Claude Code skill 작성 방식 - 버전에 따라 바뀔 수 있음 (261005)

About this offer

1. 기본 구조 Skill은 폴더 하나와 그 안의 SKILL.md 로 구성됩니다. 프로젝트용은 .claude/skills/ 에, 개인 전역용은 ~/.claude/skills/ 에 둡니다. .claude/skills/ └── code-review/ # 폴더명 = name (kebab-case) ├── SKILL.md # 필수 (대문자) ├── reference.md # 선택: 상세 문서 └── scripts/ # 선택: 보조 스크립트 .claude/skills/<skill-name>/SKILL.md 를 만들고, name 은 디렉터리명과 일치해야 합니다. 폴더명은 소문자, 숫자, 하이픈만 쓰고, 파일명 SKILL.md 는 반드시 대문자입니다. 2. Frontmatter (공식 필수 필드) 파일 맨 위에 --- 로 감싼 YAML 블록을 두며, 필수 필드는 두 개입니다. --- name: code-review description: 코드 변경사항을 리뷰한다. 사용자가 "리뷰해줘", "PR 검토", "코드 점검"을 요청할 때 사용. --- 필드 역할 name Claude Code에서 /슬래시 명령어 가 됩니다. description Claude가 이 skill을 언제 로드할지 판단하는 기준입니다. description 이 가장 중요합니다. Claude는 이 문장을 보고 skill을 자동으로 호출할지 결정하기 때문입니다. 그래서 다음을 지키는 것이 좋습니다. 무엇을 하는지 + 언제 쓰는지 를 함께 적습니다. 구체적인 트리거 문구를 포함합니다. 사용자가 실제로 쓸 법한 표현을 넣으세요. 너무 모호한 설명(예: "코드 도움")은 오작동의 원인이 됩니다. allowed-tools 같은 선택 필드도 있는 것으로 보이지만, 이번 검색에서는 공식 문서 원문을 직접 확인하지 못했습니다. 정확한 목록은 공식 문서(docs.claude.com)를 확인해 주세요. 3. 본문(Body) 작성: Goal / Instructions / Constraints Goal, Instructions, Constraints는 공식 예약 키워드가 아니라 관례적인 섹션 이름입니다. 본문은 자유로운 Markdown이며, 아래 구조가 Claude가 따르기 쉬워서 많이 쓰입니다. 섹션 내용 Goal 이 skill이 달성할 최종 결과물 When to use 적용 상황, 입력 조건 (description 보완) Instructions 순서가 있는 단계별 작업 절차 Constraints 하지 말아야 할 것, 지켜야 할 규칙, 범위 제한 Output format 결과물 형식, 템플릿 Examples 입력/출력 예시 작성 팁은 다음과 같습니다. 로딩 방식을 이해하세요. frontmatter(name, description)는 항상 로드되고, 본문은 트리거될 때만 로드됩니다. 이를 progressive disclosure라고 부릅니다. 본문을 짧게 유지하세요. SKILL.md는 500줄 미만으로 유지하고, 상세 내용(DB 스키마, API 문서 등)은 별도 참조 파일로 분리하는 것이 권장됩니다. 본문에서 상대 경로로 링크하면 됩니다. 지시는 " 하지 마라"보다 " 해라"처럼 명확하고 검증 가능하게 쓰고, 금지 사항은 Constraints에 모읍니다. 4. 자주 쓰이는 Skill 예시 예시 1: 코드 리뷰 --- name: code-review description: 변경된 코드를 리뷰하고 개선점을 제안한다. "코드 리뷰", "PR 검토", "변경사항 점검" 요청 시 사용. --- # Code Review ## Goal 변경된 코드의 버그, 보안 이슈, 가독성 문제를 찾아 우선순위별로 보고한다. ## Instructions 1. `git diff`로 변경 범위를 확인한다. 2. 변경된 파일을 읽고 주변 코드 맥락을 파악한다. 3. 다음 관점으로 점검한다: 로직 오류 → 보안 → 성능 → 가독성 → 테스트 누락 4. 결과를 아래 출력 형식으로 정리한다. ## Constraints - 요청 없이 코드를 직접 수정하지 않는다. - 변경되지 않은 파일은 지적하지 않는다. - 취향 차이 수준의 스타일 지적은 최소화한다. ## Output format - 🔴 Critical / 🟡 Suggestion / 🟢 Good 로 분류 - 각 항목: `파일:라인` – 문제 – 제안 예시 2: 커밋 메시지 작성 --- name: commit-message description: 스테이징된 변경사항으로 Conventional Commits 형식의 커밋 메시지를 작성한다. "커밋 메시지", "commit" 요청 시 사용. --- ## Goal 프로젝트 컨벤션에 맞는 커밋 메시지를 생성한다. ## Instructions 1. `git diff --staged`로 변경 내용을 확인한다. 2. `type(scope): subject` 형식으로 작성한다. (feat, fix, docs, refactor, test, chore) 3. 필요하면 본문에 "왜 변경했는지"를 적는다. ## Constraints - subject는 50자 이내, 마침표 없이 작성한다. - 직접 `git commit`을 실행하지 말고 메시지만 제안한다. 예시 3: 테스트 작성 --- name: write-tests description: 지정한 함수나 모듈의 단위 테스트를 작성한다. "테스트 작성", "테스트 추가", "커버리지 보강" 요청 시 사용. --- ## Goal 기존 테스트 스타일에 맞춰 의미 있는 테스트를 추가한다. ## Instructions 1. 프로젝트의 기존 테스트 파일에서 프레임워크와 네이밍 규칙을 파악한다. 2. 정상 케이스, 경계값, 예외 케이스 순으로 작성한다. 3. 작성 후 테스트를 실행해 통과 여부를 확인한다. ## Constraints - 프로덕션 코드는 수정하지 않는다. - 외부 네트워크 호출은 mock 처리한다. 그 밖에 자주 만드는 유형으로 PR 설명 작성, 릴리스 노트 생성, DB 마이그레이션 점검, 프로젝트 코딩 컨벤션 가이드, 문서 감사(audit) 등이 있습니다. 5. 실무 체크리스트 name 이 폴더명과 일치하는가 (kebab-case) description 에 기능 + 트리거 문구 가 모두 들어 있는가 한 skill이 한 가지 일만 하는가 (큰 작업은 분리) 본문이 500줄 이하이고, 상세 내용은 별도 파일로 뺐는가 Constraints에 금지 사항과 범위를 명시했는가