M5-2. 스킬 작성 모범 사례 — 발동하고, 일관되게

한 줄 요약 — 좋은 스킬의 공식: 트리거 문구가 든 description + 번호 단계 워크플로 + 고정된 출력 형식 + 참조는 references로. 이름 규칙(kebab-case·폴더 일치)이 최다 실패 원인입니다.

1. 필수 frontmatter

# 좋음 — 구체적 트리거
description: |
  Analyzes bond relative value using Z-spreads, ASW spreads, and butterfly analysis.
  Use when user asks to "analyze bond spreads", "compare bonds", "relative value".

# 나쁨 — 모호
description: Provides bond analytics capabilities.

이름 규칙: 소문자·하이픈만 (my-skill ✅ · My_Skill·--x--·a--b ❌)

2. 본문 작성 5원칙

1. 워크플로로 구조화 — 번호 단계, 각 단계 = 구체 행동(파일 읽기·도구 호출·출력 생성)
2. 출력 형식 명시 — 표·목록·문서 구조를 그대로 보여주면 일관성 급상승
3. 도구는 이름으로 참조 — “search_case_law 도구를 사용해…”
4. 본문은 슬림하게 — 1,500~2,000단어 목표, 3,000단어 넘으면 references로 분리
5. 3계층 로딩 활용 — frontmatter(~100토큰, 상시) → 본문(발동 시) → references(필요 시)

3. 동반 파일 규칙

• 최대 20개 · 파일당 5MB · 스킬당 총 10MB · 다운로드 타임아웃 15초
• 상대 경로만 · .. 금지 · 백슬래시·널 금지 · 숨김 파일 금지 · Windows 예약어 금지
• SKILL.md에서 references를 명시적으로 안내 (“## Additional Resources”)

4. 하지 말 것

• ❌ 시크릿을 SKILL.md에 — 자격 증명은 커넥터 인증으로
• ❌ 빌트인 13종과 중복 스킬
• ❌ “법률 문서 다 해줘” 같은 광범위 스킬 — 계약 분석·조항 추출로 쪼개기
• ❌ 파일 경로·시스템 명령 하드코딩 — 이식성 파괴

5. 크로스 플랫폼

같은 SKILL.md가 Claude Code · Claude.ai Projects · VS Code/GitHub Copilot · Gemini CLI · JetBrains Junie · OpenAI Codex · Cursor에서 동작합니다. 양쪽을 노린다면 Claude 플러그인 구조(슈퍼셋)로 시작 → 변환이 정석 — M5-4.

출처

출처: Build plugins — Skill authoring best practices·Validation rules (MS Learn)