Claude 커스텀 스킬은 반복 프롬프트, 검증 규칙, 템플릿, 스크립트, 참고 문서를 하나의 디렉터리로 묶어 에이전트가 필요할 때 불러 쓰게 하는 방식이다. 핵심 파일은 SKILL.md이며, 나머지 references/, scripts/, assets/는 선택 사항이다.

기본 구조

my-skill/
├── SKILL.md
├── references/
├── scripts/
└── assets/

SKILL.md에는 YAML frontmatter와 실행 지침을 둔다. Claude Code에서는 description이 가장 중요하다. 모델은 시작 시 전체 스킬 본문을 읽지 않고 이름과 설명 같은 메타데이터만 보고 관련 여부를 판단한다. 스킬이 선택되면 그때 본문을 읽고, 추가 파일은 필요할 때만 연다.

위치

Claude Code의 슬래시 명령 이름은 보통 디렉터리명에서 온다. 예를 들어 .claude/skills/deploy-staging/SKILL.md는 /deploy-staging으로 호출한다.

작성 원칙

• description은 “언제 이 스킬을 써야 하는가”를 구체적으로 쓴다.
• SKILL.md 본문은 짧게 두고 상세 기준은 references/로 분리한다.
• 결정적 계산은 스크립트가 하고, Claude는 해석과 권고를 맡게 한다.
• 스크립트와 규칙 문서가 서로 모순되지 않게 테스트한다.
• 새 스킬은 실제 입력 3~5개로 수동 테스트한다.

allowed-tools 주의

Claude Code에서 allowed-tools를 쓸 때는 넓은 패턴을 피한다. 예를 들어 Bash(python3 *)처럼 모든 Python 실행을 허용하면 과하다. ${CLAUDE_SKILL_DIR} 기반으로 스킬 내부 스크립트만 허용하는 식으로 좁히는 편이 낫다.

관련 문서

• agent-skills — AI 에이전트 스킬 시스템 개요
• agent-skills-tips-pitfalls — 스킬 작성·리뷰에서 자주 나오는 실수
• agent-skills-tips-engineering — 엔지니어링 워크플로를 스킬로 만드는 원칙

참고 자료

• How to Create Custom Skills in Claude: A Step-by-Step Guide — Analytics Vidhya (2026-07-29)