nomadamas__k-skill/CONTRIBUTING.md

기여 가이드

외부 기여자는 이 문서를 기준으로 이슈, PR, 스킬, 패키지, 프록시 변경을 준비해 주세요. 이 레포의 세부 운영 규칙은 AGENTS.md와 CLAUDE.md에도 있으며, 충돌할 때는 더 구체적인 최신 지침을 우선합니다.

소통 언어

• PR 코멘트, 이슈, 리뷰 등 모든 소통은 한국어로 진행합니다.
• 외부 문서나 로그를 인용해야 할 때는 원문을 함께 둘 수 있지만, 결정 사항과 요청 사항은 한국어로 요약해 주세요.

브랜치와 PR 대상

• 기능/수정 브랜치는 가능한 한 feature/<issue-number> 또는 feature/#<issue-number>처럼 추적 가능한 이름을 사용합니다.
• PR의 대상 브랜치는 반드시 dev 브랜치여야 합니다.
• main 브랜치로 PR을 만들 수 있는 사람은 @vkehfdl1뿐입니다. 그 외 기여자는 main 대상 PR을 만들지 않습니다.
• 프록시 서버 변경도 개발 레포의 dev 브랜치에서 작업하고, main에 머지된 뒤에만 프로덕션에 반영됩니다.

스킬 추가 또는 변경

스킬을 추가하거나 변경할 때는 관련 기능 문서와 README.md의 표를 포함해 코드와 문서를 함께 갱신합니다.

• top-level 스킬의 source of truth는 skill.json과 instruction.md입니다. skill.json에는 name, description, frontmatter, profiles를 두고 instruction.md에는 사이트별 workflow만 둡니다.
• SKILL.md는 scripts/generate-skill-stubs.js가 생성하는 CLI adapter stub입니다. 직접 수정하지 않습니다.
• 공통 runtime 규칙은 packages/k-skill-cli/templates/*.md에서 profile 단위로 관리합니다. vault/browser/action/legal/operations 규칙을 각 instruction.md에 복제하지 않습니다.
• source를 수정한 뒤 npm run generate:skill-stubs와 npm run sync:cli-skills를 실행하고 두 명령의 --check가 통과하는지 확인합니다.
• helper 실행은 npx -y @nomadamas/k-skill@0 exec <skill> scripts/<file> -- ..., reference 조회는 ... read <skill> references/<file> 형식으로 작성합니다. npm run migrate:cli-assets와 node scripts/migrate-cli-asset-instructions.js --check로 상대경로가 남지 않았는지 확인합니다.
• 액션이 가능한 스킬은 돌쇠에서 조회 링크만 반환하지 말고 공식 표면을 이용해 장바구니, 예약, 초안, 연락 준비 등 가역적 단계까지 실행합니다. 결제, 메시지 전송, 최종 제출, 취소 같은 비가역 외부 효과 직전에는 clarify 승인을 받습니다.
• 법률상 금지, 현장 방문 필수, CAPTCHA, 본인인증, 전자서명, 공식 사이트 미지원 경계는 제거하지 않습니다. 이런 경우에는 가능한 가장 가까운 합법적 공식 단계까지 수행하도록 완료 기준을 씁니다.
• 관련 기능 문서(docs/features/<skill-name>.md)를 추가하거나 업데이트합니다.
• README.md의 "어떤 걸 할 수 있나" 표에 스킬 이름, 설명, 사용자 로그인 필요 여부, 문서 링크를 업데이트합니다.
• 설치 흐름이 바뀌면 docs/install.md, docs/setup.md, docs/security-and-secrets.md 등 관련 문서도 함께 맞춥니다.
• 출처나 공식 표면이 바뀌면 docs/sources.md에 반영합니다.
• 스킬 개발/테스트 시에는 현재 스킬 디렉터리를 먼저 홈 디렉터리 전역 스킬 위치에 동기화합니다.
  • Claude Code: ~/.claude/skills/<skill-name>
  • agents 호환 런타임: ~/.agents/skills/<skill-name>
• ~/.agents/skills가 symlink 등으로 우회되어 있으면 기존 indirection을 존중합니다.
• 사용자가 명시적으로 요청하지 않는 한 레포 내부에 .claude 또는 .agents 설치 테스트 디렉터리를 만들지 않습니다.

npm 패키지와 릴리스

• Node 패키지는 packages/* 아래 npm workspaces로 관리합니다.
• npm 패키지를 수정할 때는 Changesets를 조사하고, 자동 CD가 올바르게 트리거되도록 .changeset/*.md 변경이 필요한지 신중히 판단합니다.
• 패키지 릴리스 목적의 버전 변경은 package.json만 직접 수정하지 말고 Changesets 흐름을 사용합니다.
• npm publish는 GitHub Actions가 생성하는 Version Packages PR이 main에 머지된 뒤 자동으로 수행되는 것을 전제로 합니다.
• Changeset 파일의 존재 여부를 테스트로 검증하지 않는다. Changesets는 changeset version 단계에서 소비되어 삭제될 수 있으므로, 그런 테스트는 버전 bump 커밋의 CI를 막습니다.
• package.json과 package-lock.json의 version 필드를 테스트에서 고정하지 않는다. Changesets 릴리스 흐름에서 매번 바뀔 수 있으므로, 테스트는 name, license, engines.node, workspace link metadata처럼 안정적인 invariant를 검증합니다.
• 현재 구현이 registry token 기반인 경우에도 신규 또는 재설계 흐름은 trusted publishing/OIDC를 우선합니다. 기존 token 기반 경로를 고칠 때는 현재 구현 예외와 목표 원칙을 PR 설명에 분리해 적습니다.

Python 패키지와 PyPI

• Python 패키지는 python-packages/* 아래에 둡니다.
• Python 릴리스는 release-please 기반입니다.
• 실제 Python 패키지가 생기기 전까지 Python release workflow는 scaffold-only로 유지합니다.
• PyPI publish는 release-please가 구체적인 패키지 경로에 대해 release_created=true를 보고할 때만 실행되도록 설계합니다.
• PyPI도 가능하면 trusted publishing/OIDC를 우선합니다.

API와 k-skill-proxy 정책

• k-skill-proxy는 무료 API 전용입니다.
• 신규 proxy route는 upstream이 API key를 요구하는 무료 API인 경우에만 k-skill-proxy 경유를 검토합니다. 기존 승인 예외를 넓히려면 근거와 운영 경계를 문서화합니다.
• 인증 없이 동작하는 공개 read-only endpoint는 기본적으로 사용자 머신에서 직접 호출하고, 불필요하게 프록시 운영 표면을 넓히지 않습니다.
• 유료 API, 사용자별 과금 API, 개인 계정 권한이 필요한 API는 k-skill-proxy를 타지 않도록 설계합니다.
• 기본 자세는 공개 read-only endpoint, proxy auth 없음입니다.
• 프록시 표면은 좁게 유지하고 allowlist, cache, rate limit를 적용합니다.
• 남용이나 운영 문제가 실제로 나타나면 그때 더 강한 제어를 추가합니다.

프록시 서버 개발과 배포

• 프록시 서버 코드: packages/k-skill-proxy/src/server.js
• 프록시 서버 테스트: packages/k-skill-proxy/test/server.test.js
• 컨테이너 이미지 정의: packages/k-skill-proxy/Dockerfile
• 로컬 테스트: 필요한 upstream 환경변수를 export한 상태에서 node packages/k-skill-proxy/src/server.js. 로컬에서 시크릿을 모아두는 표준 위치는 ~/.config/k-skill/secrets.env 입니다.
• 프로덕션 프록시는 gpu01의 systemd user service에서 운영하며 Cloudflare Tunnel을 통해 k-skill-proxy.nomadamas.org에 노출됩니다.
• main 브랜치에 머지되면 gpu01 cron이 origin/main을 감지해 테스트, 백업, systemd 재시작, local/public /health smoke test를 자동 수행합니다.
• 프로덕션 시크릿은 gpu01 app directory의 .env에서 runtime에 주입됩니다. 자동 배포와 운영 점검 절차는 docs/deploy-k-skill-proxy.md에 정리되어 있습니다.
• dev에서 route를 추가하거나 수정해도 main에 머지되기 전까지는 프로덕션 프록시에 반영되지 않습니다.

검증

• 문서만 바꿔도 관련 문서 테스트를 먼저 추가하거나 업데이트하고, 실패를 확인한 뒤 구현하는 TDD 흐름을 권장합니다.
• npm run lint / npm test / npm run pack:dry-run은 scripts/run-*.js가 파일 목록을 glob으로 수집합니다. 새 helper나 테스트를 추가할 때 루트 package.json 스크립트 문자열을 손으로 늘리지 않습니다.
• npm run lint가 모든 top-level 스킬의 stub/source/bundle 정합성과 profile 유효성을 검증하는지 확인합니다.
• 일반 변경은 가능한 한 npm run lint, npm run typecheck, npm test를 실행합니다.
• 릴리스나 패키징 관련 변경은 npm run ci를 실행합니다.
• 변경 범위가 작더라도 최종 보고에는 어떤 명령을 실행했고 어떤 결과가 나왔는지 적습니다.
• 테스트를 통과시키기 위해 기존 테스트를 삭제하거나 범위를 부당하게 줄이지 않습니다.