Claude Code Skills 개념과 기본 사용

들어가며

21~23차시에서는 Claude Code의 메모리/규칙 시스템을 다뤘다. CLAUDE.md는 매 세션에 무조건 로드되는 사실, path-scoped rules는 매칭 파일을 만질 때 활성화되는 영역별 규칙, Auto memory는 Claude가 스스로 적어두는 학습 노트였다.

세 가지 모두 공통점이 있다. 자동으로 컨텍스트에 들어간다. 사용자가 호출하지 않아도, Claude가 판단하지 않아도, 조건만 맞으면 펼쳐진다.

Skills는 이와 다르다. on-demand로 로드되는 워크플로/지식 패키지다. 사용자가 /<skill-name>으로 직접 호출하거나, Claude가 작업과 관련 있다고 판단했을 때만 본문이 컨텍스트에 들어온다. 매 세션 컨텍스트를 늘리지 않으면서 재사용 가능한 절차를 패키징하는 방법이다.

이번 차시는 Skills의 개념과 기본 사용을 다룬다.

• Skills란 무엇인가 — CLAUDE.md/rules와 어떻게 다른가
• SKILL.md 구조 — 디렉토리, frontmatter, 본문
• 호출 방식 — 직접 호출 vs Claude 자동 호출
• 위치 4계층 — Enterprise / Personal / Project / Plugin
• 번들 스킬 — Claude Code가 기본 제공하는 것들
• 호출 주체 제어 — disable-model-invocation, user-invocable
• 인수, 도구 승인, 동적 컨텍스트, 서브에이전트 실행 — 자주 쓰는 패턴들

25차시에서 직접 스킬을 작성하기 전에, 이번 차시에서 개념과 기본 사용을 정리한다.

Skills란 무엇인가

Skill은 디렉토리다. 그 안에 SKILL.md가 들어 있고, YAML frontmatter와 마크다운 본문으로 Claude에게 “이런 작업을 어떻게 처리해라”고 알려준다.

.claude/skills/
└── explain-code/
    └── SKILL.md

이 한 가지만 만들어두면 두 가지 호출 경로가 동시에 열린다.

1. 사용자가 직접: /explain-code 슬래시 명령
2. Claude가 자동: 사용자의 질문이 description에 매치되면 Claude가 알아서 본문을 컨텍스트에 끌어옴

만드는 이유는 단순하다. 같은 절차를 채팅에 반복해서 붙여넣고 있다면 — 또는 CLAUDE.md의 한 섹션이 사실(fact)을 넘어 절차(procedure)로 자라났다면 — Skill로 옮겨라. CLAUDE.md와 달리 본문은 호출됐을 때만 로드되므로, 긴 참고 자료도 평소엔 컨텍스트 비용이 거의 없다.

공식 문서가 명시하는 핵심 차이: “Unlike CLAUDE.md content, a skill’s body loads only when it’s used, so long reference material costs almost nothing until you need it.”

Skills vs CLAUDE.md vs path-scoped rules

핵심은 사실이 아니라 절차라면 Skill이라는 점이다. CLAUDE.md의 “보안 규칙”이 “릴리스 절차” 비슷한 단계로 자라났다면 Skill로 분리할 후보다.

Progressive Disclosure: 3단계 로드

Skills는 Agent Skills 오픈 표준을 따른다. 이 표준은 컨텍스트를 아끼는 핵심 메커니즘으로 progressive disclosure(점진적 노출)를 정의한다.

1. Discovery (세션 시작): 모든 스킬의 name과 description만 로드. Claude는 “어떤 스킬이 있고 언제 쓰면 되는지”를 안다. 본문은 모름.
2. Activation (호출 시): 호출되는 순간 SKILL.md 본문이 한 번의 메시지로 컨텍스트에 들어감.
3. Execution: Claude가 본문 지시를 따른다. 필요하면 supporting files를 읽거나 번들된 스크립트를 실행한다.

이 구조 덕분에 스킬을 수십 개 만들어두어도 평소 컨텍스트 비용은 description 합계뿐이다. 절차의 무게는 호출 순간에만 나간다.

Skill을 호출하면 본문이 메시지로 들어가서 세션 끝까지 컨텍스트에 남는다. Claude Code는 이후에 같은 파일을 다시 읽지 않는다. 그래서 본문은 “한 번만 실행되는 단계”가 아니라 “이 작업 동안 지킬 standing instructions”로 쓰는 게 맞다.

SKILL.md 구조

스킬 디렉토리에는 SKILL.md가 필수, 나머지는 선택이다.

my-skill/
├── SKILL.md           # 필수 — 진입점
├── reference.md       # 선택 — 디테일 레퍼런스
├── examples/
│   └── sample.md
└── scripts/
    └── helper.sh

SKILL.md는 두 부분이다.

• YAML frontmatter (---로 둘러싸인 부분) — Claude에게 언제 쓰는 스킬인지 알려준다
• 마크다운 본문 — 호출됐을 때 Claude가 따를 지시

최소 예시

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

description 한 줄이 핵심이다. Claude가 자동 호출을 결정할 때 이걸 본다. 사용자가 자연스럽게 쓸 단어들(“how does this work”, “explain code”)이 들어가야 매칭이 잘 된다.

공식 권장: SKILL.md는 500줄 이하. 디테일 레퍼런스는 supporting files로 빼고 SKILL.md에서 명시적으로 가리킨다 — “For complete API details, see reference.md”.

Frontmatter 필드

전체 필드는 다음과 같다. 모두 선택이지만 description은 권장이다.

description을 다시 강조한다. front-load the key use case — 핵심 사용 사례를 앞에 둔다. description과 when_to_use 합쳐서 1,536자에서 잘리기 때문이다. 또한 사용자에게 스킬이 많아지면 /skills 목록이 컨텍스트 1% 또는 8,000자 fallback로 잘려서, 키워드를 못 찾으면 Claude가 매칭에 실패한다.

어디에 두는가: 4계층

스킬을 어디에 두느냐가 누가 쓸 수 있는지를 결정한다.

같은 이름이 충돌하면 우선순위는 enterprise > personal > project다. Plugin 스킬은 plugin-name:skill-name 네임스페이스라 다른 계층과 충돌하지 않는다.

Live change detection

세션 중에 스킬 파일을 추가/수정/삭제하면 즉시 반영된다. 별도 재시작 없이 바로 쓸 수 있다. 단, 디렉토리(~/.claude/skills/, .claude/skills/) 자체는 세션 시작 시 등록되어야 한다 — 디렉토리를 새로 만들었다면 Claude Code를 한 번 재시작한다.

--add-dir에서도 로드됨

--add-dir 플래그는 보통 파일 접근만 추가하지 working directory 외부의 .claude/ 설정은 안 가져온다. 하지만 스킬은 예외다. --add-dir된 디렉토리의 .claude/skills/도 자동 로드된다. 모노레포에서 패키지마다 별도 스킬을 두는 패턴에 적합하다.

모노레포 nested discovery

서브디렉토리에 들어가면 packages/frontend/.claude/skills/ 같은 nested 위치도 자동 발견된다. 모노레포 루트에 공통 스킬, 패키지마다 패키지 전용 스킬을 두는 구조가 가능하다.

.claude/commands/도 여전히 동작

중요한 변경: 예전의 custom commands가 skills로 통합됐다. .claude/commands/deploy.md(파일)와 .claude/skills/deploy/SKILL.md(디렉토리) 둘 다 /deploy를 만들고 동일하게 동작한다. 기존 .claude/commands/는 계속 쓸 수 있지만, 새로 만들 거면 .claude/skills/가 권장이다 — supporting files, 추가 frontmatter 옵션, Claude 자동 호출 같은 기능이 더 있다.

호출 방식 두 가지

스킬은 두 가지로 호출된다.

1. 사용자가 직접 (/<skill-name>)

> /explain-code src/auth/login.ts

확정적인 호출이다. 사용자가 의도한 워크플로를 그대로 트리거한다.

2. Claude가 자동 (description 매칭)

> 이 코드 어떻게 동작하는지 설명해줘

Claude가 description을 보고 매칭되는 스킬을 자동으로 로드한다. 사용자는 슬래시 명령을 외울 필요 없다. 자연스러운 요청이 적절한 스킬로 라우팅된다.

이 두 경로가 동시에 열려 있다는 게 핵심이다. 같은 스킬을 한쪽에서 명시적으로 부르거나, 다른 쪽에서 자동으로 발화시키거나 — 둘 다 가능하다.

추가 지시와 함께

> /review-pr 보안 취약점에 집중해서

스킬 본문을 따르되 사용자가 덧붙인 추가 지시도 같이 전달된다.

호출 주체 제어

기본은 양쪽 다 가능이다. 하지만 워크플로에 따라 한쪽으로 제한해야 할 때가 있다.

A. 사용자만 호출 (Claude 자동 발화 차단)

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

disable-model-invocation: true를 달면 Claude는 이 스킬을 자동 호출하지 못한다. 사용자가 /deploy로만 트리거할 수 있다.

언제 쓰나: 사이드 이펙트가 있고 타이밍이 중요한 워크플로 — 배포, 커밋, Slack 메시지 발송. Claude가 “코드가 좋아 보여” 하고 멋대로 deploy를 트리거하는 걸 막는다.

B. Claude만 호출 (사용자에게 안 보임)

---
name: legacy-system-context
description: Background context about the legacy auth system
user-invocable: false
---

user-invocable: false를 달면 /메뉴에서 안 보인다. Claude만 자동 호출할 수 있다.

언제 쓰나: 액션이 아니라 배경 지식이다. 사용자가 /legacy-system-context를 누를 의미가 없다 — 그냥 Claude가 관련 작업할 때 알아두면 좋은 컨텍스트.

정리

인수 전달

스킬에 인수를 전달하려면 본문에 $ARGUMENTS를 쓴다.

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

> /fix-issue 123

→ Claude가 받는 메시지: “Fix GitHub issue 123 following our coding standards…”

스킬에 $ARGUMENTS가 없는데도 사용자가 인수를 같이 보냈다면, Claude Code가 본문 끝에 ARGUMENTS: <input>을 붙여준다. 그래서 사용자 입력이 사라지지는 않는다.

위치별 인수

복수 인수를 위치별로 받고 싶으면 $ARGUMENTS[N] 또는 짧게 $N을 쓴다.

---
name: migrate-component
description: Migrate a component from one framework to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

> /migrate-component SearchBar React Vue

→ $0=SearchBar, $1=React, $2=Vue로 치환된다.

다중 단어를 한 인수로 묶으려면 따옴표로 감싼다 — /my-skill "hello world" second이면 $0="hello world", $1="second".

기타 치환 변수

도구 사전 승인 (allowed-tools)

스킬이 Bash로 git 명령을 줄줄이 실행해야 하는데 매번 승인 다이얼로그가 뜨면 워크플로가 깨진다. allowed-tools로 스킬이 활성인 동안 자동 승인되는 도구를 지정한다.

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

allowed-tools는 이 스킬이 켜져 있는 동안만 그 도구를 자동 승인한다. 다른 도구는 일반 permission 설정을 따른다. 어떤 도구를 차단하고 싶다면 settings의 deny 규칙에 추가하면 된다.

동적 컨텍스트 주입 (! 문법)

SKILL.md가 Claude에게 가기 전에 셸 명령을 실행해서 출력을 본문에 끼워넣을 수 있다. !`<command>` 형태다.

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

이 스킬을 호출하면 다음이 일어난다.

1. 각 !`<command>`가 즉시 실행된다 (Claude가 보기 전에)
2. 출력이 자리에 들어간다
3. Claude는 명령어가 아니라 결과만 본다 — 이미 채워진 프롬프트

다중 라인 명령이 필요하면 ```!로 시작하는 코드펜스를 쓴다.

## Environment
```!
node --version
npm --version
git status --short
```

조직에서 이 동작을 차단해야 한다면 settings에 "disableSkillShellExecution": true를 둔다. 사용자/프로젝트/플러그인/추가 디렉토리 스킬에 적용되고, 매니지드/번들 스킬은 영향받지 않는다.

서브에이전트에서 실행 (context: fork)

스킬이 컨텍스트를 폭발시키는 작업 — 코드베이스 탐색, 대량 파일 읽기 — 을 한다면 메인 대화에 그 노이즈를 끌고 들어오지 않는 게 낫다. context: fork를 달면 스킬이 서브에이전트의 격리 컨텍스트에서 실행된다.

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

이 스킬은 다음 흐름이다.

1. 격리된 새 컨텍스트가 만들어진다
2. 서브에이전트가 SKILL.md 본문을 prompt로 받는다 (“Research X thoroughly…”)
3. agent: Explore — Explore 서브에이전트 설정 (모델, 도구, 권한)으로 실행된다
4. 결과가 요약되어 메인 대화에 돌아온다

agent 옵션엔 빌트인(Explore, Plan, general-purpose) 또는 .claude/agents/에 정의한 커스텀 서브에이전트를 쓴다. 생략하면 general-purpose다.

context: fork는 본문이 명시적인 작업 지시일 때만 의미가 있다. “use these conventions” 같은 가이드라인만 있고 작업이 없으면 서브에이전트는 가이드라인만 받고 할 일이 없다. 가이드라인을 reference로만 두려면 fork하지 말고 일반 스킬로 둔다.

번들 스킬 (Bundled Skills)

Claude Code에는 매 세션 같이 따라오는 번들 스킬이 있다. 사용자가 작성한 스킬과 같은 메커니즘이다 — Claude에게 prompt를 넘기는 방식이라, 사용자가 /<name>으로 부르거나 Claude가 알아서 호출할 수 있다.

번들 스킬은 commands 레퍼런스에서 Skill 표시로 구분된다.

번들 스킬 vs Built-in Command

자주 헷갈리는 부분이다.

• 번들 스킬 (/simplify, /batch 등): prompt 기반. Claude가 도구를 써서 진행한다. 자동 호출 가능.
• Built-in 명령어 (/clear, /compact, /permissions, /commit, /review, /init 등): CLI에 하드코딩된 동작. Claude가 아니라 CLI가 직접 실행한다.

겉모습은 똑같이 /로 시작하지만 동작 방식이 다르다. 사용자 입장에서는 굳이 구분 안 해도 되지만, 자기 스킬을 만들 때 “내가 만들 수 있는 건 prompt 기반 스킬”이라는 점만 알면 된다.

스킬 목록 보기: /skills

세션에서 어떤 스킬이 활성인지 보려면 /skills다.

> /skills

스킬 이름, 설명, 토큰 카운트가 나온다. t 키를 누르면 토큰 순으로 정렬된다.

예전에 /help가 스킬 목록을 보여줬다는 자료가 돌지만, 지금은 /help는 도움말이고 스킬 목록은 /skills다.

Compaction 동작

Skills의 본문은 한 번 호출되면 세션 끝까지 컨텍스트에 남는다. 하지만 컨텍스트가 가득 차서 auto-compaction이 일어나면 어떻게 될까?

공식 동작은 다음과 같다.

• 호출됐던 스킬들이 compaction 후 재첨부된다 — 각 스킬 본문 5,000 토큰까지
• 재첨부 전체에 25,000 토큰 budget
• 가장 최근에 호출된 스킬부터 채워진다 → budget 넘치면 오래된 스킬은 통째로 빠진다

이게 의미하는 바는 — 스킬 호출 후 동작이 흐릿해진 것 같으면, 두 가능성이 있다.

1. 본문은 살아 있지만 모델이 다른 도구/접근을 선택 중이다 → description과 본문을 강화한다
2. 큰 스킬이 budget 밖으로 밀려났다 → 한 번 더 호출해서 재주입한다

트러블슈팅

스킬이 자동 호출 안 됨

체크리스트.

• description에 사용자가 자연스럽게 쓸 keyword가 들어 있나
• /skills로 스킬이 보이나
• description+when_to_use가 1,536자 안에서 핵심 use case를 앞쪽에 두고 있나
• disable-model-invocation: true로 막혀 있지는 않나

스킬이 너무 자주 호출됨

• description을 더 좁혀라 — 어떤 상황에서만 쓰는지 명시
• 의도한 게 수동만이라면 disable-model-invocation: true

Description이 잘림

스킬이 많아지면 description budget 안에 다 못 들어가서 keyword가 잘릴 수 있다. budget은 동적으로 컨텍스트 1% 또는 8,000자 fallback이다. 늘리려면 환경 변수 SLASH_COMMAND_TOOL_CHAR_BUDGET을 설정한다. 또는 description/when_to_use를 짧게 쓰고 핵심을 앞에 둔다.

스킬 본문이 첫 응답 후 사라지는 것 같음

본문은 세션에 남아 있다 — 다른 도구를 모델이 선택했을 가능성이 크다. description과 본문을 더 단호하게 쓰거나, hooks로 결정적으로 강제한다. 큰 스킬은 compaction 후 dropped됐을 수 있으니 한 번 더 호출.

다른 도구는 어떻게 차단?

Claude의 스킬 호출을 제한하려면 permission 규칙을 쓴다.

# /permissions에서
Skill                  # Skill 도구 자체 차단 (모든 자동 호출 막음)
Skill(commit)          # 정확 매치 허용
Skill(review-pr *)     # prefix 매치 + 인수 허용
Skill(deploy *)        # deploy 차단 (deny 리스트에)

Agent Skills 오픈 표준

Claude Code의 Skills는 Agent Skills 표준을 따른다. Anthropic이 만들어 오픈한 표준이고, Cursor, OpenAI Codex, Goose, GitHub Copilot, Gemini CLI 등 여러 코딩 에이전트가 같은 SKILL.md 포맷을 채택한다.

실용적으로 무슨 의미인가? 한 번 작성한 스킬을 여러 도구에서 재사용할 수 있다. Claude Code 전용 기능(disable-model-invocation, context: fork 같은)은 도구별 확장이지만, 핵심 구조 — frontmatter name/description + 본문 + supporting files — 는 표준이다.

Plugins로 배포

스킬을 여러 프로젝트, 또는 외부에 배포할 거면 Plugin으로 패키징한다. Plugin은 스킬, 서브에이전트, 훅, MCP 서버를 묶어서 하나의 단위로 배포하는 메커니즘이다.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── code-review/
        └── SKILL.md

Plugin의 스킬은 /plugin-name:skill-name 네임스페이스로 호출된다 — 충돌 방지를 위해서다. 25차시 이후에 직접 작성을 다루면서 다시 본다.

정리

핵심 요점

1. Skills는 디렉토리 — <name>/SKILL.md. 안에 frontmatter + 본문. supporting files 옵션
2. on-demand 로드 — CLAUDE.md/rules와 달리 호출됐을 때만 본문이 컨텍스트에 들어감
3. Progressive disclosure 3단계 — Discovery(name+description만) → Activation(본문 로드) → Execution
4. 호출 두 경로 — 사용자가 /<name>, 또는 Claude가 description 매칭으로 자동
5. 위치 4계층 — Enterprise > Personal(~/.claude/skills/) > Project(.claude/skills/) + Plugin (네임스페이스)
6. 호출 주체 제어 — disable-model-invocation: true(수동만), user-invocable: false(Claude만)
7. 인수 — $ARGUMENTS, $ARGUMENTS[N], $N. 따옴표로 묶어 다중 단어 한 인수로
8. 도구 사전 승인 — allowed-tools: Bash(git add *) ...로 스킬 동안 자동 승인
9. 동적 컨텍스트 주입 — !`<command>`로 SKILL.md가 Claude에게 가기 전에 셸 명령 실행
10. 서브에이전트 실행 — context: fork + agent: Explore로 격리 컨텍스트
11. 번들 스킬 — /simplify, /batch, /debug, /loop, /claude-api, /fewer-permission-prompts
12. Built-in command와 다름 — 번들 스킬은 prompt 기반, built-in은 CLI 하드코딩
13. /skills로 목록 — 토큰 카운트 포함, t로 정렬
14. Compaction — 각 스킬 5,000토큰 / 전체 25,000토큰 budget로 재첨부
15. Description 1,536자 캡 — front-load the key use case
16. Agent Skills 오픈 표준 — Cursor, Codex, Goose 등도 같은 포맷 호환

확인해볼 링크

• 공식 문서: Extend Claude with skills
• 공식 문서: Commands reference
• 공식 문서: Subagents
• 공식 문서: Permissions (Skill 권한 규칙)
• 공식 문서: Plugins
• Agent Skills 오픈 표준

다음 단계

이번 차시는 “이미 있는 스킬을 어떻게 호출하는가, 어떻게 동작하는가”였다. 25차시에서는 직접 스킬을 작성하는 법을 다룬다 — 디렉토리 구조 잡기, frontmatter 옵션 고르기, 본문 쓰기, supporting files 활용, 그리고 재사용 가능한 스킬 패턴까지. 26차시에서는 PR 리뷰, 테스트 생성, 문서화 같은 실전 스킬 예제를, 27차시에서는 context: fork를 쓴 서브에이전트 스킬을 본격적으로 다룬다.

참고 자료

• Extend Claude with skills
• Commands reference
• Subagents
• Permissions
• Plugins
• Agent Skills standard