스킬 작성 베스트 프랙티스

공식 컨벤션: 바인딩 규칙은 docs/rules/skill-convention.md 참조. 이 문서는 튜토리얼/참고 자료로 유지됩니다.

Claude Code 스킬을 효과적으로 작성하기 위한 가이드입니다. 기존 03-skills/ 스킬 분석을 기반으로 합니다.

스킬 기본 구조

my-skill/
├── skill.md              ← 메인 스킬 정의 (필수)
├── references/           ← 참조 파일 (선택)
│   ├── schema.md
│   └── patterns.md
├── examples/             ← 예시 파일 (선택)
│   └── example-output.md
└── scripts/              ← 보조 스크립트 (선택)
    └── helper.sh

Frontmatter 필드 가이드

---
name: my-skill              # 고유 이름 (kebab-case)
description: |              # 스킬 설명 (자동 호출 트리거에 사용!)
  Use this skill when...    # 영문으로 시작, 트리거 조건 명시
  Examples: "키워드1", "키워드2"
model: sonnet               # 사용 모델 (opus/sonnet/haiku)
color: blue                 # 표시 색상
tools:                      # 허용 도구 목록
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - WebFetch
  - WebSearch
permissionMode: default     # 권한 모드 (default/allowAll/denyAll)
---

핵심 필드 상세

Description 작성법 (자동 호출 최적화)

Description은 스킬이 자동으로 호출되는 핵심 트리거입니다. Claude는 사용자 요청과 description을 매칭하여 스킬 호출 여부를 결정합니다.

좋은 예

description: |
  Use this skill when the user asks to extract reusable code from a project.
  Trigger keywords: "코드 추출", "재사용 코드 정리", "패키징", "라이브러리화",
  "kdyextract", "extract reusable code"

나쁜 예

description: "코드를 추출합니다"   # 너무 짧고 트리거 키워드 없음

작성 원칙

1. 영문으로 시작: "Use this skill when..." 패턴
2. 트리거 키워드 명시: 한/영 혼합 키워드
3. 예시 포함: 실제 사용자 요청 예시
4. 범위 명확화: 이 스킬이 하는 것과 하지 않는 것 구분

500줄 이하 원칙

왜?

• Claude의 컨텍스트 효율성 유지
• 핵심 로직에 집중
• 관리 용이성

초과 시 전략

skill.md (핵심 프로세스만, <500줄)
  ├── references/detailed-rules.md (상세 규칙)
  ├── references/patterns.md (패턴/예시)
  └── references/schema.md (데이터 구조)

skill.md에서 참조:

상세 규칙은 `references/detailed-rules.md` 참조.

또는 동적 컨텍스트 주입:

!`cat references/detailed-rules.md`

변수 치환

활용 예

사용자가 제공한 인수: $ARGUMENTS

이 인수를 분석하여 작업 대상을 결정하세요:
- 파일 경로면 → 해당 파일 처리
- 키워드면 → 검색 후 처리
- 비어있으면 → 전체 프로젝트 대상

동적 컨텍스트 주입 (Dynamic Context Injection)

!`command` 구문으로 스킬 로드 시 명령 실행 결과를 주입합니다.

활용 예

## 현재 프로젝트 상태

!`cat docs/status/current.md 2>/dev/null || echo "상태 파일 없음"`

## Git 상태

!`git status --short 2>/dev/null || echo "Git 저장소 아님"`

## 최근 변경 파일

!`git diff --name-only HEAD~3 2>/dev/null | head -20`

주의사항

• 명령 실행은 스킬 로드 시 1회만 실행
• 실행 실패 시 빈 문자열 반환 (에러 핸들링 필수)
• 무거운 명령은 로드 시간 증가

context:fork 격리 실행

스킬 실행을 별도 컨텍스트에서 격리하여 메인 세션에 영향을 주지 않습니다.

---
name: heavy-analysis
context: fork
---

사용 시점

• 대량의 파일을 읽는 분석 작업
• 실험적/파괴적일 수 있는 작업
• 메인 컨텍스트 오염 방지가 필요할 때

동작

• 스킬 실행이 별도 프로세스(서브에이전트)로 분리
• 스킬 완료 후 결과만 메인 세션으로 반환
• 메인 세션의 컨텍스트 윈도우 절약

위치별 적용범위

같은 이름의 스킬이 여러 위치에 있으면, 가장 가까운(프로젝트) 것이 우선합니다.

기존 스킬 패턴 분석

03-skills/ 스킬들의 공통 패턴

개선 포인트

1. Description 표준화: 영문 트리거 + 한글 키워드 패턴 통일
2. 참조 파일 분리: 500줄 초과 스킬은 references/ 활용
3. 에러 처리: 실패 시 복구 경로 명시
4. 테스트 가능성: 예시 입력/출력 포함으로 검증 용이성 확보

스킬 작성 체크리스트

• name이 고유하고 kebab-case인가?
• description에 영문 트리거와 한글 키워드가 포함되었는가?
• 500줄 이하인가? (초과 시 references/ 분리)
• $ARGUMENTS 활용이 적절한가?
• 에러/실패 시 복구 경로가 있는가?
• 출력 포맷이 명확하게 정의되었는가?
• 불필요한 도구 접근 없이 최소 권한인가?