Claude Code Skills 2.0 공식 업데이트 정리 + 실전 튜토리얼

개요

이 문서는 Claude Code Skills 관련 공식 문서와 공식 릴리즈 노트를 바탕으로, 최근 Skills 기능이 어떻게 확장되었는지와 실제로 어떻게 설계하고 활용해야 하는지를 정리한 튜토리얼입니다.

---

1. 공식적으로 확인된 핵심 업데이트

1) Custom commands가 skills로 통합됨

공식 skills 문서에 따르면,

> Custom commands have been merged into skills.

결국 이제,

둘 다 /deploy처럼 동작할 수 있으며, Anthropic은 skills를 확장 표준 포맷으로 밀고 있습니다.

2) Skills frontmatter가 강화됨

관련 공식 문서 기준 주요 필드,

이제 skills는 단순 프롬프트 파일이 아니라, 호출 정책·실행 문맥·권한·훅을 가진 실행 단위입니다.

3) `context: fork`로 서브에이전트 실행 가능

공식 docs 기준,

설정을 통해 skill을 forked subagent에서 실행할 수 있습니다.

4) `hooks`를 skill frontmatter에 직접 붙일 수 있음

공식 docs frontmatter reference에 hooks가 포함되어 있고, 릴리즈 노트에도 skill hooks 관련 버그 수정이 등장합니다.

5) Hot reload 지원

공식 docs에 따르면 .claude/skills/ 및 --add-dir로 추가된 skills 디렉토리에 대해 live change detection이 지원됩니다.

6) Bundled skills 추가/강화

공식 docs에 정리된 기본 탑재 skills,

특히 /simplify와 /batch는 병렬 agent 실행과 worktree 활용까지 포함하는 고급 워크플로우형 skill입니다.

---

2. 공식 릴리즈 노트에서 보이는 Skills 관련 변화

공식 GitHub releases 기준 Skills 관련 포인트,

해석

이 변화들은 skills가 단순 텍스트 지시문이 아니라, 런타임 기능과 깊게 결합된 구조라는 걸 보여줍니다.

---

3. Skills 2.0의 본질

예전

지금

결국 Skills 2.0은 프롬프트 템플릿에서 작업 단위(work unit)로 진화한 것으로 보는 게 맞습니다.

---

4. 실전 튜토리얼

Step 1. 가장 기본 skill 만들기

디렉토리 생성

mkdir -p ~/.claude/skills/explain-code

`SKILL.md` 작성

---
name: explain-code
description: Explains code with diagrams and analogies when the user asks how code works.
---

When explaining code, always:

1. Start with a simple analogy
2. Draw an ASCII diagram
3. Walk through the code step by step
4. Mention one common mistake

사용

자동 호출,

How does this code work?

수동 호출:

/explain-code src/auth/login.ts

---

Step 2. 자동 호출 금지 skill 만들기

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(npm test), Bash(npm run build), Bash(deploy *)
---

Deploy $ARGUMENTS to production,

1. Run tests
2. Build the app
3. Deploy
4. Verify health checks

사용:

/deploy production

이 설정을 사용하면 Claude가 자동으로 deploy하지 않고, 사용자가 직접 /deploy를 호출해야만 실행됩니다.

---

Step 3. 유저에게는 숨기고 Claude만 쓰게 만들기

---
name: legacy-billing-context
description: Explains the legacy billing flow and known migration edge cases.
user-invocable: false
---

When working with billing code,

- The old ledger sync runs before invoice finalization
- Refund reconciliation is eventually consistent
- Never rename event types without checking downstream consumers

이건 slash menu에는 안 보이지만 Claude가 배경지식처럼 자동 활용할 수 있는 skill입니다.

---

Step 4. Arguments 제대로 쓰기

공식 docs 기준 지원:

예를 들어,

---
name: migrate-component
description: Migrate a component from one framework to another.
argument-hint: [component] [from] [to]
---

Migrate the $0 component from $1 to $2.

Requirements:
- Preserve behavior
- Preserve tests
- Keep accessibility intact

사용,

/migrate-component SearchBar React Vue

---

Step 5. Supporting files로 skill 분리하기

권장 구조:

my-skill/
├── SKILL.md
├── reference.md
├── examples.md
└── scripts/
    └── validate.sh

`SKILL.md`

---
name: write-api-spec
description: Write API specs following team conventions.
---

Use this workflow,

1. Read `reference.md` for schema rules
2. Read `examples.md` for output style
3. Draft the spec
4. Run `scripts/validate.sh` if needed

이 구조를 쓰면 SKILL.md는 가볍게 유지하고, 자세한 자료는 필요할 때만 로드하게 만들 수 있습니다.

---

Step 6. `${CLAUDE_SKILL_DIR}` 활용하기

공식 릴리즈에서 추가된 변수입니다.

예를 들어,

---
name: validate-pr
description: Validate PR content using bundled scripts.
allowed-tools: Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/*)
---

Run:

!python3 ${CLAUDE_SKILL_DIR}/scripts/check_pr.py

장점,

---

Step 7. Dynamic context injection 쓰기

공식 docs의 !command 패턴,

---
name: pr-summary
description: Summarize a pull request with live PR context
context: fork
allowed-tools: Bash(gh *)
---

PR diff,
!gh pr diff

PR comments,
!gh pr view --comments

Changed files,
!gh pr diff --name-only

Now summarize,
- What changed
- Risks
- Missing tests
- Release note candidate

이 방식은 명령 결과를 먼저 skill prompt에 주입한 뒤 Claude가 작업하도록 만듭니다.

---

Step 8. `context: fork`로 무거운 작업 분리하기

---
name: refactor-audit
description: Audit the codebase for refactor opportunities.
context: fork
agent: Explore
---

Audit this codebase for:

1. duplicated logic
2. over-coupled modules
3. dead abstractions
4. easy refactor wins

Return:
- top 5 issues
- severity
- suggested refactor order

이런 유형은 조사형/분석형/장시간 탐색 작업에 적합합니다.

---

Step 9. Hooks 붙이기

개념 예를 들어,

---
name: safe-edit
description: Edit files with validation hooks
hooks,
  PostToolUse,
    - command: "npm run lint"
---

When editing code,
- make minimal changes
- preserve tests
- explain the diff clearly

이제 skill은 작업 후 검증 흐름까지 포함하는 실행 단위가 됩니다.

---

5. Skills 2.0 설계 원칙

원칙 1. skill을 두 종류로 나눠라

#### A. 지식형 skill

#### B. 작업형 skill

원칙 2. `SKILL.md`는 짧게 유지해라

overview, when to use, workflow만 두고 상세 문서는 분리.

원칙 3. fork skill은 산출물을 명확히 요구하라

좋은 fork skill:

원칙 4. 위험한 작업은 자동 호출 막아라

예:

원칙 5. description 품질이 중요하다

description은 discoverability와 invocation 품질에 직접 영향을 줍니다.

---

6. 실전 예제 3개

예제 1: 안전한 배포 skill

---
name: deploy-staging
description: Deploy the app to staging after tests pass.
disable-model-invocation: true
allowed-tools: Bash(npm test), Bash(npm run build), Bash(deploy staging)
---

Deploy to staging:

1. Run tests
2. Build
3. Deploy staging
4. Verify logs and health endpoint
5. Report result

예제 2: 코드베이스 조사 skill

---
name: find-tech-debt
description: Find high-impact tech debt in the current repo.
context: fork
agent: Explore
---

Audit the repo for,
- duplicated logic
- giant files
- dead code
- outdated abstractions

Return top 10 items with,
- file path
- why it matters
- estimated cleanup difficulty

예제 3: PR 요약 skill

---
name: pr-summary
description: Summarize the current pull request for review or release notes.
context: fork
allowed-tools: Bash(gh *)
---

PR diff:
!gh pr diff

Comments:
!gh pr view --comments

Now produce:
1. summary
2. risks
3. release note
4. reviewer checklist

---

7. 결론

Claude Code Skills 2.0에서 중요한 건 문법 몇 개가 아니라, 스킬을 설계하는 관점이 바뀌었다는 점입니다.

이제 질문은 이렇게 바뀝니다,

결국 skill은 이제 단순 프롬프트 파일이 아니라,

를 함께 가진 구조라고 보는 게 맞습니다.

---

8. 출처