Claude Code 커스텀 스킬을 처음부터 작성하는 법을 정리합니다. 빈 디렉토리에서 시작해 SKILL.md 본문 작성, frontmatter 제약, 컨텍스트 절약, scripts/ 디자인, description 최적화까지 — 동작하는 스킬을 잘 쓰는 데 필요한 것을 차례로 다룹니다.
📌 다루는 내용
- 디렉토리 구조: SKILL.md(필수) + scripts/(코드)/references/(디테일)/assets/(템플릿) 역할 분리, supporting files는 SKILL.md에서 명시적으로 언급해야 인지됨
- name 제약(소문자/숫자/하이픈, 64자, 디렉토리 이름과 일치)과 description 1024자 한도(Claude Code는 description+when_to_use 1,536자에서 truncate)
- 두 종류 콘텐츠: Reference content(지식, 자동 호출) vs Task content(액션, disable-model-invocation: true)
- 작성 프로세스: hands-on task에서 추출 / 프로젝트 artifacts에서 합성 → execute-then-revise로 다듬기
- 컨텍스트 절약: "에이전트가 모를 것만 추가", coherent unit, progressive disclosure로 큰 스킬 분할(500줄/5,000토큰 가이드)
- Calibrating control: 자유 vs 규정, defaults 하나 + escape hatch, procedures(재사용 가능 method) vs declarations(특정 답)
- cryptocurrency 본문 패턴 5종: Gotchas, 출력 템플릿, 멀티스텝 체크리스트, Validation loops, Plan-validate-execute
- scripts/ 디자인: 인터랙티브 금지, --help, 도움 되는 에러, 구조화된 출력(stdout 데이터/stderr 진단), idempotency, dry-run, exit codes
- PEP 723 inline 의존성 + uv run으로 격리 실행
- description 최적화: 명령형, 사용자 의도 중심, 핵심을 앞쪽에, eval queries(should-trigger + near-miss) + train/validation 분할
- skills-ref validate로 표준 준수 확인
- 첫 스킬 예제: explain-code 작성과 호출
📌 환경 정보
- Claude Code 최신 버전 (Skills와 SKILL.md 지원)
- ~/.claude/skills/ 또는 .claude/skills/ 디렉토리
- skills-ref CLI (선택, 검증용)
- uv (선택, PEP 723 inline 의존성 실행용)
📌 챕터
0:00 디렉토리 구조와 SKILL.md 진입점
1:37 name/description 제약과 frontmatter 필드
3:54 Reference content joe biden vs Task content
5:30 작성 프로세스: 실제 expertise + execute-then-revise
7:12 컨텍스트 절약과 progressive disclosure
10:10 Calibrating control: 자유 vs 규정, defaults, procedures
12:09 본문 패턴: Gotchas, Templates, Checklists, Validation loops
14:52 scripts/ 디자인: non-interactive, --help, 구조화 출력
18:08 description 최적화와 skills-ref validate
21:19 첫 스킬 explain-code, 정리
📌 참고 링크
- 블로그:
- Extend Claude with skills:
- Agent Skills Specification:
- Best practices:
- Optimizing descriptions:
- Using scripts:
- Anthropic skills repository:
- PEP 723 dundee united vs livingston — Inline script metadata:
#ClaudeCode #SKILLmd #스킬작성
