02화 프론트마터 필드설계와 3가지 Skill 실전구현 - 브런치

allowed-tools·context·fork 설정법 SKILL.md의 전체 구조 (frontmatter + 본문) 이해 frontmatter 각 필드(name / description / argument-hint / allowed-tools / model / disable-model-invocation)의 역할과 작성법 실행 컨텍스트(메인 / fork)의 동작 원리와 구분 사용 3가지 Skill(pr-review / test-gen / doc-gen)의 frontmatter 본격 설계 1장을 완료하여 Skills의 개념과 기본 구조를 이해하고 있을 것 ~/dev-workflow-skills/.claude/skills/ 하위에 pr-review/, test-gen/, doc-gen/ 디렉터리가 생성되어 있을 것 1장에서 작성한 최소 구성의 pr-review/SKILL.md 동작 확인이 완료되어 있을 것 frontmatter의 전 필드 의미와 작성법을 올바르게 설명할 수 있다 목적에 맞게 적절한 필드를 선택하고 올바른 frontmatter를 작성할 수 있다 3가지 Skill 각각에 맞는 frontmatter를 설계·구현할 수 있다 SKILL.md는 YAML 형식의 frontmatter와 Markdown 형식의 본문으로 구성됩니다. --- name: skill-name description: "이 Skill을 사용하는 상황 설명" argument-hint: "[인수 설명]" allowed-tools: tool1, tool2 --- # Skill 본문 여기에 Claude에 대한 구체적인 지시를 작성한다 frontmatter는 ---로 감싸인 YAML 블록으로, Skill의 메타 정보를 정의합니다. 본문은 Claude가 실행 시 읽어 들이는 지시 내용 그 자체입니다. SKILL.md는 500행 이하로 작성할 것을 권장합니다. 상세한 참조 정보나 가이드라인은 references/ 등의 보조 파일로 분리하세요 (4장에서 설명). 또한 Skill이 많은 경우, 문자 예산 (기본값: 컨텍스트 윈도우의 2%, 폴백 16,000자)을 초과하면 일부 Skill이 로드되지 않습니다. /context 커맨드로 제외된 Skill을 확인할 수 있습니다. 상한을 변경하려면 환경 변수 SLASH_COMMAND_TOOL_CHAR_BUDGET으로 설정할 수 있습니다. �� 팁: 한글 본문 작성 시 주의사항 한글로 본문을 작성하면 동일한 내용이라도 영문보다 바이트 수가 커질 수 있습니다. 특히 Skill을 여러 개 운용하는 경우 문자 예산을 의식하여 핵심 지시만 간결하게 작성하고, 상세 내용은 references/ 보조 파일로 분리하는 것을 권장합니다. name은 슬래시 커맨드로 그대로 사용되므로 아래 규칙을 지켜야 합니다. 영소문자·숫자·하이픈만 사용 (최대 64자) (예: pr-review, test-gen) 짧고, 무엇을 하는지 직관적으로 알 수 있는 이름으로 팀 내에서 고유한 이름으로 생략한 경우 디렉터리명이 자동으로 사용됨 # 실수: 공백 포함 name: pr review # 실수: 한글 포함 name: PR리뷰 # 실수: 언더스코어는 피할 것 (동작하는 경우도 있지만 관례적으로 하이픈 권장) name: pr_review # OK name: pr-review argument-hint를 설정하면 슬래시 커맨드 입력 시 사용자에게 인수 가이드가 표시됩니다. argument-hint: "[파일 경로 or PR 번호]" 사용자가 /pr-review src/main.ts처럼 인수를 붙여 호출하면, 그 인수가 Skill의 실행 컨텍스트에 전달됩니다. SKILL.md 본문 내에서는 아래의 변수 플레이스홀더를 사용할 수 있습니다. Skill 실행 시 실제 값으로 치환됩니다. --- name: review-file description: "특정 파일의 리뷰를 요청받았을 때" argument-hint: "[파일 경로]" allowed-tools: Read, Grep, Glob --- # 파일 리뷰 대상 파일: $0 `${CLAUDE_SKILL_DIR}/references/coding-standards.md`의 규약을 기반으로 리뷰해 주세요. �� 국내 활용 팁 ${CLAUDE_SKILL_DIR}을 활용하면 사내 코딩 컨벤션 문서, 보안 체크리스트 등을 references/ 폴더에 두고 Skill에서 동적으로 참조할 수 있습니다. Confluence나 Notion에서 내보낸 Markdown 파일을 그대로 활용할 수 있어 편리합니다. Skill은 기본적으로 메인 대화 컨텍스트 내에서 실행됩니다. context: fork를 지정하면 독립된 컨텍스트에서 실행되어 메인 대화 기록을 오염시키지 않습니다. context: fork agent 필드를 지정하면 context: fork로 실행되는 서브에이전트의 종류를 선택할 수 있습니다. --- name: pr-summary description: "PR의 변경 내용을 요약할 때" context: fork agent: Explore allowed-tools: Bash(gh *) --- 내장 서브에이전트로는 Explore(코드베이스 탐색에 특화)나 Plan(설계·계획에 특화) 등을 이용할 수 있습니다. agent를 지정하면 자동으로 context: fork로 처리됩니다. 자동 실행을 비활성화하고 슬래시 커맨드를 통한 수동 호출만 허용합니다. disable-model-invocation: true 의도치 않게 자동 실행되면 곤란한 Skill(파괴적인 조작을 포함하는 것 등)에 사용합니다. 수동 실행만으로 제한하면 .claude/commands/의 슬래시 커맨드와 유사해집니다. 현재 commands도 동일한 frontmatter를 지원하지만, Skills에는 아래의 추가 기능이 있습니다. "보조 파일로 Skill을 구조화하고 싶은 경우"는 Skills, "단일 .md 파일로 충분한 경우"는 commands가 적합합니다. disable-model-invocation과 반대로, 사용자의 수동 호출을 비표시로 하고 Claude의 자동 실행만 허용하는 설정입니다. user-invocable: false / 메뉴에 표시되지 않게 되지만, Claude는 description을 기반으로 자동으로 이 Skill을 사용할 수 있습니다. 호출 제어 조합 정리: user-invocable: false는 사용자가 직접 호출할 필요는 없지만, Claude가 문맥에 따라 자동으로 참조해 줬으면 하는 지식베이스형 Skill에 적합합니다. �� 국내 활용 사례 - 사내 보안 정책 문서를 user-invocable: false Skill로 등록해 두면, Claude가 코드 리뷰 시 자동으로 참조하여 보안 지적을 강화할 수 있습니다. - 레거시 시스템의 독자적인 사양이나 특수 데이터 포맷 설명을 Skill로 등록하면, 관련 질문 시 Claude가 자동으로 참조합니다. 1장에서 작성한 최소 구성의 pr-review/SKILL.md를 본격적인 frontmatter로 다시 작성합니다. .claude/skills/pr-review/SKILL.md를 아래 내용으로 업데이트하세요. --- name: pr-review description: "PR 리뷰나 코드 리뷰를 요청받았을 때, 변경 내용을 분석하여 리뷰 코멘트를 생성한다" argument-hint: "[대상 파일 경로 or 변경 내용 설명]" allowed-tools: Read, Grep, Glob, Bash --- # PR 리뷰 Skill 당신은 시니어 엔지니어로서 코드 변경 사항을 리뷰합니다. ## 리뷰 절차 1. 지정된 파일 또는 최근 변경 차분을 확인한다 2. 아래 관점에서 리뷰 코멘트를 생성한다 - **정확성**: 로직 오류, 경계 조건 누락 - **보안**: 입력 검증, 인증·인가 누락 - **성능**: 불필요한 루프, N+1 문제 - **가독성**: 명명, 함수 분할, 주석의 적절성 - **테스트**: 테스트 커버리지 부족 3. 각 지적에 중요도(`Critical` / `Warning` / `Info`)를 부여한다 ## 출력 형식 ### [중요도] 지적 제목 - 파일: `path/to/file.ts` (L행 번호) - 문제: 구체적인 문제 설명 - 제안: 개선안 allowed-tools에 Read, Grep, Glob, Bash를 지정하여 이 도구들은 사용자 확인 없이 자동 실행됩니다. 리뷰는 코드를 변경하지 않으므로 Write나 Edit는 포함하지 않았습니다 (목록 외 도구는 실행 시 사용자 확인이 필요하지만, 승인하면 사용 가능합니다). argument-hint로 파일 경로 또는 변경 내용 설명을 받을 수 있도록 했습니다. �� 한국 환경 보완 사내 코딩 컨벤션이 있다면 references/coding-standards.md를 만들어 두고 본문에 ${CLAUDE_SKILL_DIR}/references/coding-standards.md의 규약을 기반으로 리뷰하세요라고 추가하면 사내 규칙에 맞는 리뷰가 가능합니다. .claude/skills/test-gen/SKILL.md를 아래 내용으로 작성하세요. --- name: test-gen description: "테스트 코드 생성이나 기존 코드에 대한 테스트 추가를 요청받았을 때" argument-hint: "[대상 소스 파일 경로]" allowed-tools: Read, Grep, Glob, Bash, Write, Edit --- # 테스트 생성 Skill 지정된 소스 코드에 대한 테스트 코드를 생성합니다. ## 절차 1. 대상 파일을 읽어 함수·클래스의 구조를 파악한다 2. 기존 테스트 파일이 있으면 확인하여 테스트 프레임워크와 작성법을 맞춘다 3. 아래 종류의 테스트를 생성한다 - 정상 케이스 (기대하는 입출력) - 비정상 케이스 (오류 케이스, 경계값) - 엣지 케이스 (빈 입력, 최댓값, null/undefined) 4. 테스트 파일을 대상 파일과 같은 디렉터리 또는 테스트 디렉터리에 배치한다 ## 테스트 명명 규칙 - 테스트 파일: `대상파일명.test.확장자` 또는 `대상파일명.spec.확장자` - 테스트 케이스: `should [기대 동작] when [조건]` ## 주의사항 - 기존 테스트 프레임워크(Je