스킬 시스템

1. 스킬이란 무엇인가?

스킬은 Claude Code가 발견하고 실행할 수 있는, 이름이 붙은 재사용 가능한 프롬프트 워크플로입니다. 스킬은 YAML 프런트매터 헤더가 있는 SKILL.md Markdown 파일로 저장되거나, bundled skills 형태로 CLI 바이너리에 직접 컴파일됩니다.

사용자 관점에서 스킬은 슬래시 명령입니다. /commit, /simplify, /review-pr 같은 형태죠. Claude 관점에서 스킬 호출은 Skill tool(Skill)을 부르는 일이며, 이 도구는 전체 프롬프트를 로드하고, 인자를 치환하고, 필요하면 인라인 셸 블록을 실행한 뒤, 결과를 대화에 주입합니다.

2. 스킬 생명주기

모든 스킬은 Claude Code가 시작되는 순간부터 Claude가 실제로 그것을 실행하는 순간까지 여섯 단계를 거칩니다.

발견

시작 시점에 getSkillDirCommands()는 네 위치를 병렬로 순회하고, 레거시 .claude/commands/ 디렉터리도 함께 로드합니다. 심볼릭 링크는 realpath()로 해석되므로, 중복 파일은 내용이 같고 경로만 달라도 Claude에 도달하기 전에 제거됩니다.

로드

각 skill-name/SKILL.md 파일을 읽습니다. 토큰 수는 프런트매터만 기준으로 추정하며(name + description + whenToUse), 전체 본문은 시작 시 토큰화하지 않습니다. 덕분에 스킬이 수백 개여도 목록을 빠르게 보여줄 수 있습니다. 목록 자체도 컨텍스트 윈도우의 1%로 예산이 제한됩니다.

파싱

프런트매터는 Command 객체로 파싱됩니다. 여기서 description, allowed tools, argument hints, model override, hooks, paths, effort, shell 같은 모든 필드를 검증합니다. paths 필드가 있는 스킬은 조건부 스킬이 되며, 저장은 되지만 사용자가 일치하는 파일을 열기 전까지는 Claude에 노출되지 않습니다.

치환

스킬이 호출되면 본문에서 다음 순서로 인자 치환이 일어납니다.

1. 이름 붙은 인자: $foo, $bar (arguments 프런트매터의 위치 기반 매핑)
2. 인덱스 인자: $ARGUMENTS[0], $0, $1
3. 전체 인자 문자열: $ARGUMENTS
4. 플레이스홀더가 없고 인자가 있으면 ARGUMENTS: ... 형태로 뒤에 붙임
5. 셸 주입: !`command` 또는 ```! 블록(로컬 스킬만 가능, MCP 스킬은 차단됨)
6. 특수 변수: ${CLAUDE_SKILL_DIR}, ${CLAUDE_SESSION_ID}

실행

스킬은 프런트매터의 context: fork 여부에 따라 두 방식 중 하나로 실행됩니다.

• Inline (기본값): 확장된 프롬프트가 현재 대화에 사용자 메시지로 주입됩니다. Claude는 같은 컨텍스트 윈도우 안에서 이를 처리합니다.
• Forked: 스킬은 자기 토큰 예산을 가진 격리된 서브 에이전트(runAgent())에서 실행됩니다. 상위 대화는 최종 텍스트 출력만 받습니다. 독립적인 작업에 적합합니다.

주입

Skill tool은 ToolResult를 반환합니다. inline 스킬에서는 결과에 allowedTools와 선택적 model 오버라이드가 담겨, 이번 턴의 이후 도구 호출에 적용됩니다. forked 스킬에서는 Done 표시가 나오고, 서브 에이전트의 출력이 다시 컨텍스트로 들어갑니다.

3. 네 가지 스킬 출처와 우선순위

스킬은 네 가지 서로 다른 출처에서 올 수 있습니다. 두 출처가 같은 이름의 스킬을 정의하면 먼저 로드된 쪽이 이깁니다 (managed > user > project > bundled). 중복 제거는 이름이 아니라 해석된 파일 경로 기준이므로, 심볼릭 링크된 스킬이 실제 파일을 가릴 수도 있습니다.

다섯 번째 출처, MCP skills

MCP 서버가 스킬을 노출하면 (loadedFrom === 'mcp'로 감지), 연결 시점에 가져와 명령 레지스트리에 추가합니다. MCP skills는 같은 프런트매터 스키마를 따르지만 셸 주입은 차단되며, 원격의 신뢰할 수 없는 콘텐츠에 대해서는 !backtick과 ```! 블록을 절대 실행하지 않습니다.

레거시: .claude/commands/

예전의 /commands/ 디렉터리도 아직 지원됩니다 (loadedFrom: 'commands_DEPRECATED'). 단일 .md 파일과 skill-name/SKILL.md 디렉터리 형식을 모두 받습니다. 새 작업은 .claude/skills/를 써야 합니다.

라이브 리로딩

skillChangeDetector 모듈은 chokidar로 스킬 디렉터리를 감시합니다. 어떤 SKILL.md든 바뀌면 300 ms 디바운스를 거친 뒤 ConfigChange 훅을 실행하고, 모든 메모이제이션 캐시를 비워 다음 호출에서 새 스킬을 보게 합니다. Bun에서는 알려진 데드락 버그를 피하려고 FSWatcher 대신 stat-polling을 사용합니다.

4. SKILL.md 형식과 프런트매터

스킬 파일은 ---로 구분된 선택적 YAML 프런트매터 블록이 붙은 일반 Markdown입니다. 파일은 반드시 <skill-name>/SKILL.md 위치에 있어야 하며, 디렉터리 이름이 슬래시 명령 이름이 됩니다.

필드 참고

5. 고급 스킬 패턴

---
paths: src/payments/**
description: "Stripe refund workflow"
---

# Stripe Refund
Stripe API로 환불을 처리하는 단계...

// bundled skill 등록
registerBundledSkill({
  name: 'simplify',
  description: 'Review changed code for reuse, quality, and efficiency.',
  userInvocable: true,
  async getPromptForCommand(args) {
    return [{ type: 'text', text: SIMPLIFY_PROMPT }]
  },
})

// getAllCommands()가 MCP와 로컬 스킬을 합치는 방식
const mcpSkills = context.getAppState().mcp.commands
  .filter(cmd => cmd.type === 'prompt' && cmd.loadedFrom === 'mcp')
const localCommands = await getCommands(getProjectRoot())
return uniqBy([...localCommands, ...mcpSkills], 'name')

/myskill "hello world" foo  →  ["hello world", "foo"]

6. 핵심 정리

• 📁 스킬은 <skill-name>/SKILL.md에 있습니다. 디렉터리 이름이 슬래시 명령이 됩니다. 모든 메타데이터는 YAML 프런트매터가 제어하고, Markdown 본문이 프롬프트입니다.
• 🔍 Claude는 우선순위 순서대로 네 출처에서 스킬을 발견합니다. managed → user → project → bundled 순서입니다. MCP skills는 호출 시점에 별도로 합쳐집니다.
• ⚡ 스킬은 inline (기본값, 같은 대화 컨텍스트) 또는 forked (context: fork, 격리된 서브 에이전트)로 실행됩니다. fork는 독립적인 작업에, inline은 중간에 방향을 잡아야 하는 작업에 더 적합합니다.
• 🔒 MCP skills는 셸 주입을 절대 실행하지 않습니다. !backtick 블록을 실행할 수 있는 것은 로컬(managed/user/project/bundled) 스킬뿐입니다. 이것은 소스 코드에 박혀 있는 강한 보안 경계입니다.
• 🎯 paths 프런트매터는 스킬을 조건부로 만듭니다. 일치하는 파일이 열리기 전까지는 보이지 않습니다. 도메인 특화 워크플로를 관련 있을 때만 노출할 때 쓰면 좋습니다.
• 💡 스킬 목록은 컨텍스트 윈도우의 1%로 예산 제한을 받습니다. bundled skill 설명은 절대 잘리지 않고, 사용자 정의 스킬 설명은 목록이 예산을 넘기면 짧아질 수 있습니다.
• 🔄 스킬 파일은 실시간 감시됩니다. SKILL.md를 저장하면 디바운스된 리로드가 일어나며 (300 ms), 재시작은 필요 없습니다.
• ✅ 단순한 스킬(allowed-tools 없음, model override 없음)은 권한 프롬프트 없이 자동 승인됩니다. 더 강한 권한의 스킬은 명시적인 사용자 allow 규칙이 필요합니다.