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

SKILL.md는 Claude Code Skill의 핵심 파일로, YAML 프론트매터(name·description 등)와 Markdown 본문(지식·절차)으로 구성됩니다. 이 파일의 구조만 이해하면 누구나 직접 Skill을 만들 수 있고, Anthropic 공식 skill-creator 플러그인을 쓰면 한결 부담이 줄어듭니다.

도메인 지식과 컨텍스트에서 "어떤 지식을 Skill로 만들 가치가 있는가"를 봤다면, 이 글은 그 지식을 실제 파일로 옮기는 방법입니다. Skill의 개념 자체는 Claude Skills란 무엇인가를 참고하세요.

핵심 요약

• Skills는 ~/.claude/skills/(개인용) 또는 .claude/skills/(프로젝트용)에 둡니다.
• 프론트매터 필드는 전부 선택이지만 description이 호출 여부를 결정하므로 사실상 필수입니다.
• description에는 "무엇을 하는가"와 "언제 쓰는가"를 구체적인 키워드로 적습니다.
• skill-creator 플러그인으로 틀을 만든 뒤 description을 직접 다듬는 것이 가장 빠릅니다.
• reference.md·examples.md·templates/ 같은 서포트 파일로 상세 규칙을 분할 관리할 수 있습니다.

Skills는 어디에 두나

책장 정리에 빗대면 '개인 서재'와 '회사 공유 책장'처럼 용도에 따라 둘 곳이 나뉩니다.

개인용은 TypeScript 베스트 프랙티스처럼 어느 프로젝트에서든 쓰고 싶은 지식에 알맞습니다. 프로젝트용은 디자인 시스템이나 코딩 규약처럼 그 프로젝트 고유의 규칙에 씁니다. 팀과 공유하려면 .claude/skills/에 두고 git에 커밋하면 다른 멤버도 같은 Skill을 쓰게 됩니다.

SKILL.md는 어떻게 생겼나

SKILL.md는 YAML 프론트매터와 Markdown 본문으로 구성됩니다. 최소 구성은 이렇습니다.

---
name: skill-identifier
description: 이 스킬의 설명과, 어떤 장면에서 쓸지를 기술
---
# 스킬명

스킬의 상세한 설명이나 가이드라인을 여기에 씁니다.

핵심 필드

프론트매터의 필드는 모두 선택이지만, description은 반드시 써 두는 것이 좋습니다. Claude는 이 설명문만 보고 "이 작업에 이 Skill을 써야 하나"를 판단하기 때문입니다.

좋은 description은 무엇이 다른가

description 작성법에 따라 Skill이 호출되는지 여부가 갈립니다. 구체적인 키워드를 포함하세요.

# 좋은 예: 구체적인 키워드를 포함
description: Apple Human Interface Guidelines에 따른 UI 설계를 한다.
  Use when creating iOS/macOS style interfaces, Apple-like design,
  or working with SF Symbols, glassmorphism, or Apple design system.

# 나쁜 예: 너무 모호함
description: 디자인을 개선하는 스킬

allowed-tools 와 disallowed-tools

필요에 따라 도구 관련 필드를 추가할 수 있습니다.

---
name: safe-file-reader
description: 파일을 읽기 전용으로 분석한다. 파일 읽기나 검색이 필요할 때 사용.
allowed-tools: Read, Grep, Glob
---

allowed-tools는 어디까지나 사전 승인입니다. 목록에 없는 도구도 통상의 권한 설정에 따라 계속 호출할 수 있습니다. 도구 사용 자체를 막으려면 disallowed-tools를 씁니다. 공식 문서가 권하는 활용 예는 다음과 같습니다.

• 읽기 전용 스킬: 파일을 변경해서는 안 되는 경우
• 스코프가 한정된 스킬: 데이터 분석만 하고 파일 쓰기는 없는 경우
• 보안에 민감한 워크플로: 기능을 제한하고 싶은 경우

둘 다 지정하지 않으면 Claude는 평소처럼 도구를 쓸 때마다 허가를 구합니다.

skill-creator 로 디자인 Skill 만들기

Anthropic 공식 skill-creator 플러그인을 쓰면 Skill 구조를 훤히 몰라도 틀을 만들 수 있습니다.

skill-creator는 '틀'을 만드는 도구입니다. 생성된 SKILL.md는 반드시 열어서 확인하고, 특히 description은 자기 유스케이스에 맞게 조정하세요.

1. 플러그인 설치

먼저 Anthropic의 스킬 마켓플레이스를 추가합니다.

> /plugin marketplace add anthropics/skills
  ⎿  Successfully added marketplace: anthropic-agent-skills

/plugin을 실행하면 example-skills 플러그인에 어떤 Skill이 들어 있는지 볼 수 있습니다(/plugin은 /plugins로 자동 전개됩니다).

example-skills @ anthropic-agent-skills
Installed components:
• Skills: algorithmic-art, brand-guidelines, canvas-design, doc-coauthoring, docx,
  frontend-design, internal-comms, mcp-builder, pdf, pptx, skill-creator,
  slack-gif-creator, theme-factory, web-artifacts-builder, webapp-testing, xlsx

이 안에 skill-creator가 포함돼 있습니다. 설치합니다.

> /plugin install example-skills@anthropic-agent-skills

설치 범위를 고르는 화면이 뜹니다.

│   Install for you (user scope)
│ > Install for all collaborators on this repository (project scope)
│   Install for you, in this repo only (local scope)

설치 후 /plugin에서 Tab 키로 Installed 탭으로 이동하면 example-skills user, v1.0.0 같은 항목이 보입니다.

2. Skill 작성 의뢰

아래 프롬프트로 새 Skill을 만들게 합니다.

skill-creator 스킬을 써서, Apple풍의 세련된 디자인을
작성하기 위한 새 Claude Skills인 "apple-design"을
프로젝트 내에 작성해 주세요.

Skill 사용 허가를 물으면 "Yes"를 고릅니다.

 Use skill "example-skills:skill-creator"?
 Claude may use instructions, code, or files from this Skill.
 Do you want to proceed?
 ❯ 1. Yes
   2. Yes, and don't ask again for example-skills:skill-creator in this project
   3. No, and tell Claude what to do differently (esc)

3. 생성 결과 확인

잠시 기다리면 가장 단순한 구조로 Skill이 만들어집니다.

.claude
└── skills
    └── apple-design
        └── SKILL.md

SKILL.md 안에 Apple Design System 가이드라인이 기술돼 있을 것입니다. 여기서 description을 자기 상황에 맞게 고치면 완성입니다.

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

SKILL.md 옆에 추가 파일을 두면 상세 규칙을 분할 관리할 수 있습니다. 공식 문서가 권장하는 구조입니다.

my-skill/
├── SKILL.md           # 필수: 메인 스킬 파일
├── reference.md       # 옵션: 상세한 문서
├── examples.md        # 옵션: 구체적인 사용 예
├── scripts/
│   └── helper.py      # 옵션: 유틸리티 스크립트
└── templates/
    └── template.txt   # 옵션: 템플릿 파일

SKILL.md 본문에서 이 파일들을 참조해 두면 필요할 때만 읽어들입니다. 본문을 가볍게 유지하면서 깊은 내용은 옆 파일에 두는 방식입니다. 같은 발상으로 CLAUDE.md를 나누는 방법은 .claude/rules/ 로 규칙 모듈화를 참고하세요.

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

Claude Code 안에서 /skills를 실행해 만든 Skill이 목록에 보이는지 확인하세요.

> /skills
 Skills
 User skills (~/.claude/skills)
 agile-ticket-planner · ~2.1k tokens
 claude-code-headless · ~1.7k tokens
 Project skills (.claude/skills)
 apple-design · ~1.1k tokens      <- 여기 보이면 OK
 Esc to close

User skills에는 환경에 따라 다른 Skill이 늘어섭니다. apple-design이 Project skills 아래에 있는지만 보면 됩니다. 토큰 수도 함께 표시되므로 Skill이 평소에 얼마나 컨텍스트를 차지하는지 가늠할 수 있습니다.

정리

• 배치 장소는 ~/.claude/skills/(개인용) 또는 .claude/skills/(프로젝트용)이며, 후자를 커밋하면 팀 공유가 됩니다.
• 프론트매터 필드는 전부 선택이지만 description이 트리거의 결정타이므로 구체적 키워드로 씁니다.
• skill-creator로 틀을 만들고 description을 다듬는 것이 가장 빠른 길입니다.
• reference.md·templates/ 같은 서포트 파일로 상세 규칙을 분할 관리하고, /skills로 인식 여부를 확인합니다.

Skill을 만들었다면 "이 일은 Skill로 할지, 서브에이전트에 맡길지"가 다음 고민입니다. Skills vs 서브에이전트에서 판단 기준을 다룹니다. 에이전트 쪽 정의 파일은 커스텀 에이전트 정의 파일을 참고하세요.