예시 실습
이 핸즈온랩은 교육 내용을 보여 드리기 위한 예시입니다. 실제 교육과정에서는 고객사의 산업과 직무를 반영한 실습 시나리오로 구성한 비공개 학습 사이트를 따로 제공합니다.
M5-2. 스킬 작성 모범 사례 — 제때 실행되고, 일관된 결과를
한 줄 요약 — 좋은 스킬의 조건: 트리거 문구가 든 description + 번호 단계 워크플로 + 고정된 출력 형식 + 참조는 references로. 가장 흔한 실패 원인은 이름 규칙(kebab-case·폴더명 일치) 위반입니다.
1. 필수 frontmatter
| 필드 | 제약 | 역할 |
|---|---|---|
name |
1~64자 · kebab-case · 폴더명과 정확히 일치 | 스킬 식별자 |
description |
1~1024자 | 실행 여부 판단 근거 — 트리거 문구 꼭 포함 |
# 좋음 — 구체적 트리거
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원칙
- 워크플로로 구성 — 번호 단계로 쓰고, 단계마다 구체적인 행동(파일 읽기·도구 호출·출력 생성)을 적기
- 출력 형식 명시 — 표·목록·문서 구조를 그대로 보여 주면 결과가 훨씬 일관됨
- 도구는 이름으로 참조 — “
search_case_law도구를 사용해…” - 본문은 짧게 — 1,500~2,000단어를 목표로, 3,000단어가 넘으면 references로 분리
- 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)