프론트마터 필드설계와 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의 전체 구조
SKILL.md는 YAML 형식의 frontmatter와 Markdown 형식의 본문으로 구성됩니다.
---
name: skill-name
description: "이 Skill을 사용하는 상황 설명"
argument-hint: "[인수 설명]"
allowed-tools: tool1, tool2
---
# Skill 본문
여기에 Claude에 대한 구체적인 지시를 작성한다
frontmatter는 ---로 감싸인 YAML 블록으로, Skill의 메타 정보를 정의합니다. 본문은 Claude가 실행 시 읽어 들이는 지시 내용 그 자체입니다.
frontmatter 필드 목록
SKILL.md 크기에 관한 주의사항
SKILL.md는 500행 이하로 작성할 것을 권장합니다. 상세한 참조 정보나 가이드라인은 references/ 등의 보조 파일로 분리하세요 (4장에서 설명).
또한 Skill이 많은 경우, 문자 예산 (기본값: 컨텍스트 윈도우의 2%, 폴백 16,000자)을 초과하면 일부 Skill이 로드되지 않습니다. /context 커맨드로 제외된 Skill을 확인할 수 있습니다. 상한을 변경하려면 환경 변수 SLASH_COMMAND_TOOL_CHAR_BUDGET으로 설정할 수 있습니다.
�� 팁: 한글 본문 작성 시 주의사항
한글로 본문을 작성하면 동일한 내용이라도 영문보다 바이트 수가 커질 수 있습니다.
특히 Skill을 여러 개 운용하는 경우 문자 예산을 의식하여 핵심 지시만 간결하게 작성하고,
상세 내용은 references/ 보조 파일로 분리하는 것을 권장합니다.
name 필드 명명 규칙
name은 슬래시 커맨드로 그대로 사용되므로 아래 규칙을 지켜야 합니다.
영소문자·숫자·하이픈만 사용 (최대 64자) (예: pr-review, test-gen)
짧고, 무엇을 하는지 직관적으로 알 수 있는 이름으로
팀 내에서 고유한 이름으로
생략한 경우 디렉터리명이 자동으로 사용됨
자주 하는 실수:
# 실수: 공백 포함
name: pr review
# 실수: 한글 포함
name: PR리뷰
# 실수: 언더스코어는 피할 것 (동작하는 경우도 있지만 관례적으로 하이픈 권장)
name: pr_review
# OK
name: pr-review
argument-hint 활용
argument-hint를 설정하면 슬래시 커맨드 입력 시 사용자에게 인수 가이드가 표시됩니다.
argument-hint: "[파일 경로 or PR 번호]"
사용자가 /pr-review src/main.ts처럼 인수를 붙여 호출하면, 그 인수가 Skill의 실행 컨텍스트에 전달됩니다.
SKILL.md에서 사용할 수 있는 변수
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 필드 (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
자동 실행을 비활성화하고 슬래시 커맨드를 통한 수동 호출만 허용합니다.
disable-model-invocation: true
의도치 않게 자동 실행되면 곤란한 Skill(파괴적인 조작을 포함하는 것 등)에 사용합니다.
commands와의 차이:
수동 실행만으로 제한하면 .claude/commands/의 슬래시 커맨드와 유사해집니다. 현재 commands도 동일한 frontmatter를 지원하지만, Skills에는 아래의 추가 기능이 있습니다.
"보조 파일로 Skill을 구조화하고 싶은 경우"는 Skills, "단일 .md 파일로 충분한 경우"는 commands가 적합합니다.
user-invocable
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의 frontmatter 설계
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의 규약을 기반으로 리뷰하세요라고 추가하면 사내 규칙에 맞는 리뷰가 가능합니다.
2단계: test-gen의 frontmatter 설계
.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 [조건]`
## 주의사항
- 기존 테스트 프레임워크(Jest, Vitest, pytest 등)에 맞춘다
- 목(mock)은 최소한으로 유지한다
- 테스트는 독립적으로 실행 가능하게 한다
설계 포인트 해설:
allowed-tools에 Write와 Edit를 포함하여 테스트 파일의 생성·편집을 사용자 확인 없이 자동 실행할 수 있도록 했습니다.
description은 "테스트 코드 생성"과 "테스트 추가" 양쪽을 커버하는 기술로 했습니다.
�� 한국 환경 보완
국내 프로젝트에서 자주 사용하는 테스트 프레임워크(Jest·Vitest·pytest·JUnit)별 기본 템플릿을 references/ 폴더에 미리 준비해 두면, Skill이 프레임워크를 자동으로 인식하여 더 정확한 테스트 코드를 생성합니다.
3단계: doc-gen의 frontmatter 설계
.claude/skills/doc-gen/SKILL.md를 아래 내용으로 작성하세요.
---
name: doc-gen
description: "코드의 문서 생성, API 명세서 작성, README 업데이트를 요청받았을 때"
argument-hint: "[대상 파일 또는 모듈 경로]"
allowed-tools: Read, Grep, Glob, Write, Edit
context: fork
---
# 문서 생성 Skill
지정된 코드 또는 모듈에 대한 Markdown 형식의 문서를 생성합니다.
## 절차
1. 대상 코드를 읽어 공개 API·함수·클래스를 파악한다
2. 기존 문서가 있으면 형식과 스타일을 따른다
3. 아래 구성으로 문서를 생성한다
## 문서 구성
### 함수·클래스 단위 문서
- 개요 설명
- 파라미터 목록 (타입·기본값·설명)
- 반환값 (타입·설명)
- 사용 예시
- 주의사항·제약
### 모듈 단위 문서
- 모듈의 목적과 책임
- 의존 관계
- 주요 익스포트 목록
- 사용 가이드
## 출력 위치
- 문서는 `docs/` 디렉터리에 배치한다
- 파일명은 대상 모듈명에 맞춘다 (예: `docs/auth-module.md`)
설계 포인트 해설:
context: fork를 지정했습니다. 문서 생성은 독립된 작업이며 메인 대화 컨텍스트를 오염시키지 않는 것이 편리합니다.
allowed-tools에 Bash를 포함하지 않았습니다. 문서 생성에 커맨드 실행은 통상 불필요하므로, Bash 실행 시에는 사용자 확인이 필요합니다 (단, 승인하면 사용 가능합니다).
4단계: frontmatter 차이 비교·확인
3가지 Skill의 frontmatter를 나란히 비교하여 설계 의도를 확인합니다.
cd ~/dev-workflow-skills
claude
Claude Code 내에서 다음과 같이 확인할 수 있습니다.
> 3가지 Skill의 frontmatter를 비교하여 각각의 설계 방침 차이를 설명해 줘
예상 출력 포인트:
5단계: 자주 하는 실수와 대처법
frontmatter 작성 시 자주 하는 실수를 실제로 시도하여 오류 동작을 확인해 봅시다.
실수 1: frontmatter 닫기 누락
---
name: broken-skill
description: "테스트"
# 이것은 동작하지 않는다
본문이 frontmatter의 일부로 해석된다
닫는 ---가 없으면 파일 전체가 frontmatter로 해석되어 Skill이 올바르게 동작하지 않습니다.
실수 2: YAML 구문 오류
---
name: broken-skill
description: PR 리뷰 (괄호를 포함하는 문자열은 따옴표가 필요)
---
description 값에 괄호나 콜론 등 YAML 특수 문자가 포함되는 경우 큰따옴표로 감싸야 합니다.
# 올바른 작성법
description: "PR 리뷰 (코드 품질 체크)"
실수 3: allowed-tools 기법 실수
# 실수: 문자열로 기술
allowed-tools: "Read, Grep, Glob"
# OK: 쉼표 구분으로 기술
allowed-tools: Read, Grep, Glob
�� 추가 주의사항
YAML 파일에 한글을 포함하는 경우 파일 인코딩이 UTF-8인지 반드시 확인하세요. 특히 Windows 환경의 WSL2에서 작업하는 경우, 에디터에서 저장 시 인코딩 설정에 주의가 필요합니다.
따라하기
model 필드 활용
disable-model-invocation의 판단
정리
SKILL.md는 YAML frontmatter와 Markdown 본문으로 구성됨
name(권장)은 슬래시 커맨드명이 되며, 영소문자와 하이픈으로 명명함 (생략 시 디렉터리명이 사용됨)
description(권장)은 자동 실행의 트리거 조건으로, 구체적으로 "언제 사용하는가"를 기술함
allowed-tools로 자동 실행할 도구의 범위를 제어할 수 있음 (목록 외 도구는 사용자 확인이 필요하지만, 승인하면 사용 가능)
context: fork로 독립 컨텍스트 실행이 가능하며, 컨텍스트 오염을 방지할 수 있음
3가지 Skill은 각각의 목적에 맞게 자동 실행 범위와 컨텍스트를 구분하여 설계함
©2024-2026 MDRules dev., Hand-crafted & made with Jaewoo Kim.
이메일문의: jaewoo@mdrules.dev
AI강의/개발/기술자문, AI 업무 자동화 컨설팅 문의: https://talk.naver.com/ct/w5umt5
AI 업무 자동화/에이전트/워크플로우설계 컨설팅/AI교육: https://mdrules.dev