12. Skills(에이전트 스킬)

Skill이란

Skill은 디스크 위의 한 디렉터리입니다. 그 안에 SKILL.md 파일 하나가 필수로 있고, Claude가 따를 지침이 담깁니다. 헬퍼 스크립트·참고 문서·템플릿을 함께 둘 수도 있습니다.

핵심은 호출 방식입니다. 당신이 무언가를 시키면, Claude가 스킬의 이름과 설명을 보고 "이 스킬을 불러올지" 스스로 판단합니다(자동 호출). /스킬이름으로 직접 부를 수도 있습니다. 데몬도, 포트도, 인증 흐름도 없습니다 — 그냥 파일입니다.

비유하자면, Skill은 특정 작업을 위한 "전문 매뉴얼" 입니다. 평소엔 책장에 꽂혀 있다가(이름표만 보임), 필요할 때 펼쳐 읽습니다.

SKILL.md 구조

스킬은 두 부분으로 이뤄집니다: YAML frontmatter(언제 쓸지)와 마크다운 본문(어떻게 할지). 디렉터리 이름이 곧 명령어가 됩니다.

~/.claude/skills/summarize-changes/SKILL.md:

---
description: 커밋되지 않은 변경을 요약하고 위험 요소를 표시.
  변경 내용을 묻거나, 커밋 메시지를 원하거나, diff 리뷰를 요청할 때 사용.
---
## 현재 변경
!`git diff HEAD`

## 지침
위 변경을 2~3개 불릿으로 요약한 뒤, 누락된 에러 처리·하드코딩 값·
갱신이 필요한 테스트 같은 위험을 나열해줘. diff가 비어 있으면
커밋되지 않은 변경이 없다고 말해줘.

핵심 frontmatter 필드

점진적 공개: 왜 수십 개 깔아도 괜찮나

Skill의 영리한 설계가 점진적 공개(progressive disclosure) 입니다. 로딩이 세 단계로 나뉩니다.

flowchart TB
    A[세션 시작<br/>모든 스킬의 이름+설명만 로드<br/>스킬당 ~30-50 토큰]:::know --> B{Claude가 작업과<br/>관련 판단}:::agent
    B -->|관련| C[SKILL.md 본문 로드<br/>최대 ~5,000 토큰]:::tool
    C --> D[헬퍼 파일은 필요 시 추가 로드]:::tool
    B -->|무관| E[본문 로드 안 함<br/>예산 거의 안 씀]:::result

    classDef know fill:#CE93D8,stroke:#8E24AA,color:#000
    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000

📌 스킬 50개를 깔아도 세션 시작 오버헤드는 약 2,500토큰으로 미미합니다. 본문은 호출될 때만 로드되니까요. (참고로 MCP는 정반대 — 14장에서 비교합니다.)

⚠️ 단, 한 번 로드된 스킬 본문은 그 세션 내내 컨텍스트에 남습니다. 그래서 본문은 CLAUDE.md처럼 간결해야 합니다. 본문은 500줄 이하로 유지하고, 상세 참고자료는 헬퍼 파일로 빼세요. "왜·어떻게"를 서술하기보다 "무엇을 하라"를 명령형으로.

자동 vs 수동 호출 제어

flowchart LR
    A[기본<br/>자동 호출 가능]:::agent
    B["disable-model-invocation: true<br/>/이름 으로만 수동"]:::tool
    C["권한: Skill 도구 deny<br/>전부 비활성"]:::danger

    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef danger fill:#EF9A9A,stroke:#E53935,color:#000

• 기본적으로 Claude는 disable-model-invocation: true가 없는 스킬을 자동 호출할 수 있습니다.
• 배포처럼 위험한 작업은 disable-model-invocation: true로 수동 전용(/deploy)으로 두는 게 안전합니다.
• 권한으로도 제어합니다: /permissions에서 Skill 도구를 deny하면 전부 끄고, Skill(commit)·Skill(review-pr *)로 특정 스킬만 허용, Skill(deploy *)로 특정 스킬만 차단할 수 있습니다(→ 8장).

context: fork — 스킬을 서브에이전트에서 격리 실행

context: fork를 frontmatter에 넣으면 스킬이 격리된 서브에이전트에서 돌고, 메인 대화에는 요약만 돌아옵니다. 스킬 본문이 곧 그 서브에이전트를 움직이는 프롬프트가 됩니다.

---
name: deploy
description: 애플리케이션을 프로덕션에 배포
context: fork
disable-model-invocation: true
---
애플리케이션 배포:
1. 테스트 스위트 실행
2. 빌드
3. 배포 대상에 푸시

⚠️ context: fork는 명시적 지시(task)가 있는 스킬에만 의미가 있습니다. "이 API 컨벤션을 써" 같은 가이드라인만 있고 할 일이 없으면, 서브에이전트가 지침만 받고 할 일이 없어 빈손으로 돌아옵니다. fork된 스킬은 대화 기록에 접근하지 못한다는 점도 기억하세요.

라이브 변경 감지

Claude Code는 스킬 디렉터리의 파일 변경을 감시합니다. ~/.claude/skills/·프로젝트 .claude/skills/ 안의 SKILL.md를 추가·편집·삭제하면 재시작 없이 현재 세션에 반영됩니다. 단:

• 세션 시작 시 없던 최상위 skills 디렉터리를 새로 만들면 재시작해야 감시 대상이 됩니다.
• 라이브 감지는 SKILL.md 텍스트만 해당합니다. 스킬 폴더가 플러그인이기도 하면, hooks/·.mcp.json·agents/ 변경은 /reload-plugins가 필요합니다.

이 장에서 배운 것

• Skill은 SKILL.md를 가진 디렉터리로, 이름·설명을 보고 Claude가 자동 호출하거나 /이름으로 수동 호출한다.
• 슬래시 명령은 Skills로 통합됐고, 둘 다 있으면 스킬이 우선한다.
• 점진적 공개 덕에 세션 시작엔 이름+설명만(스킬당 ~30-50토큰) 로드되어 수십 개를 깔아도 가볍다. 본문은 호출 시 로드되며 그 뒤 세션 내내 남으므로 500줄 이하로.
• description은 구체적으로(무엇+언제), disable-model-invocation·권한·allowed-tools로 호출과 도구를 제어한다.
• context: fork로 스킬을 서브에이전트에서 격리 실행하되, 명시적 task가 있어야 한다.

✍️ 확인 문제

1. 점진적 공개란 무엇이며, 왜 스킬을 수십 개 설치해도 컨텍스트 부담이 적은가요?
2. description 필드가 "가장 중요"하다고 하는 이유는 무엇인가요?
3. 배포 같은 위험 작업 스킬을 Claude가 멋대로 자동 실행하지 못하게 하려면 어떤 frontmatter를 쓰나요?

다음 장: 13. Subagents(서브에이전트) — 컨텍스트를 격리하는 독립 일꾼들.