k-skill

# k-skill

## 통합 CLI 스킬 instruction

- 모든 top-level 스킬의 원본은 `skill.json`(frontmatter/profile)과 `instruction.md`(사이트별 workflow)다.
- `SKILL.md`는 생성된 CLI adapter stub이므로 직접 수정하지 않는다.
- source 변경 후 `npm run generate:skill-stubs`와 `npm run sync:cli-skills`를 실행한다.
- 번들 helper는 `k-skill exec`, reference는 `k-skill read`로 접근한다. 상대 `scripts/`·`references/` 경로는 `npm run migrate:cli-assets`로 정규화한다.
- 에이전트는 CLI 도구를 쓰기 전에 `npx -y @nomadamas/k-skill@0 update` 로 CLI와 Vercel Agent Skills(`~/.agents/skills`)를 포함한 모든 코딩 에이전트 스킬 설치를 맞춘다. 이 한 줄은 `packages/k-skill-cli/templates/core.md`와 생성된 `SKILL.md` stub이 넣으므로 `instruction.md`에 복제하지 않는다.
- 공통 runtime 규칙은 `packages/k-skill-cli/templates/*.md`에서 profile 단위로 관리하고 `instruction.md`에 복제하지 않는다.
- 돌쇠 credential mode는 `DOLSHOI_ACTION_BROKER_URL`과 실행 가능한 `vault-run`이 모두 있을 때만 활성화한다. 이 모드에서는 평문 credential을 묻거나 읽지 말고 `vault-run`, 누락 시 `request_vault_credential`을 사용한다.
- CloakBrowser 감지는 credential mode와 독립적이다. 내장 browser tool이 CloakBrowser를 제공하거나 `CLOAKBROWSER_PEEK_TOKEN`이 있으면 내장 browser tool을 최우선으로 사용한다.
- 공식 표면이 합법적으로 지원하는 사용자 요청은 조회에서 멈추지 말고 가역적 준비와 실제 액션까지 수행한다. 결제, 메시지 전송, 최종 제출, 취소 등 비가역 외부 효과 직전에는 `clarify`로 정확한 대상과 효과를 승인받는다.
- 법률, 현장 방문, CAPTCHA, 본인인증, 전자서명, 사이트 미지원 경계는 유지하며 가능한 가장 가까운 공식 단계까지 수행한다.

## 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.

## Crawling/search skill authoring

- 크롤링/검색 k-skill의 목표는 최종적으로 대상 사이트에 맞는 site-dependent 접근 방법을 스킬에 패키징하는 것이다.
- 다만 방법을 고정하기 전에 `insane-search`식 site-agnostic discovery를 먼저 수행한다: 공개 입구, 브라우저에서 보이는 데이터 흐름, RSS/sitemap/정적 JSON/모바일 페이지, 차단·빈 응답·로그인벽 실패 모드를 확인한다.
- 발견한 검색 URL, 필수 입력값, 결과 해석 규칙, fallback 순서, 실패 모드는 `SKILL.md`와 helper 코드에 명확히 남긴다. 자세한 체크리스트는 `docs/adding-a-skill.md`를 따른다.
- 새 크롤링 dependency는 기본값으로 추가하지 말고 기존 기능, 공개 endpoint, 좁은 proxy route로 해결 가능한지 먼저 확인한다.

## Proxy server development

- 개발 repo: 이 디렉토리, `dev` 브랜치
- 프로덕션 배포 대상: **gpu01**의 systemd user service (custom domain `k-skill-proxy.nomadamas.org`)
- `main` 브랜치에 merge되면 gpu01 cron이 `origin/main`을 감지하고 테스트, 백업, systemd 재시작, local/public `/health` smoke test를 수행한다.
- 프로덕션 시크릿은 gpu01 app directory의 `.env`에서 runtime에 주입된다. 자동 배포와 운영 절차는 `docs/deploy-k-skill-proxy.md` 참고.
- 따라서 proxy route 변경은 **main에 merge되어야 프로덕션에 반영**된다. dev에서 코드를 바꿔도 프로덕션 proxy에는 영향 없음.
- 로컬 테스트는 `node packages/k-skill-proxy/src/server.js` 로 직접 실행하거나 `node --test packages/k-skill-proxy/test/server.test.js` 로 확인.
- **Proxy 편입 규칙**: k-skill-proxy에 route를 추가하려면 upstream이 API 키를 필요로 해야 한다. 공개 엔드포인트(키 불필요)는 skill 코드에서 직접 호출하고 프록시를 거치지 않는다.

More agent context in NomaDamas/k-skill

132 other files this repository gives its agents, the first 60 shown.