SKILL.md 작성법: 나만의 Skills 만들기

앞 편 도메인 지식과 컨텍스트에서 무엇을 어떤 형태로 담을지 정했으니, 이번에는 실제로 파일을 만듭니다. SKILL.md의 위치와 필드, 좋은 description의 조건, 도구 권한 필드, 그리고 Anthropic 공식 skill-creator 플러그인에 Skill 작성을 시켜 보는 실습입니다. 읽고 나면 여러분 업무 절차 하나를 오늘 Skill로 옮길 수 있습니다. 다음 편 Skills vs 서브에이전트에서 서브에이전트와의 역할 분담을 다룹니다.

핵심 요약

• 개인용은 ~/.claude/skills/<이름>/SKILL.md, 프로젝트용은 .claude/skills/<이름>/SKILL.md. 폴더 이름이 곧 /명령 이름입니다.
• frontmatter 필드는 전부 선택이고 description만 권장입니다. 이 한 줄이 자동 호출을 결정합니다.
• allowed-tools는 권한 확인 없이 쓸 도구를 미리 승인하고, disallowed-tools는 도구를 아예 빼 버립니다.
• disable-model-invocation: true는 배포처럼 사람이 타이밍을 정해야 하는 Skill에 붙입니다.
• skill-creator 플러그인은 Skill 초안 작성과 있음·없음 벤치마크까지 대신합니다.

Skills는 어디에 두나

Skill은 SKILL.md를 품은 폴더입니다. 어디에 두느냐가 누가 쓰느냐를 정합니다.

macOS에서는 ~가 /Users/<사용자>, Windows에서는 C:\Users\<사용자>입니다. 터미널에서 폴더를 만드는 명령은 이렇습니다.

# macOS
mkdir -p ~/.claude/skills/meeting-notes

# Windows PowerShell
New-Item -ItemType Directory -Force "$HOME\.claude\skills\meeting-notes"

우리 팀은 배포 Skill을 프로젝트의 .claude/skills/에 두고 커밋합니다. 그 저장소를 여는 사람 누구나 같은 배포 절차를 갖게 하려는 의도입니다. 반대로 채점 루프 Skill은 어느 프로젝트에서든 쓰므로 ~/.claude/skills/에 있습니다. 같은 이름이 겹치면 조직이 개인을, 개인이 프로젝트를 덮습니다. 파일을 고치면 재시작 없이 현재 세션에 반영되지만, 세션 시작 전에 없던 최상위 skills 폴더를 새로 만든 경우에는 한 번 재시작해야 합니다.

SKILL.md는 어떻게 생겼나

위쪽 --- 사이가 YAML frontmatter, 아래가 마크다운 본문입니다. 1주차 실습 "녹음을 회의록으로"를 그대로 옮기면 이렇습니다.

---
name: meeting-notes
description: 녹음 전사 텍스트를 회의록 양식으로 정리합니다. "회의록 만들어", "전사본 정리", "녹음 정리" 요청 시 사용합니다.
argument-hint: [전사 파일 경로]
---

$ARGUMENTS 파일을 읽고 다음 순서로 정리합니다.

1. 참석자·일시·안건을 표로 뽑는다.
2. 결정 사항은 담당자·기한과 함께 번호 목록으로 쓴다.
3. 고객 실명은 홍OO 형태로 가린다.
4. 결과는 같은 폴더에 `회의록-YYYY-MM-DD.md`로 저장한다.

/meeting-notes 녹음/0827.txt라고 입력하면 $ARGUMENTS 자리에 경로가 들어갑니다. 인수를 여러 개 받을 때는 $0, $1처럼 위치로 꺼낼 수 있습니다.

핵심 필드

공식 문서 기준으로 모든 필드는 선택입니다. 실무에서 자주 쓰는 것만 추립니다.

name은 폴더 이름과 달라도 되지만 /뒤에 입력하는 명령은 폴더 이름을 따릅니다. 헷갈리지 않게 둘을 같게 두는 것을 권합니다.

좋은 description은 무엇이 다른가

나쁜 예: "회의록 도우미". 좋은 예: "녹음 전사 텍스트를 회의록 양식으로 정리합니다. '회의록 만들어', '전사본 정리' 요청 시 사용합니다." 차이는 둘입니다. 무엇을 하는지가 동사로 있고, 사용자가 실제로 말할 문구가 따옴표로 들어 있습니다. Claude는 이 문장과 사용자 요청을 대조해 호출을 결정하므로, 사용자의 입말이 곧 검색 키워드입니다. 반대로 너무 넓은 설명("문서 작업 전반")은 엉뚱한 때 호출됩니다. 그럴 때는 용도를 좁히거나 disable-model-invocation: true로 수동 전용으로 바꿉니다.

allowed-tools 와 disallowed-tools

allowed-tools는 미리 승인입니다. 이 Skill이 켜진 동안 나열된 도구는 권한 확인 없이 실행됩니다. 도구를 제한하는 것은 아니며, 나열되지 않은 도구는 평소 권한 설정을 그대로 따릅니다. 우리 배포 Skill은 사람이 명시적으로 부를 때만 돌고, 배포 스크립트 실행은 묻지 않게 합니다.

---
name: deploy
description: 운영 서버에 배포하고 재시작·헬스체크까지 수행합니다.
disable-model-invocation: true
allowed-tools: Bash(bash scripts/deploy.sh *) Bash(git push *)
---

disallowed-tools는 반대로 도구를 풀에서 빼 버립니다. 자율 루프 Skill에서 사용자 질문 도구를 막아 "묻지 말고 끝까지 돌아라"를 강제할 때 씁니다. 제한은 다음 메시지를 보내면 풀립니다. 프로젝트 .claude/skills/에 체크인된 Skill의 allowed-tools는 작업 공간 신뢰를 수락한 뒤에만 적용되니, 남이 만든 프로젝트 Skill은 신뢰 전에 내용을 읽어 보세요. Skill이 스스로에게 넓은 권한을 줄 수 있기 때문입니다.

skill-creator 로 디자인 Skill 만들기

직접 쓰는 것보다 초안을 시키고 다듬는 편이 빠릅니다. 실습 목표는 "우리 사이트 카드뉴스 이미지 시안의 디자인 규칙"을 Skill로 만드는 것입니다.

1. 플러그인 설치

Claude Code 안에서 한 줄씩 입력합니다.

/plugin install skill-creator@claude-plugins-official
/reload-plugins

플러그인을 못 찾으면 /plugin marketplace update claude-plugins-official을 먼저 실행합니다. macOS와 Windows 모두 같습니다.

2. Skill 작성 의뢰

새 세션에서 이렇게 요청합니다.

skill-creator로 card-design 스킬을 ~/.claude/skills/ 에 만들어 줘.
용도: 교육 안내 카드뉴스 시안을 만들 때 적용할 디자인 규칙.
규칙: 본문 서체 1종+제목 서체 1종, 색은 배경·강조·본문 3색만, 여백은 카드 폭의 8% 이상,
문장 잇는 작대기 금지. 사용자가 "카드뉴스", "시안", "배너" 라고 말하면 호출.

규칙을 구체적으로 줄수록 초안 품질이 올라갑니다. 우리 팀은 "발행 글에 작대기 금지" 같은 운영 규칙을 이런 식으로 Skill에 박아 둡니다.

3. 생성 결과 확인

~/.claude/skills/card-design/SKILL.md를 열어 세 가지를 확인합니다. description에 "카드뉴스", "시안", "배너"가 들어갔는지, 본문이 설명문이 아니라 규칙 목록인지, 500줄을 넘지 않는지입니다. 그다음 skill-creator에 평가를 시킵니다. "card-design 스킬을 skill-creator로 평가해 줘"라고 하면 evals/evals.json에 테스트 프롬프트를 만들고, 케이스마다 서브에이전트를 띄워 Skill 있음·없음을 비교한 뒤 통과율·토큰·시간을 benchmark.json에 집계합니다. 결과가 "있음"이 나은지 숫자로 보고 커밋합니다. 정지 규칙은 증거입니다.

서포트 파일로 규칙을 나누는 법

본문이 길어지면 지원 파일로 나눕니다. 지원 파일은 SKILL.md에서 링크해야 Claude가 언제 열지 압니다.

card-design/
├── SKILL.md          # 규칙 요약 + 링크
├── palette.md        # 색 조합 표 (필요할 때만 열림)
├── examples/
│   └── good.md       # 통과한 시안 3건 설명
└── scripts/
    └── check.sh      # 이미지 크기·여백 실측

## 참고 자료
- 색 조합 전체 표는 [palette.md](palette.md)를 읽는다.
- 통과 사례는 [examples/good.md](examples/good.md)를 읽는다.
- 여백 실측은 `bash ${CLAUDE_SKILL_DIR}/scripts/check.sh <이미지>` 를 실행한다.

${CLAUDE_SKILL_DIR}는 Skill 폴더 경로로 치환되므로 개인·프로젝트·플러그인 어디에 있어도 스크립트를 찾습니다.

호출되지 않을 때 무엇을 확인하나

1. /이름으로 직접 실행되는지 봅니다. 되면 파일 위치는 맞습니다.
2. 직접 실행은 되는데 자동으로 안 되면 description을 봅니다. 사용자가 말할 단어가 없거나, YAML이 깨져 설명이 비어 있는 경우입니다. claude --debug로 파싱 오류를 볼 수 있습니다.
3. "어떤 skills를 쓸 수 있어?"라고 물어 목록에 있는지 확인합니다. 없으면 /doctor로 목록 예산 초과 여부를 봅니다.
4. disable-model-invocation: true가 붙어 있으면 자동 호출이 안 되는 게 정상입니다.
5. 플러그인 Skill이면 /reload-plugins를 실행했는지 확인합니다.

정리

• SKILL.md는 frontmatter와 본문이고, 폴더 이름이 명령 이름입니다.
• description에 동사와 사용자 입말을 넣으면 자동 호출이 안정됩니다.
• allowed-tools는 미리 승인, disallowed-tools는 제거, disable-model-invocation은 수동 전용입니다.
• skill-creator로 초안을 만들고 있음·없음 벤치마크 숫자를 본 뒤 커밋합니다.
• 긴 자료는 지원 파일로 빼고 본문에서 링크합니다.

자주 묻는 질문