mirror of
https://github.com/NomaDamas/k-skill.git
synced 2026-06-24 02:04:11 +00:00
2ff51db5d2* chore: version packages * Merge dev into main (#197) * fix(toss-securities): clarify session expiry and quote 403 handling * Clarify toss empty-output session expiry Portfolio and watchlist reads can exit successfully with empty payloads when the stored Toss session has expired. The empty-output path now verifies the session before JSON parsing and only promotes confirmed invalid auth doctor data into TossSessionExpiredError. Constraint: Scope is limited to toss-securities issue #126 follow-up on PR #192 Rejected: Treat auth doctor execution failures as expired sessions | unsupported or failing doctor output is inconclusive without parsed session.valid=false Confidence: high Scope-risk: narrow Directive: Keep empty-result session expiry classification tied to explicit auth doctor confirmation Tested: npm run test --workspace toss-securities; npm run lint --workspace toss-securities; npm run ci; manual mock tossctl blank stdout invalid/inconclusive doctor checks * Avoid false session-expiry labels for validation errors The toss wrapper now treats bare validation_error text as an upstream command failure instead of a session-expired signal. Structured auth doctor JSON remains the source of truth for empty portfolio/watchlist invalid-session promotion, while known stored-session-invalid stderr still maps to TossSessionExpiredError.\n\nConstraint: PR #192 follow-up must stay scoped to issue #126 toss-securities behavior.\nRejected: Keep validation_error in the global regex | it mislabels auth doctor transport failures and quote 403 validation errors as session expiry.\nConfidence: high\nScope-risk: narrow\nDirective: Do not broaden the free-text session classifier without regressions for auth doctor and quote upstream validation failures.\nTested: npm run lint --workspace toss-securities; npm run test --workspace toss-securities; npm run ci; manual mock tossctl validation_error checks; architect verification CLEAR\nNot-tested: Live tossctl network/auth session against real Toss upstream * Align court auction lookup with monthly site search (#196) The court auction notice page posts a YYYYMM search key from its 조회 button and returns a month of rows. Keep day inputs as a compatibility filter over the monthly response and normalize the current nested detail payload shape. Constraint: courtauction.go.kr has no public API and blocks bursty automated calls. Rejected: querying every day independently | the upstream search surface is month-based and day calls return false empty results. Confidence: high Scope-risk: narrow Directive: Preserve the site-observed YYYYMM notice search contract unless the PGJ143M01 XHR changes again. Tested: npm --workspace packages/court-auction-notice-search test; npm run ci; live 서울중앙지방법원 2026-05 notice/detail smoke lookup. Not-tested: PR CI after push. Co-authored-by: OmX <omx@oh-my-codex.dev> * Guide crawler skills toward reusable discovery (#195) * chore: version packages * Guide crawler skills toward reusable discovery Constraint: User requested insane-search-style guidance for future crawling k-skills without unrelated implementation changes. Rejected: Adding crawler code or a standalone template | too broad for a docs guidance change and risks dependency creep. Confidence: high Scope-risk: narrow Directive: Keep site-specific access details inside individual skills after a site-agnostic discovery pass. Tested: npm run ci Not-tested: Live crawler behavior; documentation-only change. * Clarify crawler skill discovery guidance Constraint: Crawling k-skills need site-dependent recipes, but should derive them through a reusable discovery pass. Rejected: Leaving guidance only in docs/adding-a-skill.md | AGENTS.md and CLAUDE.md also guide future agents. Confidence: high Scope-risk: narrow Directive: Use site-agnostic discovery to find, then explicitly package, the target site's stable access path. Tested: npm run ci Not-tested: Live crawler behavior; documentation-only change. --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Ground corporate registration guidance in official form sources Keep the consulting skill focused on draft/checklist support while pointing users to current IROS and law.go.kr form sources for submission-ready artifacts. Constraint: official registry forms can change outside the repository and must be re-downloaded at use time Rejected: committing copied official HWP/HWPX/PDF forms | they would become stale and risk misleading users Confidence: high Scope-risk: narrow Directive: do not treat Markdown templates as substitutes for official registry submission forms Tested: npm test * Ground incorporation drafting in real HWP forms Bundle official court incorporation forms plus public startup incorporation attachments, and make rhwp-filled HWP outputs the default drafting path for the corporate-registration skill. Replace the listed-company articles reference with a startup-suitable Ministry of Justice stock-company form and record source manifests for bundled binaries. Constraint: user requires actual sourced HWP templates, not generated placeholder binaries. Rejected: markdown-only drafting | it cannot produce submission-shaped Korean registry forms. Rejected: listed-company standard articles as the default reference | it is mismatched for typical startup incorporation. Confidence: high Scope-risk: moderate Directive: keep bundled HWP forms source-backed, sanitized, and edited only through copied working files. Tested: node --test scripts/skill-docs.test.js; npm run lint; k-skill-rhwp info on bundled HWP files; kordoc conversion spot checks. Not-tested: manual opening every HWP in Hancom Office and live registry submission. Co-authored-by: OmX <omx@oh-my-codex.dev> * Streamline corporate registration forms workflow Prioritize saved HWP forms for ordinary stock-company promoter incorporations, make required court-registry receipts and director identity certificates explicit, and remove the redundant markdown articles template so the skill stays HWP-first. Constraint: 법원등기소 기준 체크리스트 must include fee receipts, director seal/signature certificates, and resident-record documents. Rejected: Keeping a separate markdown articles template | duplicated the stored HWP articles workflow and encouraged non-HWP drafting. Confidence: high Scope-risk: narrow Directive: Keep corporate-registration-consulting focused on stored HWP form copies and explicit issued-document checklists. Tested: node --test --test-name-pattern 'corporate-registration-consulting' scripts/skill-docs.test.js; node --check scripts/skill-docs.test.js; ./scripts/validate-skills.sh; git diff --check Not-tested: Full npm run ci was not run because this is a skill documentation/template refactor, not release or package automation. --------- Co-authored-by: galvaomica <galvaomica@galvaomicaui-MacBookAir.local> Co-authored-by: OmX <omx@oh-my-codex.dev> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * chore: version packages (#198) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * feat(realtyprice): add address parsing and sido code mapping Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(realtyprice): use string sido codes for consistency with upstream API * feat(realtyprice): add response normalization and buildResponse Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(realtyprice): add upstream cascade fetch functions with timeout Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(realtyprice): add lookupGongsijiga orchestrator with region matching Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(realtyprice): add simple in-memory cache with TTL Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(proxy): register GET /realtyprice route with caching Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat: add gongsijiga-search SKILL.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore: add changeset for gongsijiga-search Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(realtyprice): align with actual realtyprice.kr API response format - Response wraps data in model.list (not bjdList/gsiList) - Field names are code/name (not bjd_cd/bjd_nm) - bun2 empty → send "0000" (not empty string) - eupmyeondong matching: try full string match first (API returns combined "면 리" names like "청계면 청천리") Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(gongsijiga-search): align /realtyprice route with v1 API convention - Change route from /realtyprice to /v1/realtyprice for consistency with other proxy endpoints. - Add realtypriceConfigured flag to /health upstreams. - Normalize address cache key by collapsing multiple whitespaces. - Update SKILL.md and README.md to reflect the new v1 path. * feat(gongsijiga-search): add Sejong special-city support - parseAddress: allow 3-token minimum for Sejong (no sigungu) and set sigungu to empty string. - lookupGongsijiga: skip sigungu lookup for Sejong (sidoCode 29), use fixed sggCode 36110. - Add Sejong parseAddress and lookupGongsijiga test cases. - Update SKILL.md with Sejong address format examples. * refactor(gongsijiga-search): split realtyprice.kr lookup into standalone package realtyprice.kr is a fully public endpoint that needs no API key, so per the new k-skill-proxy inclusion rule (proxy is for keyed upstreams only) the helper now ships as `gongsijiga-search` and is invoked directly from the user's machine. - new workspace package packages/gongsijiga-search/ following the blue-ribbon-nearby/coupang-product-search convention (publishConfig, files, repository, keywords) - remove /v1/realtyprice route, realtyprice.js, realtyprice.test.js, and the realtypriceConfigured health flag from k-skill-proxy - document the inclusion rule in AGENTS.md and CLAUDE.md so future skills default to direct calls when no key is required - advertise the new skill in README.md, docs/install.md, and add docs/features/gongsijiga-search.md - drop the hardcoded toss-securities lockfile version assertion that pinned a workspace version (would block changesets version-packages) and document the anti-pattern in AGENTS.md / CLAUDE.md - changesets: refresh the proxy refactor message and add a patch changeset so the new gongsijiga-search package gets published --------- Co-authored-by: Jeffrey (Dongkyu) Kim <vkehfdl1@gmail.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: galvaomica <galvaomica@galvaomicaui-MacBookAir.local> Co-authored-by: OmX <omx@oh-my-codex.dev> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
56 lines
4.9 KiB
Markdown
56 lines
4.9 KiB
Markdown
# k-skill repository instructions
|
|
|
|
This repository inherits the broader oh-my-codex guidance from the parent environment.
|
|
These rules are repo-specific and apply to everything under this directory.
|
|
|
|
## Release automation rules
|
|
|
|
- Node packages live under `packages/*` and use npm workspaces.
|
|
- Node package releases use **Changesets**. Do not hand-edit package versions only to cut a release; add a `.changeset/*.md` file instead.
|
|
- npm publish is automated from GitHub Actions and should happen only after the bot-generated **Version Packages** PR is merged into `main`.
|
|
- Python packages live under `python-packages/*` and use **release-please**. Until a real Python package exists, keep the Python release workflow as scaffold-only.
|
|
- PyPI publish should run only when release-please reports `release_created=true` for a concrete package path.
|
|
- Prefer trusted publishing via OIDC for npm and PyPI. Do not introduce long-lived registry tokens unless trusted publishing is unavailable.
|
|
|
|
## Verification rules
|
|
|
|
- For release or packaging changes, run `npm run ci`.
|
|
- Keep release docs, workflow files, and package metadata aligned in the same change.
|
|
|
|
## Testing anti-patterns
|
|
|
|
- **Never write tests that assert `.changeset/*.md` files exist.** Changesets are consumed (deleted) by `changeset version` during the release flow. Any test guarding changeset file presence will break CI on the version-bump commit and block the release pipeline.
|
|
- **Never write tests that pin a workspace package's `version` field** (in `package.json` or `package-lock.json`). `changeset version` bumps these on every release, so any hardcoded version assertion will fail the next release commit and block the npm publish pipeline. Stable invariants like `name`, `license`, `engines.node`, or workspace link metadata are fine to assert; the `version` is not.
|
|
|
|
## Development skill install rules
|
|
|
|
- When testing or developing skills from this repository, install or sync the current skill directories into the user's home-directory global skill locations first.
|
|
- Use `~/.claude/skills/<skill-name>` for Claude Code and `~/.agents/skills/<skill-name>` for agents-compatible home installs.
|
|
- Respect existing home-directory indirection such as symlinks when syncing `~/.agents/skills`.
|
|
- Do **not** create repo-local `.claude` or `.agents` directories for skill installation unless the user explicitly asks for a repository-local test fixture.
|
|
|
|
## Crawling/search skill authoring
|
|
|
|
- For any k-skill that crawls or searches a website, the expected output is a site-dependent recipe packaged into that skill.
|
|
- Before fixing that recipe, use an insane-search-style, site-agnostic discovery pass: identify public entry points, observe browser-visible data flows when needed, prefer stable public/data endpoints over brittle screen scraping, and classify login/CAPTCHA/empty/blocked responses as explicit failure modes.
|
|
- Record the discovered site-dependent access path, fallback order, inputs/outputs, and failure modes in `SKILL.md` and any helper package code. See `docs/adding-a-skill.md` for the canonical checklist.
|
|
- Do not add crawling dependencies by default; first prefer existing runtime capabilities, public endpoints, or narrow allowlisted proxy routes.
|
|
|
|
## Free API proxy policy
|
|
|
|
- The built-in `k-skill-proxy` is for **free APIs only**.
|
|
- **k-skill-proxy inclusion rule**: A skill should be served through `k-skill-proxy` **only when the upstream requires an API key** (e.g., data.go.kr, KRX, Naver Search Open API, NEIS, Data4Library). Fully public endpoints that work without any authentication (e.g., realtyprice.kr) should be called directly from the user's machine, not routed through the proxy.
|
|
- Default posture: public read-only endpoint, **no proxy auth by default**.
|
|
- Keep free-API proxy surfaces narrow, allowlisted, cache-backed, and rate-limited.
|
|
- If abuse or operational issues appear later, add stricter controls then instead of preemptively requiring auth.
|
|
|
|
## Proxy server development
|
|
|
|
- 개발 repo (`dev` 브랜치)에서 proxy 코드를 수정하고, main에 merge하면 프로덕션에 반영된다.
|
|
- 프로덕션 배포본은 `~/.local/share/k-skill-proxy`에 main 브랜치 단독 clone으로 존재한다.
|
|
- cron job (`0 * * * *`)이 매시 정각에 `~/.local/share/k-skill-proxy/scripts/auto-update-proxy.sh`를 실행해 origin/main fetch → fast-forward pull → package-lock 변경 시 npm ci → pm2 restart 순서로 자동 배포한다.
|
|
- 로그: `/tmp/k-skill-proxy-update.log`
|
|
- proxy 서버 코드: `packages/k-skill-proxy/src/server.js`
|
|
- proxy 서버 테스트: `packages/k-skill-proxy/test/server.test.js`
|
|
- proxy 환경변수(API key 등)는 `~/.config/k-skill/secrets.env`에 넣고, `scripts/run-k-skill-proxy.sh`가 source한다.
|
|
- **dev에서 route를 추가/수정한 뒤 main에 merge되기 전까지는 프로덕션 proxy에 반영되지 않는다.** 로컬 테스트는 `node packages/k-skill-proxy/src/server.js`로 직접 실행한다.
|