Claude Code Skills 시스템 2026 — Custom Commands 합병과 context fork 패턴
Anthropic 공식 Claude Code Skills 시스템(2026 시점)을 'Extend Claude with skills' 공식 문서 기준으로 정리한다. Custom Commands → Skills 합병, frontmatter 필드 카탈로그, context fork 모드, `!` 백틱 동적 컨텍스트 주입, skill content lifecycle, allowed-tools / skillOverrides 거버넌스를 다룬다.
이 글의 범위
이 글은 Anthropic 공식 vanilla Claude Code의 Skills 시스템만 다룬다.1 oh-my-claudecode(OMC)가 그 위에 얹는 트리거 키워드 매핑·Tier-0 워크플로우·팀 오케스트레이션은 이 글의 범위 밖이다. OMC 레이어 작성법은 아래 글에서 별도로 다뤘다:
- Claude Code 스킬 작성 완전 가이드 — OMC 기반 워크플로우와 자동화 설계
- Claude Code 스킬 작성 팁 — OMC 스킬 실전 패턴
본 글은 공식 “Extend Claude with skills” 문서1를 1차 자료로 따른다.
1. Custom Commands → Skills 합병
공식 문서가 명시한다:1
“Custom commands have been merged into skills. A file at
.claude/commands/deploy.mdand a skill at.claude/skills/deploy/SKILL.mdboth create/deployand work the same way. Your existing.claude/commands/files keep working.”
핵심 사실 3가지:
- 양쪽 경로 모두 작동 —
.claude/commands/<name>.md와.claude/skills/<name>/SKILL.md가 같은/<name>슬래시 커맨드를 만든다. - 이름 충돌 시 Skill이 우선 — 같은 이름이 두 곳에 있으면 Skills가 이긴다.
- Skills의 추가 기능: (a) 지원 파일 디렉토리(템플릿·스크립트), (b) 확장 frontmatter, (c) Claude가 자동으로 관련 상황에 로드하는 기능.
기존 .claude/commands/ 파일은 그대로 동작한다. Skills로 옮기는 것은 더 많은 기능이 필요할 때만 의미가 있다.
2. Skill의 두 갈래 — Reference vs Task content
공식 문서는 SKILL.md 본문 내용을 어떤 의도로 쓰는지에 따라 두 갈래로 정리한다.1
Reference content
“Reference content adds knowledge Claude applies to your current work. Conventions, patterns, style guides, domain knowledge. This content runs inline so Claude can use it alongside your conversation context.”
대화 컨텍스트와 함께 inline으로 작동한다. 사용자가 직접 호출하기보다 Claude가 상황에 맞게 자동 로드하는 것을 의도한다.
Task content
“Task content gives Claude step-by-step instructions for a specific action, like deployments, commits, or code generation.”
직접 /skill-name으로 호출하는 것을 의도한다. Side effect가 있는 경우 disable-model-invocation: true로 자동 호출을 막는다.
두 갈래는 frontmatter 필드가 아니라 의도다 — 공식 문서엔
type: reference같은 필드가 존재하지 않는다. Reference/Task는 SKILL.md 콘텐츠를 작성하는 작성자의 선택이다.
3. Frontmatter — 공식 필드 카탈로그
공식 문서가 정의하는 SKILL.md frontmatter 필드 전체:1
| 필드 | 필수 | 설명 |
|---|---|---|
name | × | 표시 이름. 생략 시 디렉토리 이름. 소문자·숫자·하이픈, 최대 64자 |
description | 권장 | Claude가 이 스킬을 언제 쓸지 판단하는 텍스트. when_to_use와 합쳐 1,536자 캡 |
when_to_use | × | 추가 트리거 컨텍스트(예시 발화 등). 1,536자 캡에 포함 |
argument-hint | × | 자동완성 시 보이는 인자 형식 힌트(예: [issue-number]) |
arguments | × | 명명 인자. 위치 매핑 |
disable-model-invocation | × | true 면 Claude의 자동 호출 차단 (사용자 직접 호출만) |
user-invocable | × | false 면 / 메뉴에서 숨김 (Claude만 호출) |
allowed-tools | × | 이 스킬 활성 중에 무승인 허용할 도구 목록 |
model | × | 활성 중 모델 오버라이드 (/model 값) |
effort | × | 활성 중 effort 레벨 (low/medium/high/xhigh/max) |
context | × | fork 설정 시 forked subagent context에서 실행 |
agent | × | context: fork 일 때 어떤 subagent 타입 사용 |
hooks | × | 이 스킬 lifecycle에 한정된 훅 |
paths | × | glob 패턴 — 해당 파일을 다룰 때만 자동 로드 |
shell | × | bash (기본) 또는 powershell |
type,max-tokens,temperature,system,tags,version필드는 공식 frontmatter에 존재하지 않는다. 인터넷에서 그런 예시를 봤다면 비공식 확장이거나 환각이므로 공식 문서를 기준으로 한다.
description 1,536자 캡의 의미
공식 문서는 임베딩 검색이 아니라 “skill listing 컨텍스트 토큰 예산” 으로 캡을 적용한다:1
“the combined
descriptionandwhen_to_usetext is truncated at 1,536 characters in the skill listing to reduce context usage”
스킬 description은 컨텍스트에 항상 적재되므로 짧게 유지하는 것이 권장된다. 설정으로 캡과 예산을 조정할 수 있다:
maxSkillDescriptionChars— 1,536 캡 자체를 변경skillListingBudgetFraction— 모델 context의 몇 %를 skill listing에 쓸지 (기본 1%)SLASH_COMMAND_TOOL_CHAR_BUDGET— 고정 캐릭터 수
“1% trigger 신뢰도 임계값” 같은 표현은 공식 문서에 없다 — 공식 문서가 다루는 1%는 컨텍스트 예산 비율이다.
4. context: fork — Skills를 서브에이전트로 분기
공식 문서가 정의하는 단 하나의 context 값은 fork 다.1 inject/isolated 같은 값은 공식 명세에 존재하지 않는다.
“Add
context: forkto your frontmatter when you want a skill to run in isolation. The skill content becomes the prompt that drives the subagent. It won’t have access to your conversation history.”
동작
| 항목 | context: fork 사용 시 |
|---|---|
| 시스템 프롬프트 | agent 필드로 지정한 subagent 타입의 시스템 프롬프트 |
| 태스크 프롬프트 | SKILL.md 본문 |
| 대화 히스토리 접근 | 없음 (격리) |
| 추가 로드 | CLAUDE.md (단 Explore/Plan agent는 예외 — 둘은 CLAUDE.md·git status 스킵) |
예시 — 코드베이스 리서치 스킬
1
2
3
4
5
6
7
8
9
10
11
12
---
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
/deep-research <topic> 으로 호출하면 Explore 에이전트가 forked 컨텍스트에서 실행되며, 부모 대화의 토큰을 잠식하지 않는다. 본 블로그 서브에이전트 패턴 글의 격리 분기와 같은 원리다.
context: fork vs 서브에이전트 호출
공식 문서가 두 방향을 표로 정리:1
| 접근 | 시스템 프롬프트 | 태스크 |
|---|---|---|
context: fork 스킬 | agent 타입에서 가져옴 | SKILL.md 본문 |
서브에이전트 + skills 필드 | 서브에이전트 본문 | Claude의 위임 메시지 |
전자는 스킬이 태스크를 들고 가서 에이전트에 위임하는 모델, 후자는 에이전트가 스킬을 참조 자료로 끌어다 쓰는 모델이다.
5. Dynamic Context Injection — !`<command>` 백틱 문법
공식 문서가 정의하는 동적 컨텍스트 주입 문법은 백틱 + ! 접두사 다.1 `` 템플릿 변수는 공식 명세에 없다.
“The
!`<command>`syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself.”
단일 라인 — 인라인
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
---
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...
각 !`<command>` 는 Claude가 콘텐츠를 받기 전에 실행되고, 출력으로 자리바꿈된다. 한 번만 치환되며 재귀 확장은 없다.
여러 라인 — fenced 코드 블록
1
2
3
4
5
6
## Environment
```!
node --version
npm --version
git status --short
```
보안 가드
공식 문서가 명시한 보안 설정: disableSkillShellExecution: true 를 settings에 두면 위 셸 주입이 “[shell command execution disabled by policy]” 로 대체된다. 본 블로그 Prompt Injection 글의 셸 호출 신뢰 경계를 정책 레벨에서 강제할 수 있다.
6. 문자열 치환 — $ARGUMENTS / ${CLAUDE_*}
공식 문서가 정의하는 치환 변수:1
| 변수 | 의미 |
|---|---|
$ARGUMENTS | 호출 시 전달된 전체 인자 문자열 |
$ARGUMENTS[N] | 0-based 인덱스로 N번째 인자 |
$N | $ARGUMENTS[N] 축약형 |
$<name> | arguments frontmatter 리스트로 정의한 명명 인자 |
${CLAUDE_SESSION_ID} | 현재 세션 ID |
${CLAUDE_EFFORT} | 현재 effort 레벨 |
${CLAUDE_SKILL_DIR} | 이 SKILL.md의 디렉토리 (스크립트·지원파일 참조용) |
예시 — 명명 인자
1
2
3
4
5
6
7
8
---
name: migrate-component
description: Migrate a component from one framework to another
arguments: [component, from, to]
---
Migrate the $component from $from to $to.
Preserve all existing behavior and tests.
호출: /migrate-component SearchBar React Vue → $component = SearchBar, $from = React, $to = Vue.
7. Skill 위치와 로딩 우선순위
공식 문서의 4가지 스킬 스코프:1
| 스코프 | 경로 | 적용 범위 |
|---|---|---|
| Enterprise | managed settings 경로 | 조직 전체 |
| Personal | ~/.claude/skills/<name>/SKILL.md | 사용자의 모든 프로젝트 |
| Project | .claude/skills/<name>/SKILL.md | 해당 프로젝트만 |
| Plugin | <plugin>/skills/<name>/SKILL.md | 플러그인이 활성된 곳 |
이름 충돌 시 우선순위: Enterprise > Personal > Project. Plugin 스킬은 plugin-name:skill-name 네임스페이스를 가져 다른 레벨과 충돌하지 않는다. .claude/commands/ 의 기존 파일은 그대로 작동하되, 스킬과 같은 이름이면 스킬이 이긴다.
자동 발견 — 부모·중첩 디렉토리
공식 문서가 명시한 두 가지 자동 발견:
- 부모 방향: 현재 시작 디렉토리부터 저장소 루트까지
.claude/skills/를 모두 로드 → 서브디렉토리에서 시작해도 루트 스킬 발견 - 중첩 방향: 시작 디렉토리 아래 서브디렉토리 파일을 다룰 때 그 서브디렉토리의
.claude/skills/를 추가 로드 → 모노레포 패턴
--add-dir로 추가한 디렉토리는 예외적으로 .claude/skills/ 만 로드된다 (다른 .claude/ 구성은 미로딩).
8. Skill content lifecycle — 세션 끝까지 머문다
공식 문서가 강조하는 lifecycle 사실:1
“When you or Claude invoke a skill, the rendered SKILL.md content enters the conversation as a single message and stays there for the rest of the session. Claude Code does not re-read the skill file on later turns.”
핵심 함의:
- SKILL.md 본문은 한 번 컨텍스트에 들어간 뒤 세션 끝까지 머문다.
- 이후 턴에 파일을 수정해도 그 세션엔 반영되지 않는다.
- 작성 시점에 “이 텍스트가 매 턴 토큰을 차지한다” 는 인식이 필요하다 — 길게 쓰면 그만큼 모든 후속 응답에 비용이 든다.
Auto-compaction 시 재첨부 정책
공식 문서가 명시한 수치:1
- 각 스킬의 가장 최근 invocation 만 재첨부
- 각 스킬에서 첫 5,000 토큰 까지 보존
- 재첨부된 스킬 전체 합 25,000 토큰 budget
- 최근 invocation 부터 채우므로 오래된 스킬은 잘릴 수 있음
이 두 수치(5,000 / 25,000)는 재첨부 시점 budget 이지, 스킬 작성 시 max-tokens 한도 가 아니다.
“스킬이 영향력을 잃은 것 같다” 시
공식 문서의 진단: 콘텐츠는 여전히 컨텍스트에 있고, 모델이 다른 도구를 선호하는 것이 보통. 해결: (a) description 강화 → 모델이 계속 선호하도록, (b) hooks로 결정론적 강제, (c) 큰 스킬이나 다수 후속 invocation 후엔 재호출로 콘텐츠 부활.
9. 권한·거버넌스 — allowed-tools / skillOverrides
allowed-tools — 허용만, 제한은 아님
공식 문서가 명시:1
“It does not restrict which tools are available: every tool remains callable, and your permission settings still govern tools that are not listed.”
allowed-tools는 스킬 활성 중에 해당 도구를 무승인으로 만든다. 다른 도구를 막는 게 아니다. 막으려면 /permissions의 deny 룰을 쓴다.
저장소 .claude/skills/에 체크인된 스킬의 allowed-tools는 워크스페이스 trust 다이얼로그를 수락한 후 발효한다 — .claude/settings.json 권한 룰과 동일한 정책이다.
/permissions 의 Skill(...) 패턴
1
2
3
4
5
6
7
8
9
# 특정 스킬만 허용
Skill(commit)
Skill(review-pr *)
# 특정 스킬 차단
Skill(deploy *)
# Skill 도구 자체를 deny (모든 스킬 차단)
Skill
문법: Skill(name) 정확 매칭, Skill(name *) 접두사 매칭.
skillOverrides — settings로 가시성 제어
SKILL.md 자체는 수정하지 않고 settings로 가시성을 바꾼다. 4단계 상태:1
| 값 | Claude에 노출 | / 메뉴 |
|---|---|---|
"on" | 이름 + description | 보임 |
"name-only" | 이름만 | 보임 |
"user-invocable-only" | 숨김 | 보임 |
"off" | 숨김 | 숨김 |
1
2
3
4
5
6
{
"skillOverrides": {
"legacy-context": "name-only",
"deploy": "off"
}
}
플러그인 스킬은 skillOverrides로 제어되지 않는다 — /plugin 메뉴에서 관리한다.
10. 정리 — 작성자가 매번 기억할 6가지
description은 짧게 — 매 턴 토큰을 차지하고 1,536자 캡이 있다.- 사이드이펙트가 있으면
disable-model-invocation: true— Claude가 임의 호출하지 않도록. - 격리가 필요하면
context: fork— 부모 컨텍스트 잠식 방지.agent: Explore로 CLAUDE.md·git status 스킵. - 동적 데이터는
!`<command>`— `` 가 아니다. allowed-tools는 허용만, 차단은/permissionsdeny — 두 메커니즘이 다르다.- SKILL.md 콘텐츠는 한 번 들어가면 세션 끝까지 머문다 — 모든 라인이 재발생 비용이라는 인식.
참고
관련 포스트
- Claude Code 스킬 작성 완전 가이드 — OMC 기반 스킬 워크플로우와 자동화 설계
- Claude Code 스킬 작성 팁 — OMC 스킬 실전 패턴
- Claude Code Hooks 완전 가이드 — 라이프사이클 이벤트와 settings.json 구조
- Claude Code 서브에이전트 설계 패턴 —
context: fork와 비교 - AI 코딩 에이전트 보안 — Prompt Injection 방어 —
allowed-tools·셸 주입 가드레일