Claude Skills 관리 가이드

Skills가 뭔가요?

Claude Code에서 /commit, /review 같은 슬래시 명령어를 직접 만들 수 있는 기능이다. SKILL.md 파일 하나에 Claude가 따라야 할 지시사항을 적으면, 그게 곧 하나의 Skill이 된다.

---
name: deploy
description: "프로덕션 배포 파이프라인. '배포해줘' 등 언급 시 호출"
---

# Deploy

배포 절차:
1. 테스트 실행
2. 빌드
3. 배포

이게 전부다. /deploy를 입력하면 Claude가 이 지시사항대로 움직인다.

공식 문서: Extend Claude with skills

대부분이 놓치는 것: Description이 트리거다

Skill이 동작하려면 Claude가 "이 상황에서 이 Skill을 써야겠다"고 판단해야 한다. 그 판단 근거가 description 필드 하나뿐이다.

# ❌ 나쁜 예 — Claude가 언제 쓸지 모른다
description: "도구 관련 작업"

# ✅ 좋은 예 — 무엇을 하고, 언제 쓰는지 명확
description: "현재 브랜치를 commit → push → PR → merge까지 처리. '배포해줘', 'ship' 등 언급 시 호출"

원칙: "무엇을 하는가" + "언제 쓰는가(트리거 키워드)" 둘 다 포함.

Gotchas 섹션 — Skills에서 가장 중요한 부분

Gotchas는 Claude가 이 Skill을 실행할 때 자주 실수하는 지점을 기록하는 섹션이다.

공식 Best Practices에서 이렇게 말한다:

"Build a Gotchas section in every skill — this is considered the highest-signal content."

다른 어떤 설명보다 Gotchas가 Claude의 행동에 가장 강하게 영향을 준다.

왜 중요한가

Claude는 매 세션마다 기억이 초기화된다. 지난번에 실패한 걸 다음번에도 똑같이 반복한다. Gotchas에 적어두면 매 실행 시 자동으로 읽히므로, 같은 실수를 방지할 수 있다.

작성 구조

## Gotchas

- **verify.sh 미존재 상태에서 VERIFY 진입**
  - What happens: "No such file" 에러로 FAIL 루프에 빠짐
  - How to fix: Phase 1에서 verify.sh 존재 여부를 먼저 확인
  - Prevention: 컨텍스트 수집 시 verify.sh 존재를 필수 체크 항목으로 포함

3요소 구조:

핵심 원칙: "상상 X, 실패 O"

Gotchas를 미리 상상해서 채우지 않는다. 실제로 발생한 실패만 기록한다.

실패 발생 → 원인 분석 → Gotchas에 추가 → 다음 실행에서 자동 방지

추가 기준:

• 같은 유형의 실패가 2회 이상 발생
• 또는 1회라도 복구에 5분 이상 소요된 심각한 실패

점진적 공개 — 500줄의 벽

Claude가 Skill을 실행할 때의 로딩 순서:

1. 1단계: 모든 Skill의 name + description만 로드 (트리거 매칭)
2. 2단계: 선택된 Skill의 SKILL.md 전체 로드
3. 3단계: SKILL.md 내 링크된 파일은 필요할 때만 Read

SKILL.md가 500줄을 넘으면 컨텍스트를 과도하게 소비한다. 해결책은 점진적 공개(Progressive Disclosure) — 핵심 흐름은 SKILL.md에, 상세는 별도 파일에.

Before vs After

Before — 단일 파일에 모든 내용:

init-project/
└── SKILL.md    ← 467줄

After — 핵심 흐름 + 참조 파일로 분리:

init-project/
├── SKILL.md              ← 134줄 (흐름 + Gotchas)
├── phase-research.md     ← 62줄
├── phase-scaffold.md     ← 128줄
└── init-plan-template.md ← 73줄

SKILL.md에서는 링크로 참조만 한다:

## Phase 2: RESEARCH
기술 스택 후보를 조사한다.
상세 절차는 [phase-research.md](phase-research.md) 참조.

Claude는 Phase 2에 진입할 때만 phase-research.md를 읽는다. 나머지 Phase의 상세 파일은 로드되지 않는다.

분리 기준

파일명과 프론트매터 — 사소하지만 치명적인 실수들

파일명은 반드시 SKILL.md (대문자)

• O my-skill/SKILL.md
• X my-skill/skill.md — 인식 불안정

프론트매터 누락

프론트매터가 없으면 description 매칭이 불가능하다.

# ❌ 프론트매터 없이 바로 시작
# My Skill
이렇게 시작하면 Claude가 자동으로 매칭할 수 없다.

# ✅ 프론트매터 필수
---
name: my-skill
description: "..."
---

argument-hint로 사용법 힌트

argument-hint: "[기능명 또는 작업 설명]"

/my-skill을 입력할 때 자동완성에 힌트가 표시된다. 선택사항이지만 UX가 좋아진다.

전역 vs 프로젝트 — 같은 이름의 Skill 충돌?

같은 이름의 Skill이 전역과 프로젝트에 모두 있으면, 프로젝트 Skill이 우선한다.

이걸 일부러 활용할 수 있다:

공통 로직은 전역에, 프로젝트별 맞춤은 로컬에 — 이게 의도된 오버라이드 패턴이다.

Hook으로 Gotchas 자동 수집하기

Gotchas의 가장 큰 문제는 수동으로 추가해야 한다는 점이다. 실패가 발생해도 까먹으면 기록되지 않는다.

이걸 Stop Hook으로 반자동화할 수 있다.

동작 원리

1. Skill 실행 중 실패 발생
2. Claude 응답 종료 시 Stop 이벤트 발생
3. gotchas-collector.js가 대화 내역에서 실패 패턴 감지 (verify FAIL, merge 충돌 등)
4. 어떤 Skill이 실행 중이었는지 매칭 + 이미 Gotchas에 있는 실패인지 중복 체크
5. 새로운 실패면 exit 2로 종료 → Claude에게 피드백 전달
6. Claude가 "Gotchas에 추가할까요?" 질의 → 승인 시 SKILL.md에 자동 추가

핵심 코드 (간략화)

// settings.json — Stop 훅 등록
{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "node $HOME/.claude/hooks/gotchas-collector.js"
      }]
    }]
  }
}

// gotchas-collector.js — 실패 감지 패턴 예시
const FAILURE_PATTERNS = [
  { pattern: /verify\.sh.*FAIL/i, type: "verify-fail" },
  { pattern: /merge.*충돌|conflict/i, type: "merge-conflict" },
  { pattern: /에이전트.*실패/i, type: "agent-fail" },
  // ...
];

Hook이 실패를 감지하면 exit 2로 종료한다. 이때 stdout의 내용이 Claude에게 전달되어 대화가 계속된다. Claude는 사용자에게 확인 후 SKILL.md의 Gotchas 섹션에 항목을 추가한다.

Hook 공식 문서: Claude Code Hooks

체크리스트 — Skill 배포 전 확인

필수

• 파일명이 SKILL.md (대문자)인가
• name, description 프론트매터가 있는가
• description에 "무엇" + "언제" 둘 다 포함되어 있는가
• SKILL.md가 500줄 이하인가

권장

• argument-hint 추가
• Gotchas 섹션 존재 (실패 경험 축적 후)
• 400줄 이상이면 참조 파일로 분리
• git add -A 등 위험 명령에 안전장치 포함

선택

• disable-model-invocation: true (사용자 명시 호출만 허용하고 싶을 때)
• allowed-tools 제한 (Read-only 모드 등)
• Stop Hook으로 Gotchas 자동 수집

참고 자료

이 글에서 다룬 패턴은 실제 4개 프로젝트, 13개 Skills를 운영하면서 정리한 내용이다. Skill은 한 번 만들고 끝이 아니라, 실패를 먹고 자라는 문서다.