1. 스킬 기본형

한 줄 정의. 스킬은 SKILL.md 한 개를 품은 폴더이고, 에이전트는 그 안의 이름과 설명만 평소에 들고 있다가, 필요할 때 본문과 리소스를 단계적으로 불러온다.

왜 중요한가

에이전트에게 능력을 더하는 가장 단순한 방법은 프롬프트에 지식을 다 때려 넣는 것입니다. 하지만 그러면 컨텍스트가 금세 부풀고, 컨텍스트 엔지니어링 장에서 다룰 성능 저하로 이어집니다.

스킬은 “지식을 폴더에 두고 필요할 때만 꺼내 쓴다”는 발상으로 이 문제를 정면으로 피합니다. 그래서 스킬은 단순한 프롬프트 조각이 아니라, 하네스가 컨텍스트를 아끼는 핵심 장치입니다.

스킬의 정의와 본질

스킬은 절차적 지식과 회사·팀·사용자별 맥락을 이식 가능한 버전관리 폴더로 패키징해, 에이전트가 필요한 순간(on-demand)에 로드하도록 만든 단위입니다¹. 여기서 중요한 단어는 두 개입니다. 첫째는 “폴더”입니다.

스킬은 단일 텍스트 조각이 아니라 디렉터리이고, 그 안에서 유일한 필수 파일이 SKILL.md 하나입니다². 나머지 — scripts/, references/, assets/, 그 밖의 임의 파일과 디렉터리 — 는 전부 선택입니다. 둘째는 “on-demand”입니다.

스킬은 항상 컨텍스트에 머무르지 않고, 관련된 작업이 들어올 때 비로소 본문이 펼쳐집니다. 이 두 성질이 합쳐져 스킬은 “많이 들고 있어도 가벼운” 능력 확장 수단이 됩니다.

스킬이 실무에서 주는 가치는 세 가지로 정리됩니다¹.

• 하나는 도메인 전문성(domain expertise) — 특정 분야의 노하우를 모델에 주입합니다.
• 둘은 반복 가능한 워크플로(repeatable workflows) — 같은 절차를 매번 동일하게, 감사 가능한 형태로 수행하게 합니다.
• 셋은 제품 간 재사용(cross-product reuse) — 한 번 만든 스킬을 호환되는 에이전트 어디서든 다시 씁니다.

built-in 커맨드와 무엇이 다른가

Claude Code에서 스킬은 프롬프트 기반(prompt-based)입니다. 고정된 로직을 그대로 실행하는 built-in 커맨드와 달리, 스킬은 Claude에게 상세한 지침을 건네고 Claude가 도구를 동원해 작업을 직접 오케스트레이션하게 합니다³. 즉 스킬은 “이렇게 하라”는 절차서이지, 박혀 있는 함수가 아닙니다.

그래서 같은 일이라도 상황에 맞게 도구 조합을 바꿔 처리할 수 있습니다.

SKILL.md의 내부 구조

SKILL.md는 YAML 프런트매터 + 그 뒤를 잇는 Markdown 본문으로 이루어집니다². 프런트매터는 파일 맨 위에서 --- 마커 두 줄 사이에 놓이고, 그 아래부터 끝까지가 본문입니다. 프런트매터에는 스킬을 식별하는 메타데이터(name, description 등)가, 본문에는 모델이 실제로 따를 지침이 들어갑니다.

이 분리가 점진적 공개의 토대입니다. 메타데이터만 평소에 들고 있다가, 본문은 필요할 때 펼치는 구조가 바로 이 파일 형식에서 나옵니다.

Claude Code에서는 기존 커스텀 커맨드(.claude/commands/deploy.md)가 스킬 체계로 통합됐습니다³. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 동작도 같습니다. 기존 commands/ 파일도 계속 작동하지만, 동명이 충돌하면 스킬이 우선합니다.

따라서 커맨드를 스킬로 옮기는 마이그레이션은 점진적으로 진행할 수 있습니다.

폴더 구조와 보조 파일

표준 레이아웃은 네 갈래입니다². SKILL.md(필수), scripts/(실행 코드), references/(상세 문서), assets/(템플릿·정적 리소스). 그 밖의 임의 파일·디렉터리도 허용됩니다.

my-skill/
├── SKILL.md      # 필수: 메타데이터 + 지침
├── scripts/      # 선택: 실행 코드 (validate.sh, fill.py …)
├── references/   # 선택: 상세 문서 (REFERENCE.md, FORMS.md …)
└── assets/       # 선택: 템플릿·리소스 (template.md, schema.json …)

각 디렉터리는 역할이 분명합니다.

• scripts/에는 실행 코드가 들어갑니다 — 자족적이거나 의존성을 명시하고, 도움이 되는 에러 메시지를 내며, 엣지 케이스를 우아하게 처리하도록 작성합니다. 지원 언어는 에이전트 구현에 따르지만 Python·Bash·JavaScript 등이 흔합니다².
• references/에는 문서를 둡니다 — 기술 레퍼런스(REFERENCE.md), 폼·구조화 데이터(FORMS.md), 도메인별 파일(finance.md, legal.md 등). 개별 파일을 작게 유지하는 것이 핵심인데, on-demand로 로드되므로 작은 파일이 곧 컨텍스트 절약이기 때문입니다².
• assets/에는 정적 리소스를 둡니다 — 문서·설정 템플릿, 이미지, lookup 테이블이나 스키마 같은 데이터 파일입니다².

보조 파일은 반드시 SKILL.md에서 참조하라

보조 파일을 폴더에 넣어 두기만 해서는 안 됩니다. 모델은 SKILL.md에서 언급된 파일만 그 존재와 로드 시점을 인식합니다². 언급되지 않은 파일은 사실상 없는 것과 같습니다. “필드 규칙은 references/field-spec.md를 참고한다”처럼 본문이 명시적으로 가리켜야 모델이 그 파일을 적시에 읽습니다.

참조는 한 단계만 깊이

파일 참조는 항상 skill root 기준 상대경로로 적습니다. 그리고 중요한 제약이 하나 있습니다 — 참조는 SKILL.md에서 한 단계만 깊이(one level deep)로 두라는 것입니다². 즉 SKILL.md → advanced.md까지는 괜찮지만, SKILL.md → advanced.md → details.md처럼 참조가 중첩되면 위험합니다.

그 이유는 메커니즘에 있습니다. Claude는 큰 파일을 읽을 때 head -100처럼 앞부분만 미리 보기로 읽는 경우가 있는데, 중첩 참조의 두 번째 단계 파일이 더 깊은 곳을 가리키면 그 지점에서 정보가 누락될 수 있습니다.

그래서 깊이를 한 단계로 평평하게 유지하는 편이 안전합니다.

Windows 역슬래시 경로 금지

경로는 항상 forward slash(scripts/helper.py)로 적습니다. Windows식 역슬래시(scripts\helper.py)는 쓰지 않습니다 — Unix 스타일 경로라야 전 플랫폼에서 호환되기 때문입니다⁴.

스크립트를 가리킬 때는 “실행하라”는 것인지 “읽어 보라”는 것인지 의도를 명시해야 합니다. Run analyze_form.py는 실행 지시이고, See analyze_form.py for the algorithm은 참조해 읽으라는 뜻입니다⁴. 대부분의 경우 코드를 본문으로 끌어와 읽히기보다 실행하는 쪽이 더 신뢰성 있고 효율적입니다.

코드가 길어도 실행은 출력만 컨텍스트에 들어오기 때문입니다. 아래는 Claude Code 문서의 예시 트리입니다 — SKILL.md(required) 외에 template.md, examples/sample.md, scripts/validate.sh가 곁들여진 형태입니다³.

pdf-skill/
├── SKILL.md
├── template.md
├── examples/
│   └── sample.md
└── scripts/
    └── validate.sh

필수 프런트매터: name

오픈 스펙에서 name은 필수이며 검증 규칙이 까다롭습니다². 1–64자 길이에, 유니코드 소문자 알파벳과 숫자(a-z, 0-9), 그리고 하이픈(-)만 허용됩니다. 추가로 세 가지 금지 규칙이 있습니다 — 하이픈으로 시작하거나 끝낼 수 없고, 연속 하이픈(--)이 불가하며, 부모 디렉터리 이름과 일치해야 합니다.

유효	무효	이유
pdf-processing	PDF-Processing	대문자 사용
data-analysis	-pdf	하이픈으로 시작
code-review	pdf--processing	연속 하이픈

Anthropic best-practices는 여기에 두 가지를 더 얹습니다⁴. name에 XML 태그를 쓸 수 없고, 예약어 anthropic·claude는 사용할 수 없습니다. 명명 방식은 동명사형(gerund, verb+-ing)을 권장합니다 — processing-pdfs, analyzing-spreadsheets처럼 동작을 드러내는 이름입니다.

대안으로 명사구(pdf-processing)도 좋습니다. 반면 helper·utils·tools(모호함), documents·data(과도하게 일반적), anthropic-helper·claude-tools(예약어 포함)는 피해야 합니다⁴.

Claude Code에서 name은 사실 ‘선택’이다

스펙상 name은 필수지만, Claude Code 한정으로는 실제로 선택(No)입니다³. 생략하면 디렉터리 이름이 display name으로 쓰입니다. 더 중요한 점은, 스킬을 부르는 커맨드명이 프런트매터의 name이 아니라 폴더 위치에서 온다는 것입니다.

예를 들어 .claude/skills/deploy-staging/에 두면 프런트매터와 무관하게 /deploy-staging으로 호출됩니다. 예외는 단 하나, 플러그인 루트의 SKILL.md에서만 name이 커맨드명을 결정합니다.

필수 프런트매터: description

description은 비어 있으면 안 되는(non-empty) 필수 필드이고, 길이는 1–1024자입니다². 내용으로는 무엇을 하는지 + 언제 쓰는지 둘 다 담아야 하며, 관련 작업을 식별할 구체적 키워드를 포함해야 합니다. 이 한 줄이 결정적인 이유는, 스킬이 100개를 넘어가도 Claude가 어느 스킬을 지금 꺼낼지를 거의 전적으로 description만 보고 판단하기 때문입니다⁴. 스킬당 정확히 하나의 description을 둡니다.

best-practices에는 결정적 작성 규칙이 있습니다 — 반드시 3인칭(third person)으로 쓰라는 것입니다⁴. description은 system prompt에 그대로 주입되므로, 1인칭(I can help...)이나 2인칭(You can use...)으로 쓰면 모델이 스킬을 발견·매칭하는 데 문제가 생깁니다. 그리고 name과 마찬가지로 XML 태그는 금지입니다.

# 좋은 예 — 무엇을(extract/fill/merge) + 언제(PDF 작업 시) + 키워드
description: >
  Extract text and tables from PDF files, fill forms, merge documents.
  Use when working with PDF files or when the user mentions PDFs, forms,
  or document extraction.

# 나쁜 예 — 모호하고 트리거 단서가 없음
description: Helps with PDFs.
description: Processes data.
description: Does stuff with files.

핵심 use case를 맨 앞에 두어라

description 자체 상한은 1024자이지만, Claude Code의 스킬 listing에서는 description과 when_to_use를 합친 텍스트가 1,536자에서 잘립니다(truncate)³. 이 한계는 maxSkillDescriptionChars로 조정할 수 있지만, 기본 동작을 전제로 가장 중요한 use case를 문장 맨 앞에 배치하는 것이 안전합니다. 잘리더라도 핵심 트리거가 살아남도록 말입니다.

참고로 Claude Code에서 description을 아예 생략하면 markdown 본문의 첫 문단이 description으로 쓰입니다³.

점진적 공개 3단계

스킬이 컨텍스트를 아끼는 비결은 3단계 로딩, 즉 점진적 공개입니다. 각 단계의 토큰 규모와 메커니즘은 다음과 같습니다.

1. 발견(Discovery) — 메타데이터, 약 100토큰. 시작(startup) 시 모든 스킬의 name·description만 system prompt로 로드됩니다⁵. 스킬 하나당 약 100토큰이라, 수십 개를 들고 있어도 footprint가 작습니다.
2. 활성화(Activation/Instructions) — 5천 토큰 미만 권장. 들어온 작업이 어떤 스킬의 description과 맞으면, 그제야 그 SKILL.md 본문 전체가 컨텍스트로 로드됩니다⁵.
3. 실행(Execution/Resources) — 필요할 때만. 본문이 가리키는 references/·assets/ 파일은 실제로 필요한 순간에만 로드됩니다. scripts/의 코드는 bash로 실행되어 출력만 토큰을 소모하고, 코드 본문 자체는 컨텍스트를 차지하지 않습니다⁵. 그래서 큰 파일이라도 읽기 전에는 컨텍스트 패널티가 없습니다.

이 구조를 떠받치는 것은 파일시스템 모델입니다. metadata를 preload하고, 파일은 bash나 Read로 on-demand 읽으며, 스크립트는 내용을 로드하지 않고 실행합니다 — 이 세 동작이 결합돼 큰 파일에도 컨텍스트 패널티가 붙지 않습니다⁵. best-practices는 이를 한 문장으로 압축합니다.

“컨텍스트 윈도우는 공공재(public good)다.”⁴ startup에는 metadata만 preload하고, SKILL.md는 관련될 때만 읽으며, 그렇게 로드된 본문조차 다른 대화·컨텍스트와 토큰을 두고 경쟁하므로 간결해야 합니다.

Claude는 이미 똑똑하다 — 모르는 것만 적어라

점진적 공개의 기본 가정은 *“Claude는 이미 매우 똑똑하다”*는 것입니다⁴. 그러니 Claude가 모르는 것만 본문에 추가하면 됩니다. PDF가 무엇인지, 흔한 라이브러리를 어떻게 쓰는지는 설명할 필요가 없습니다.

같은 지침이라도 간결하면 약 50토큰, 장황하면 약 150토큰까지 부풉니다. 본문이 로드되는 순간 이 차이가 곧 다른 작업에서 쓸 토큰을 깎아먹습니다.

본문 작성 규칙과 안티패턴

SKILL.md 본문은 500줄 이하로 유지하기를 권장합니다 — 스펙·best-practices·Claude Code 문서가 모두 같은 기준을 제시합니다²⁴. 초과하면 별도 파일로 분리합니다. 그리고 100줄을 넘는 reference 파일에는 상단에 목차(table of contents)를 둡니다⁴. Claude가 부분 미리보기로 읽을 때조차 전체 범위를 파악하게 하기 위함입니다.

작성의 큰 원칙은 자유도(degrees of freedom)를 작업의 취약성에 맞추라는 것입니다⁴. 비유하자면, 양쪽이 절벽인 좁은 다리를 건너야 하는 작업은 자유도를 낮게, 위험이 없는 들판을 걷는 작업은 자유도를 높게 둡니다.

자유도	적합한 상황	작성 방식
High	여러 접근이 모두 유효	텍스트 지침으로 방향만 제시
Medium	정해진 틀 + 약간의 변주	파라미터 있는 의사코드/스크립트
Low	한 치도 어긋나면 안 됨	정확한 스크립트 + “명령을 수정하지 마라”

흔한 안티패턴들

• 선택지를 너무 많이 늘어놓지 마라. pypdf·pdfplumber·PyMuPDF를 다 나열하면 모델이 갈팡질팡합니다. 기본값 하나를 정하고, 예외 상황을 위한 escape hatch만 덧붙입니다⁴.
• voodoo constants 금지. TIMEOUT = 47 같은 값을 근거 없이 박지 마십시오. 모든 값은 정당화하고 문서화합니다(Ousterhout’s law)⁴.
• 스크립트가 Claude에게 punt하지 않게 하라. 에러를 모델에게 떠넘기지 말고 스크립트가 직접 처리합니다⁴.
• 시간 민감 정보 금지. “2025년 8월 전에는 구 API”처럼 시점에 묶인 서술은 피하고, 대신 <details>로 ‘Old patterns’ 섹션을 만들어 접어 둡니다⁴.
• 용어를 통일하라. API endpoint/field/extract를 하나로 고정하고, URL·route·path를 섞어 쓰지 않습니다⁴.

평가는 문서화보다 먼저입니다. 광범위한 문서화에 들어가기 전에 평가(eval) 3개를 먼저 작성하라는 것이 best-practices의 권고입니다⁴. 평가는 evals.json 포맷({skills, query, files, expected_behavior})으로 적고, 실제로 사용할 모든 모델 — Haiku·Sonnet·Opus — 로 테스트합니다.

모델마다 스킬을 다르게 해석할 수 있기 때문입니다.

MCP 도구를 본문에서 부를 때는 완전수식명(ServerName:tool_name)을 써야 합니다. 예를 들어 BigQuery:bigquery_schema처럼 적습니다 — prefix를 빠뜨리면 ‘tool not found’가 납니다⁴. 또한 패키지 가용성에 주의해야 합니다.

claude.ai에서는 npm·PyPI 설치가 가능하지만, Claude API 실행 환경에서는 네트워크·런타임 설치가 불가능합니다. 필요한 패키지는 SKILL.md에 미리 명시해 둡니다⁴.

Claude Code 확장 프런트매터 필드

오픈 스펙의 필수 필드는 name·description 둘뿐이지만, Claude Code는 그 위에 다수의 확장 필드를 얹습니다. 모두 선택이고 description만 권장됩니다³. 자주 쓰는 것들을 살펴봅니다.

호출 제어 필드는 다음과 같습니다.

• disable-model-invocation: true로 두면 Claude의 자동 호출이 차단되어 사용자만 /name으로 부를 수 있고, 서브에이전트 preload도 막히며, description이 컨텍스트에서 빠집니다(기본 false). /deploy·/commit처럼 부수효과(side-effect)가 있는 작업에 적합합니다³.
• user-invocable: false는 반대로 / 메뉴에서 스킬을 숨겨 Claude만 호출하게 합니다(기본 true). 배경지식용 스킬(legacy-system-context 등)에 씁니다. 단 이 필드는 메뉴 가시성만 제어하며 Skill 도구를 통한 접근은 막지 않습니다³.

allowed-tools는 ‘제한’이 아니라 ‘사전승인’이다

allowed-tools는 스킬이 활성일 때 승인 없이 쓸 도구를 지정합니다. 공백/콤마로 구분한 문자열이나 YAML 리스트로 적습니다(예: Bash(git add *) Bash(git commit *)). 흔한 오해와 달리 이것은 도구를 제한하는 게 아니라 사전승인하는 것입니다 — 나열되지 않은 도구도 여전히 호출될 수 있습니다.

프로젝트의 .claude/skills/에 둔 경우 workspace trust를 수락해야 적용됩니다³. 참고로 오픈 스펙은 allowed-tools를 아직 experimental로 표시하며, 지원 여부는 에이전트 구현마다 다를 수 있다고 명시합니다². 진짜로 도구를 빼고 싶다면 disallowed-tools를 씁니다 — 스킬이 활성인 동안 도구 풀에서 제거하고, 다음 메시지를 보내면 해제됩니다³.

실행 컨텍스트 필드는 다음과 같습니다.

• context: fork는 스킬을 forked 서브에이전트 컨텍스트에서 실행합니다 — 이 모드에서는 대화 이력에 접근할 수 없고, SKILL.md 내용 자체가 프롬프트가 됩니다. 명시적 task가 있는 스킬에만 의미가 있습니다³.
• agent는 context: fork일 때 서브에이전트 타입(Explore·Plan·general-purpose 또는 .claude/agents/의 커스텀)을 고르며, 생략하면 general-purpose입니다³.
• model/effort는 스킬이 활성인 동안 모델과 effort(low/medium/high/xhigh/max)를 오버라이드하되, 현재 턴에만 적용되고 끝나면 세션 모델로 돌아갑니다³.

그 밖에 when_to_use, argument-hint, arguments, paths(글롭으로 활성 범위 제한), hooks, shell(bash/powershell)이 있습니다³. 여기에 더해 오픈 스펙이 정의한 옵션 필드 license·compatibility·metadata도 그대로 쓸 수 있습니다².

문자열 치환과 동적 컨텍스트 주입

본문 안에서 인자와 환경값을 치환할 수 있습니다. $ARGUMENTS(전체 인자), $ARGUMENTS[N]/$N(0-based 개별 인자), $name(arguments로 선언한 이름), ${CLAUDE_SESSION_ID}, ${CLAUDE_EFFORT}, 그리고 스크립트 경로 해석에 쓰는 ${CLAUDE_SKILL_DIR}이 그것입니다³.

더 강력한 것은 동적 컨텍스트 주입입니다. 백틱으로 감싼 !`command`(줄 시작 또는 공백 직후에서만 인식)와 ```! 펜스 블록은 Claude가 보기 전에 셸에서 실행되어 그 출력으로 치환됩니다 — 일종의 preprocessing입니다³. 예를 들어 현재 git 상태를 스킬 본문에 미리 끼워 넣을 수 있습니다.

현재 변경 사항:
!`git status --short`

셸 실행은 차단 가능하다

!`command` 동적 주입은 disableSkillShellExecution 설정으로 끌 수 있습니다³. 신뢰할 수 없는 스킬을 들여올 때는 이 동작이 의도치 않은 명령을 실행할 수 있으니 점검 대상입니다.

스킬 위치·스코프·우선순위

Claude Code에서 스킬이 적용되는 범위는 위치로 정해집니다³.

위치	경로	적용 범위
Enterprise	managed settings	조직 전체
Personal	~/.claude/skills/<name>/SKILL.md	모든 프로젝트
Project	.claude/skills/<name>/SKILL.md	해당 프로젝트
Plugin	<plugin>/skills/<name>/SKILL.md	플러그인이 활성인 곳

동명이 충돌하면 우선순위는 enterprise > personal > project 순이고, 어느 레벨이든 동명의 bundled skill을 override합니다³. 플러그인 스킬은 plugin-name:skill-name 네임스페이스를 쓰므로 애초에 충돌하지 않습니다.

중첩 .claude/skills/도 로드됩니다. 시작 디렉터리부터 repo 루트까지의 모든 상위 디렉터리, 그리고 작업 중인 하위 디렉터리에서 on-demand로 잡힙니다 — 덕분에 모노레포의 각 패키지가 자기 스킬을 제공할 수 있습니다³. 중첩 스킬이 동명이면 둘 다 유지되며, 중첩본은 디렉터리 한정명으로 노출됩니다.

예를 들어 /deploy는 루트 스킬, /apps/web:deploy는 apps/web 아래의 중첩본을 가리킵니다³.

—add-dir의 스킬은 예외적으로 로드된다

--add-dir나 /add-dir로 추가한 디렉터리의 .claude/skills/는 예외적으로 로드됩니다. 보통 이 옵션은 파일 접근만 부여하지만 스킬은 예외입니다. 반면 permissions.additionalDirectories 설정으로 추가한 디렉터리의 스킬은 로드되지 않습니다³.

Live change detection 덕분에 ~/.claude/skills/, 프로젝트 .claude/skills/, --add-dir 안의 변경은 재시작 없이 세션 중에 반영됩니다. 다만 세션 시작 시점에 없던 top-level skills 디렉터리를 새로 만드는 경우에는 재시작이 필요합니다.

이 감지는 SKILL.md 텍스트만 커버하며, hooks나 .mcp.json 등의 변경은 /reload-plugins로 따로 반영해야 합니다³.

스킬 콘텐츠 생애주기와 컨텍스트 예산

스킬을 호출하면 렌더된 SKILL.md가 단일 메시지로 대화에 들어와 세션 내내 유지됩니다. Claude Code는 이후 턴에 그 파일을 다시 읽지 않으므로, 작업 전반에 적용돼야 할 지침은 일회성 지시가 아니라 standing instruction(상시 지침)으로 적어야 합니다³.

긴 세션에서 핵심이 되는 것은 auto-compaction 동작입니다. compaction은 호출된 스킬을 토큰 예산 안에서 이월합니다 — 각 스킬의 가장 최근 호출분을 요약 뒤에 다시 붙이되, 각 스킬당 첫 5,000토큰을 유지합니다.

그리고 재첨부되는 스킬들은 합산 25,000토큰의 예산을 공유합니다³. 채우는 순서는 최근 호출된 스킬부터이므로, 오래된 스킬은 통째로 드롭될 수 있습니다.

스킬이 ‘힘을 잃은 것처럼’ 보일 때

첫 응답 이후 스킬의 영향력이 사라진 듯 보여도, 보통은 내용이 그대로 남아 있고 모델이 다른 접근을 고르는 중일 뿐입니다³. 이때는 description과 지침을 더 강하게 쓰거나, 결정론적으로 강제하고 싶다면 hooks를 씁니다. 큰 스킬을 여러 번 호출한 뒤 compaction이 일어났다면, 스킬을 다시 호출해 복원할 수 있습니다.

스킬 listing에도 예산이 있습니다. 모든 스킬의 이름은 항상 포함되지만, description은 예산을 초과하면 단축됩니다³. 기본 예산은 모델 컨텍스트 윈도우의 1%이며, skillListingBudgetFraction 또는 SLASH_COMMAND_TOOL_CHAR_BUDGET로 조정합니다.

초과 시 가장 덜 쓰는 스킬의 description부터 드롭되고, 어떤 스킬이 단축·드롭됐는지는 /doctor로 확인합니다.

서브에이전트는 본문을 미리 받는다

정규 세션은 description만 컨텍스트에 두고 본문은 호출 시점에 로드합니다. 단, preloaded skills를 가진 서브에이전트는 예외입니다 — 시작 시 본문 전체가 주입됩니다³. 그래서 서브에이전트에 붙이는 스킬은 본문 분량이 곧바로 그 에이전트의 시작 컨텍스트 비용이 됩니다.

한 번 만들면 어디서나

Agent Skills 포맷은 Anthropic이 개발한 뒤 오픈 표준으로 공개됐고, 생태계 기여에 열려 있습니다(GitHub agentskills/agentskills)¹. Claude Code 자체도 agentskills.io 오픈 표준을 따르며, 그 위에 호출 제어·서브에이전트 실행·동적 컨텍스트 주입 같은 확장을 얹은 것입니다³.

같은 SKILL.md를 읽는 호환 클라이언트는 공식 showcase 기준으로 넓습니다 — Claude·Claude Code·Gemini CLI·Cursor·GitHub Copilot·VS Code·OpenAI Codex·Goose·OpenCode·OpenHands·Amp·Letta·Roo Code·Kiro·Junie·Factory·Mistral Vibe·Laravel Boost·Spring AI·Databricks/Snowflake 등 다수입니다¹.

검증에는 레퍼런스 라이브러리 skills-ref를 씁니다 — skills-ref validate ./my-skill로 frontmatter와 명명 규칙을 검사합니다².

이식성 메타데이터로는 스펙 표준 옵션 필드인 license, compatibility(최대 500자, 환경 요구사항), metadata(임의 key-value)가 정의돼 있습니다².

예제: 최소 스킬

---
name: pdf-form-filler
description: PDF 양식의 빈 칸을 채운다. 사용자가 PDF 양식 작성·서식 채우기를 요청할 때 사용.
---

# PDF 양식 채우기

1. `scripts/inspect.py`로 양식 필드를 추출한다.
2. 사용자 값과 매핑한다.
3. `scripts/fill.py`로 채운 PDF를 출력한다.

자세한 필드 규칙은 references/field-spec.md를 참고한다.

description만 보고도 “지금 이걸 꺼낼지” 판단되고, 본문은 짧고, 무거운 일은 scripts/에 위임돼 있습니다 — 점진적 공개의 교과서적 형태입니다. references/field-spec.md는 본문에서 명시적으로 참조됐으므로 필요할 때 로드되고, 참조 깊이도 한 단계라 안전합니다.

요약 · 체크리스트

• 스킬은 SKILL.md를 가진 폴더이고, scripts/·references/·assets/는 선택임을 안다.
• name 검증 규칙(1–64자, 소문자·숫자·하이픈, 연속 하이픈·예약어 금지, 디렉터리명 일치)을 안다.
• description을 3인칭으로, ‘무엇을+언제’를 담아 쓰고 핵심 use case를 맨 앞에 둘 줄 안다.
• 점진적 공개 3단계(발견 ~100토큰 → 활성화 <5000토큰 → 실행)와 그 메커니즘을 설명할 수 있다.
• 본문 500줄·one-level-deep 참조·자유도 매칭 같은 작성 규칙과 안티패턴을 안다.
• Claude Code 확장 필드(disable-model-invocation·allowed-tools·context: fork 등)와 스코프 우선순위를 안다.

관련 장

• 2. 점진적 공개
• 3. 도구 호출
• 5. 컨텍스트 엔지니어링

Footnotes

1. Agent Skills — Overview (agentskills.io) ↩ ↩² ↩³ ↩⁴

2. Agent Skills — Specification (agentskills.io) ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴ ↩¹⁵

3. Extend Claude with skills — Claude Code Docs ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴ ↩¹⁵ ↩¹⁶ ↩¹⁷ ↩¹⁸ ↩¹⁹ ↩²⁰ ↩²¹ ↩²² ↩²³ ↩²⁴ ↩²⁵ ↩²⁶ ↩²⁷ ↩²⁸ ↩²⁹ ↩³⁰

4. Skill authoring best practices — platform.claude.com ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴ ↩¹⁵ ↩¹⁶ ↩¹⁷ ↩¹⁸ ↩¹⁹

5. Agent Skills — Specification (Progressive Disclosure), agentskills.io ↩ ↩² ↩³ ↩⁴