Kwangmin Kim - SKILL.md 명세와 작성법

1 Custom Commands에서 SKILL.md로

Agent 스킬(Agent Skills)은 단순한 단축 명령어에서 출발하여 현재는 여러 AI Agent 제품이 채택하는 오픈 표준(Open Standard)으로 발전했다.

1.1 Custom Commands의 한계

초기 Claude Code는 Agent의 행동을 확장하기 위해 사용자 지정 명령어(Custom Commands) 방식을 사용했다. .claude/commands/ 폴더 내에 단일 마크다운(.md) 파일로 프롬프트 템플릿을 저장하는 단순한 형태였다.

한계	설명
수동 호출만 가능	사용자가 항상 `/명령어`를 통해 수동으로 호출해야 했다. AI가 스스로 판단하여 자동 실행하는 기능이 없었다
컨텍스트 낭비	명령어 실행 시 전체 프롬프트가 한 번에 로드되어 컨텍스트 윈도우(토큰)를 크게 소비했다
구조적 한계	스크립트를 번들링하거나 참조 문서를 분리 관리할 수 없었다

1.2 SKILL.md의 도입

이 한계를 극복하기 위해 Anthropic은 SKILL.md 기반 Agent 스킬을 개발하고 오픈 표준으로 공개했다. 핵심 개선점은 다음과 같다.

단일 파일에서 디렉토리 구조로 전환: SKILL.md를 중심으로 scripts/, references/ 등을 분리하여 체계적 관리가 가능해졌다
자동 호출(Model-invoked) 도입: 사용자 의도를 파악하여 Agent가 스스로 적절한 스킬을 활성화한다
점진적 정보 노출(Progressive Disclosure) 적용: 필요한 순간에만 문서를 읽어들여 토큰 소비를 극적으로 줄였다

스킬의 일반적 개념과 설계 원칙은 Agent 스킬 설계와 생성에서, LangChain 스킬 세트 분석은 스킬 기반 Agent 패턴에서 다룬다. 본 포스트는 SKILL.md 공식 명세에 초점을 맞춘다.

2 점진적 정보 노출 메커니즘

점진적 정보 노출(Progressive Disclosure)은 Agent가 한정된 컨텍스트 윈도우를 효율적으로 관리하기 위한 핵심 설계 원칙이다. 수십 개의 스킬이 설치되어 있더라도 모든 내용을 처음부터 읽지 않는다. 발견, 활성화, 실행의 3단계로 정보를 나누어 필요할 때만 로드한다.

┌────────────────────────────────────────────────────────────┐
│  1단계: 발견 (Discovery) — 카탈로그 로드                    │
│  ────────────────────────────────────                       │
│  세션 시작 시, 모든 스킬의 name과 description만 읽는다      │
│  스킬당 약 50~100 토큰만 소모                               │
│  "어떤 스킬이 존재하는가"를 판단할 수 있는 최소 정보        │
├────────────────────────────────────────────────────────────┤
│  2단계: 활성화 (Activation) — 지시사항 로드                  │
│  ──────────────────────────────────────                     │
│  사용자 요청이 특정 스킬의 description과 일치하면            │
│  해당 SKILL.md의 전체 본문을 컨텍스트로 로드                │
│  권장 크기: 5,000 토큰 이하                                 │
│  사용되지 않는 스킬의 본문은 무시 → 토큰 낭비 없음          │
├────────────────────────────────────────────────────────────┤
│  3단계: 실행 (Execution) — 리소스 온디맨드 로드              │
│  ──────────────────────────────────────────                 │
│  SKILL.md 본문의 외부 참조 파일(scripts/, references/)을     │
│  한 번에 로드하지 않고, 정말 필요한 순간에만 개별 로드       │
└────────────────────────────────────────────────────────────┘

이 메커니즘 덕분에 스킬이 수십 개 설치되어 있어도 실제로 컨텍스트에 로드되는 것은 현재 태스크에 필요한 스킬 하나의 본문뿐이다. 나머지 스킬은 이름과 설명만 카탈로그에 존재한다.

3 SKILL.md 구조

SKILL.md는 YAML 프론트매터와 마크다운 본문 두 부분으로 구성된다.

3.1 프론트매터 (Frontmatter)

마크다운 파일 최상단에 ---로 감싸서 작성하며, 스킬의 메타데이터와 실행 환경을 정의한다.

필드	필수	설명
`name`	선택	스킬의 고유 이름. 생략 시 디렉토리 이름을 사용한다. 최대 64자, 소문자/숫자/하이픈만 허용
`description`	권장	Agent가 자동 호출 여부를 판단하는 핵심 필드. “무엇을 하는지”, “언제 사용하는지”를 구체적으로 명시한다. 생략 시 마크다운 본문의 첫 문단을 사용
`argument-hint`	선택	자동완성 시 예상 인자를 표시하는 힌트. 예: `[issue-number]`, `[filename] [format]`
`disable-model-invocation`	선택	`true`이면 Agent의 자동 호출을 차단하고, 사용자의 `/명령어` 입력 시에만 실행한다. 기본값: `false`
`user-invocable`	선택	`false`이면 사용자의 `/` 메뉴에서 숨긴다. Agent만 백그라운드에서 참고하는 배경 지식에 사용한다. 기본값: `true`
`allowed-tools`	선택	스킬 활성 시 권한 확인 없이 사용할 수 있는 도구를 지정한다. 예: `Read, Grep, Glob`
`model`	선택	스킬 실행에 사용할 모델을 지정한다 (예: `sonnet`)
`effort`	선택	스킬 활성 시 적용할 노력 수준. 세션 설정을 오버라이드한다. 옵션: `low`, `medium`, `high`, `max` (Opus 4.6 전용)
`context`	선택	`fork`로 설정하면 격리된 서브에이전트 컨텍스트에서 실행한다
`agent`	선택	`context: fork`와 함께 사용. 서브에이전트 유형을 지정한다. 옵션: `Explore`, `Plan`, `general-purpose` 또는 `.claude/agents/`의 커스텀 에이전트. 기본값: `general-purpose`
`hooks`	선택	스킬의 라이프사이클에 스코프된 훅을 정의한다
`paths`	선택	스킬 활성화를 특정 파일 패턴으로 제한하는 glob 패턴. 매칭되는 파일 작업 시에만 자동 로드된다. 쉼표 구분 문자열 또는 YAML 리스트
`shell`	선택	!`command` 블록에 사용할 쉘. `bash`(기본값) 또는 `powershell`. Windows에서 PowerShell 사용 시 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` 환경변수 필요

프론트매터 예시이다.

---
name: explain-code
description: >
  Use this skill when the user asks how a piece of code works,
  mentions "explain", "코드 설명", or wants to understand a complex function.
  Keywords: explain, 설명, 분석
disable-model-invocation: false
allowed-tools: ["Read", "Bash"]
context: fork
agent: Explore
model: sonnet
---

description은 단순한 설명이 아니라 트리거 조건이다. Agent가 수많은 스킬 중에서 현재 요청에 맞는 스킬을 자동으로 선택하는 판단 기준이 된다. “무엇을 하는지”뿐 아니라 “어떤 키워드에 반응하는지”까지 구체적으로 기술해야 정확도가 높아진다.

3.2 호출 제어 매트릭스

disable-model-invocation과 user-invocable 두 필드의 조합으로 스킬의 호출 방식과 컨텍스트 로드 시점을 세밀하게 제어할 수 있다.

설정	사용자 호출	Agent 호출	컨텍스트 로드 시점
(기본값)	O	O	description은 항상 컨텍스트에 포함. 전체 스킬은 호출 시 로드
`disable-model-invocation: true`	O	X	description이 컨텍스트에 포함되지 않음. 사용자 호출 시에만 전체 로드
`user-invocable: false`	X	O	description은 항상 컨텍스트에 포함. Agent 호출 시 전체 로드

사용 시나리오별 권장 설정이다.

배포, 커밋 등 부작용이 있는 작업 -> disable-model-invocation: true (사용자만 호출)
레거시 시스템 컨텍스트, 팀 규칙 등 배경 지식 -> user-invocable: false (Agent만 참조)
코드 설명, 검색 등 범용 작업 -> 기본값 (양쪽 모두 호출 가능)

3.3 마크다운 본문

프론트매터 아래에 작성하는 본문은 Agent가 스킬 호출 시 읽고 따를 구체적인 가이드라인이다. 목적(Purpose), 명세(Specification), 리파인먼트(Refinement)의 3단계 구조가 권장된다.

섹션	역할	핵심 질문
Purpose	스킬의 목적과 큰 그림을 정의한다	“이 스킬은 무엇을 하는가?”
Specification	사용할 도구와 단계별 절차를 구체화한다	“어떻게 동작하는가?”
Refinement	설계 결정과 제한 사항을 설명한다	“왜 이렇게 작성했는가?”

3.4 본문 작성 핵심 원칙

원칙	설명
일반 지식 생략	Agent가 이미 아는 지식(PDF 개념, HTTP 기초 등)은 과감히 생략한다. 프로젝트 고유의 규약, 엣지 케이스, API 패턴만 담는다
프로젝트 특유의 주의사항 명시	“users 테이블은 소프트 삭제이므로 항상 `WHERE deleted_at IS NULL` 조건을 포함한다” 같은 실무적 예외 규칙을 적어 에러를 방지한다
체크박스 워크플로우	복잡한 작업은 `- [ ]` 형태의 단계별 워크플로우로 분해한다
출력 템플릿 제공	Agent가 생성할 결과물의 마크다운 구조나 데이터 포맷을 본문 내에 제공하면 일관된 결과를 얻을 수 있다
계획-검증-실행 루프	“1. 스크립트 실행 -> 2. validate.py로 검증 -> 3. 실패 시 에러를 읽고 수정 후 재검증”처럼 검증 루프를 명시한다
500줄 이하 유지	방대한 API 명세나 코드는 `references/`에 분리하고 본문에서는 경로만 참조한다

4 동적 변수와 쉘 주입

SKILL.md는 런타임에 동적으로 값을 주입하는 기능을 지원한다.

4.1 사용자 인자

사용자가 스킬 호출 시 전달한 인자를 본문에 삽입할 수 있다.

변수	설명	예시
`$ARGUMENTS`	사용자가 입력한 전체 인자	`/explain-code src/main.py` -> `src/main.py`
`$ARGUMENTS[N]` 또는 `$N`	특정 순서의 인자	`$0` = 첫 번째 인자, `$1` = 두 번째 인자

4.2 환경 변수

변수	설명
`${CLAUDE_SKILL_DIR}`	해당 스킬 폴더의 절대 경로. 내부 스크립트 경로를 가리킬 때 사용
`${CLAUDE_SESSION_ID}`	현재 대화의 고유 세션 ID. 세션별 로그나 임시 파일 생성에 사용

4.3 쉘 명령어 주입

본문 내에 !`명령어` 구문을 작성하면, Agent에게 프롬프트가 전달되기 전에 시스템이 해당 명령어를 먼저 실행하고 출력값을 본문에 실시간으로 주입한다.

## 현재 PR 변경 사항

!`gh pr diff`

이 기능을 활용하면 스킬 실행 시점의 Git 상태, 환경 정보, 파일 목록 등을 동적으로 컨텍스트에 포함시킬 수 있다.

4.4 종합 예시

아래는 코드 분석 스킬의 전체 SKILL.md 예시이다. 프론트매터, 동적 변수, 쉘 주입을 모두 활용한다.

---
name: explain-code
description: >
  Use this skill when the user asks how a piece of code works,
  mentions "explain", "코드 설명", or wants to understand a complex function.
  Keywords: explain, 설명, 분석
disable-model-invocation: false
allowed-tools: ["Read", "Bash"]
context: fork
agent: Explore
model: sonnet
---

# Purpose

사용자가 제시한 코드나 파일의 동작 원리를 분석하고,
비유(analogy)와 ASCII 다이어그램을 활용해 직관적으로 설명한다.

# Specification

1. 사용자가 입력한 다음 내용을 분석한다:
   $ARGUMENTS
2. 코드의 핵심 로직을 3줄 이내로 요약한다.
3. 기술적 배경이 없는 사람도 이해할 수 있도록 비유를 들어 설명한다.
4. 로직의 흐름을 나타내는 ASCII 다이어그램을 작성한다.
5. 필요한 경우 `${CLAUDE_SKILL_DIR}/scripts/analyze.sh`를 실행하여
   코드 메타데이터를 수집한다.

현재 브랜치 상태:
!`git status -s`

# Refinement

- 최종 결과물은 한국어로 작성한다.
- 지나치게 깊은 기술 용어(AST 파싱 등)는 피하고 직관적 이해에 집중한다.

context: fork로 설정되어 있으므로 이 스킬은 메인 대화의 컨텍스트를 오염시키지 않고 별도의 서브에이전트에서 실행된다. allowed-tools: ["Read", "Bash"]로 파일 읽기와 스크립트 실행이 권한 확인 없이 허용된다.

5 번들 스킬

Claude Code에는 모든 세션에서 사용 가능한 번들 스킬(Bundled Skills)이 기본 탑재되어 있다. 빌트인 명령어(/help, /compact)와 달리, 번들 스킬은 프롬프트 기반으로 작동하여 병렬 에이전트 생성, 파일 읽기, 코드베이스 적응 등이 가능하다.

스킬	용도
`/batch <instruction>`	대규모 코드 변경을 병렬로 오케스트레이션한다. 작업을 5~30개 독립 단위로 분해하고, 단위별로 격리된 git worktree에서 백그라운드 에이전트를 생성하여 구현, 테스트, PR 생성까지 수행한다
`/claude-api`	프로젝트 언어에 맞는 Claude API 레퍼런스를 로드한다. `anthropic`, `@anthropic-ai/sdk`, `claude_agent_sdk` import 시 자동 활성화
`/debug [description]`	현재 세션의 디버그 로깅을 활성화하고 이슈를 진단한다
`/loop [interval] <prompt>`	프롬프트를 주기적으로 반복 실행한다. 배포 모니터링, PR 감시 등에 유용하다
`/simplify [focus]`	최근 변경 파일을 코드 재사용, 품질, 효율성 관점에서 리뷰하고 수정한다. 3개의 리뷰 에이전트를 병렬 실행

6 스킬 권한 제어

Agent가 호출할 수 있는 스킬을 제한하는 세 가지 방법이 있다.

# 모든 스킬 비활성화 (/permissions에서 deny 규칙 추가)
Skill

# 특정 스킬만 허용
Skill(commit)
Skill(review-pr *)

# 특정 스킬 차단
Skill(deploy *)

권한 문법: Skill(name)은 정확히 일치, Skill(name *)은 접두사 매칭이다. user-invocable 필드는 메뉴 표시만 제어하며, 프로그래밍 호출을 차단하려면 반드시 disable-model-invocation: true를 사용해야 한다.

스킬 description 용량 제한

스킬 description은 세션 시작 시 컨텍스트에 로드되어 Agent가 사용 가능한 스킬을 인식한다. 스킬이 많으면 컨텍스트 윈도우의 2%(fallback: 16,000자) 한도를 초과할 수 있다. /context 명령어로 제외된 스킬을 확인하고, SLASH_COMMAND_TOOL_CHAR_BUDGET 환경변수로 한도를 조정할 수 있다.

7 디렉토리 구조

7.1 스킬 저장 위치

스킬의 사용 범위에 따라 저장 위치가 달라진다. 동일한 이름의 스킬이 여러 위치에 존재하면 상위 우선순위가 적용된다.

우선순위	범위	경로	적용 대상
1 (최고)	Enterprise	관리 설정(Managed Settings)	조직 전체 사용자
2	Personal	`~/.claude/skills/<name>/SKILL.md`	모든 프로젝트
3	Project	`.claude/skills/<name>/SKILL.md`	해당 프로젝트만
4	Plugin	`<plugin>/skills/<name>/SKILL.md`	플러그인 활성화된 곳

플러그인 스킬은 plugin-name:skill-name 네임스페이스를 사용하므로 다른 레벨과 충돌하지 않는다. .claude/commands/ 파일도 여전히 작동하지만, 동일한 이름의 스킬과 명령어가 있으면 스킬이 우선한다.

Agent는 현재 작업 디렉토리의 하위 .claude/skills/도 자동 탐색한다. 예를 들어 packages/frontend/ 파일을 편집 중이면 packages/frontend/.claude/skills/의 스킬도 사용할 수 있다. 모노레포에서 패키지별 스킬을 분리 관리할 때 유용하다.

7.2 스킬 폴더 구조

하나의 스킬 폴더는 다음과 같이 모듈화하여 구성한다.

my-skill/
├── SKILL.md            # (필수) 메타데이터와 핵심 지시사항
├── scripts/            # (선택) 실행 가능한 스크립트
│   ├── analyze.py
│   └── format.sh
├── references/         # (선택) 추가 참조 문서
│   ├── schema.yaml
│   └── guidelines.md
├── assets/             # (선택) 정적 리소스 및 템플릿
│   └── report-template.md
└── evals/              # (선택) 스킬 테스트 및 평가 데이터
    └── evals.json

디렉토리	역할	비고
`SKILL.md`	스킬의 진입점. 프론트매터 + 지시사항	필수. 500줄 이하 권장
`scripts/`	Agent가 직접 실행하는 코드	매번 코드를 생성하지 않아도 되므로 일관되고 결정론적인 결과
`references/`	API 명세서, 데이터 포맷 등 부피가 큰 문서	Agent가 정말 필요한 순간에만 온디맨드로 로드
`assets/`	문서 템플릿, 다이어그램, 조회용 데이터	스킬 실행이나 결과물 생성에 필요한 정적 파일
`evals/`	테스트 프롬프트 (`evals.json`)	스킬이 올바르게 동작하는지 검증. 테스트 주도 개발 방식으로 품질 평가

scripts/에 로직을 분리하면 Agent가 매번 코드를 새로 생성할 필요가 없다. 동일한 스크립트를 반복 실행하므로 결정론적이고 일관된 결과를 얻을 수 있다.

8 서브에이전트에서 스킬 실행

context: fork를 프론트매터에 설정하면 스킬이 격리된 서브에이전트에서 실행된다. 스킬 내용이 서브에이전트의 프롬프트가 되며, 메인 대화의 히스토리에 접근하지 않는다.

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

실행 흐름은 다음과 같다.

격리된 새 컨텍스트가 생성된다
서브에이전트가 스킬 내용을 프롬프트로 받는다
agent 필드가 실행 환경(모델, 도구, 권한)을 결정한다
결과가 요약되어 메인 대화로 반환된다

context: fork 주의사항

context: fork는 명시적 작업 지시가 있는 스킬에서만 의미가 있다. “이 API 규칙을 따르라” 같은 가이드라인만 포함된 스킬에 fork를 설정하면, 서브에이전트가 가이드라인을 받지만 실행할 작업이 없어 의미 있는 결과를 반환하지 못한다.

접근 방식	시스템 프롬프트	태스크	추가 로드
스킬 + `context: fork`	Agent 유형(`Explore`, `Plan` 등)에서 제공	SKILL.md 내용	CLAUDE.md
서브에이전트 + `skills` 필드	서브에이전트의 마크다운 본문	Agent의 위임 메시지	프리로드된 스킬 + CLAUDE.md

9 스킬 생태계 활용

이미 커뮤니티에서 만들어진 스킬을 재사용할 수 있다. skills.sh 사이트에서 공개된 스킬을 검색하고 설치할 수 있다.

9.1 스킬 설치

# 스킬 설치 (npx 사용)
npx skills add vercel-labs/skills

9.2 find-skills 스킬

가장 많이 설치된 스킬은 find-skills이다. 필요한 스킬을 검색해주는 메타 스킬로, 설치 후 Agent에게 원하는 기능을 설명하면 적절한 스킬을 찾아준다.

# find-skills 스킬 설치
npx skills add vercel-labs/skills

Agent에서 사용하는 예시이다.

/find-skills "extreme programming"

→ proffesor-for-testing/agentic-qe@xp-practices  (60 installs)
  XP 핵심 실천법: TDD, CI, Pair Programming, Collective Ownership

  npx skills add proffesor-for-testing/agentic-qe@xp-practices

10 실전 예시: 계산기 스킬

간단한 더하기 계산 스킬을 만들어 전체 흐름을 확인한다.

10.1 디렉토리 구조

.agents/skills/calculator/
├── SKILL.md
└── scripts/
    └── add.py

10.2 SKILL.md

---
name: calculator
description: >
  단순한 더하기 계산기. 사용자가 전달한 숫자들을 더한다.
  "더해줘", "더하기" 등의 명령어로 실행할 수 있다.
---

# Purpose

사용자가 전달한 숫자들을 더하는 역할을 한다.

# Specification

숫자 더하기는 `${CLAUDE_SKILL_DIR}/scripts/add.py` 스크립트를 사용한다.

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/add.py $ARGUMENTS


### scripts/add.py

```python
import sys

numbers = [int(x) for x in sys.argv[1:]]
total = sum(numbers)
print(f"합계: {' + '.join(map(str, numbers))} = {total}")

10.3 실행 결과

사용자가 “1 2 3 4 5 더해줘”라고 입력하면, Agent가 “더해줘” 키워드를 보고 calculator 스킬을 자동 선택하여 실행한다.

● skill(calculator)

● Add 1 2 3 4 5 (shell)
  │ python3 .agents/skills/calculator/scripts/add.py 1 2 3 4 5
  └ 합계: 1 + 2 + 3 + 4 + 5 = 15

● 1 + 2 + 3 + 4 + 5 = 15

Agent가 description의 “더해줘” 키워드를 매칭하여 스킬을 자동 호출하고, $ARGUMENTS로 전달된 숫자들을 스크립트에 넘겨 실행한 것이다. 사용자가 /calculator를 명시적으로 입력하지 않아도 자동으로 작동한다.

11 트러블슈팅

증상	원인	해결
스킬이 자동 트리거되지 않음	description이 사용자 표현과 매칭되지 않음	description에 사용자가 자연스럽게 사용할 키워드를 포함한다. `What skills are available?`로 스킬 인식 여부를 확인한다
스킬이 너무 자주 트리거됨	description이 지나치게 광범위함	description을 더 구체적으로 수정하거나 `disable-model-invocation: true`로 수동 전환한다
Agent가 일부 스킬을 인식하지 못함	description 총량이 컨텍스트 한도(2%) 초과	`/context`로 제외된 스킬을 확인한다. `SLASH_COMMAND_TOOL_CHAR_BUDGET` 환경변수로 한도를 조정한다
`context: fork` 스킬이 빈 결과 반환	가이드라인만 있고 실행할 태스크가 없음	스킬 본문에 명시적인 작업 지시를 포함한다

12 관련 주제

선행 지식

Agent 스킬 설계와 생성 – 스킬의 일반 개념, 설계 방법론, 품질 체크리스트
스킬 기반 Agent 패턴 – LangChain 스킬 세트 분석, 프로그레시브 디스클로저 원리
스킬 역분석: Agent용 시스템 프롬프트 작성 원리 – SKILL.md 내부의 프롬프트 엔지니어링 기법 8가지

후속 주제

스킬 패턴의 실전 적용: 블로그 지식 관리 시스템 – 계층적 스킬 구조의 실제 구현 사례
MCP 기반 도구 통합 – 스킬이 외부 도구와 연동할 때 사용하는 표준 프로토콜

참고 자료