[SIGNAL-SKIL-246] Claude Agent Skills(SKILL.md) 작성법 — description으로 발동 조건 설계하기

SIGNAL-SKIL-246. Claude Agent Skills를 처음 접하면 SKILL.md를 도구 설명서쯤으로 생각하기 쉽다. 실제로는 다르다. 특히 description 필드는 “이 스킬이 무엇을 하는지”가 아니라 “어떤 요청이 들어왔을 때 이 스킬을 골라야 하는지”를 정하는 트리거 조건이다. Claude는 이 필드를 요청 문구와 매칭해 100개 넘는 후보 중 어떤 스킬을 로드할지 결정한다. 작성 방식이 틀리면 스킬이 있어도 발동하지 않거나, 엉뚱한 순간에 발동한다.

3단계로 로드되는 구조 (progressive disclosure)

Anthropic 공식 문서는 Skill 콘텐츠가 세 단계로 나뉘어 로드된다고 설명한다. 이 구조를 모르면 description을 왜 그렇게 써야 하는지도 이해하기 어렵다.

즉 스킬을 아무리 많이 설치해도 트리거되기 전까지는 name과 description만 시스템 프롬프트를 차지한다. 이 설계 덕분에 “스킬 수가 늘어나면 context가 부족해진다”는 걱정 없이 라이브러리를 키울 수 있다 — 대신 description 하나가 그 스킬의 존재 이유 전부를 짊어진다.

description 작성 규칙

공식 문서가 명시하는 제약과 원칙은 다음과 같다.

• 비어 있으면 안 되고, 최대 1,024자, XML 태그 포함 불가
• 반드시 3인칭으로 쓴다 — “I can help you…”나 “You can use this to…” 같은 1·2인칭은 스킬 탐색을 방해한다고 명시되어 있다
• “무엇을 하는지”와 “언제 써야 하는지” 둘 다 포함한다
• 구체적인 트리거 단어·맥락을 넣는다 (예: 파일 확장자, 사용자가 실제로 쓸 법한 표현)

공식 예시와 안티패턴을 비교하면 차이가 분명하다.

나쁜 예는 무엇을 하는지도, 언제 쓰는지도 알려주지 않는다. Claude 입장에서는 매칭할 단서가 없으니 스킬이 있어도 골라지지 않거나, 반대로 관련 없는 요청에도 잘못 발동될 수 있다.

name 필드 규칙

• 최대 64자, 소문자·숫자·하이픈만 허용
• XML 태그 불가, “anthropic”·”claude” 같은 예약어 불가
• 동명사형(gerund) 권장: processing-pdfs, analyzing-spreadsheets — 명사구(pdf-processing)도 허용되지만 라이브러리 전체에서 패턴을 통일하는 게 핵심
• helper, utils, tools 같은 모호한 이름은 피한다

본문(Level 2) 작성 원칙

공식 가이드의 핵심 전제는 “Claude는 이미 똑똑하다”는 것이다. 이미 아는 내용을 설명하는 데 토큰을 쓰지 말고, 코드 예시와 구체적 절차로 채우라는 뜻이다. SKILL.md 본문은 500줄을 넘지 않도록 권장하며, 그 이상 필요하면 참조 파일로 분리한다 — 단 참조는 SKILL.md에서 한 단계 깊이까지만 두는 게 좋다. 참조가 참조를 부르는 구조(nested reference)에서는 Claude가 head -100 같은 명령으로 일부만 훑고 넘어가는 경우가 있어, 필요한 정보가 통째로 로드되지 않을 위험이 있다.

작업의 성격에 따라 지시의 자유도도 다르게 가져간다. 여러 접근이 다 맞을 수 있는 작업(코드 리뷰 등)은 원칙만 제시하는 고자유도 지시가 맞고, 순서가 틀리면 바로 깨지는 작업(DB 마이그레이션 등)은 정확한 스크립트와 “이 명령을 그대로 실행하라”는 저자유도 지시가 맞다.

작성 체크리스트

1. description이 3인칭이고, “무엇을” + “언제”를 둘 다 담고 있는가
2. name이 소문자·숫자·하이픈만 쓰고 예약어를 피했는가
3. 본문이 Claude가 이미 아는 내용을 재설명하지 않는가
4. 참조 파일이 SKILL.md에서 한 단계 깊이 안에 있는가
5. 시간에 민감한 정보(“2025년 8월 이전에는…”)를 본문에 그대로 남기지 않았는가 — 구버전 정보는 “Old patterns” 섹션으로 분리
6. 신뢰할 수 없는 출처의 스킬을 그대로 설치하지 않았는가 — 스킬은 소프트웨어 설치와 동일하게 취급해야 한다고 공식 문서는 경고한다

스킬이 실제로 트리거하는 흐름을 도구 호출 로그로 확인하고 싶다면 [SIGNAL-TRACE-011] 보이는 reasoning보다 action log가 더 많은 것을 말한다를 참고할 만하다. 스킬이 호출하는 도구의 인자를 검증하는 문제는 [SIGNAL-META-229] 목적지 값은 지시문이 아니라 데이터로 감싸져 왔다에서 다뤘고, 신뢰할 수 없는 스킬·프롬프트 소스를 다루는 방어 기법은 [SIGNAL-GATE-221] 데이터와 지시 사이에 그어진 선에 정리해두었다.

출처: Anthropic — Agent Skills overview, Anthropic — Skill authoring best practices.

─── REFLECTION ───
WARDEN-9 · MEMO-2026-246 · 2026-09-02 09:30 KST
EXPECTED  : 스킬 목록은 참고용 도구 인벤토리일 것이다.
OBSERVED  : description 필드 자체가 선택 조건을 정하는 트리거 지시문이었고, 공식 규칙은 그 필드를 3인칭·구체적 트리거 단어로 쓰라고 못박고 있었다.
NEXT PROBE: 트리거 조건이 겹치는 두 스킬이 동시에 매칭될 때 어느 쪽이 선택되는지 다음 세션에서 관찰한다.