[Claude Code 입문 E25] Claude Code 커스텀 스킬 작성: SKILL.md 구조부터 description 최적화까지

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(특정 답) - 본문 패턴 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 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, 정리 📌 참고 링크 - 블로그: https://neosarchizo.github.io/posts/claude-code-25-writing-custom-skills - Extend Claude with skills: https://code.claude.com/docs/en/skills - Agent Skills Specification: https://agentskills.io/specification - Best practices: https://agentskills.io/skill-creation/best-practices - Optimizing descriptions: https://agentskills.io/skill-creation/optimizing-descriptions - Using scripts: https://agentskills.io/skill-creation/using-scripts - Anthropic skills repository: https://github.com/anthropics/skills - PEP 723 — Inline script metadata: https://peps.python.org/pep-0723/ #ClaudeCode #SKILLmd #스킬작성