Claude를 skills로 확장하기

Claude Code에서 skills를 생성, 관리 및 공유하여 Claude의 기능을 확장합니다. 사용자 정의 명령어 및 번들 skills를 포함합니다.

Skills는 Claude가 할 수 있는 작업을 확장합니다. SKILL.md 파일을 지침과 함께 생성하면 Claude가 이를 자신의 도구 모음에 추가합니다. Claude는 관련성이 있을 때 skills를 사용하거나, /skill-name으로 직접 호출할 수 있습니다.

동일한 지침, 체크리스트 또는 다단계 절차를 반복해서 채팅에 붙여넣거나, CLAUDE.md의 섹션이 사실이 아닌 절차로 성장했을 때 skill을 생성합니다. CLAUDE.md 콘텐츠와 달리, skill의 본문은 사용할 때만 로드되므로 긴 참고 자료는 필요할 때까지 거의 비용이 들지 않습니다.

Claude Code skills는 여러 AI 도구에서 작동하는 Agent Skills 개방형 표준을 따릅니다. Claude Code는 호출 제어, subagent 실행, 동적 컨텍스트 주입과 같은 추가 기능으로 표준을 확장합니다. Claude Code 외부에서 skill frontmatter 사용에서 어떤 frontmatter 필드가 표준의 일부이고 어떤 필드가 Claude Code 확장인지 확인하세요.

번들된 스킬

Claude Code에는 /doctor, /code-review, /batch, /debug, /loop, /claude-api 등의 번들된 스킬 세트가 포함되어 있습니다. 번들된 스킬은 프롬프트 기반입니다. 즉, Claude에 상세한 지침을 제공하고 도구를 사용하여 작업을 조율하도록 합니다. 대부분의 기본 제공 명령어는 대신 고정된 로직을 직접 실행합니다.

번들된 스킬은 다른 스킬과 동일한 방식으로 호출합니다. / 다음에 스킬 이름을 입력하면 됩니다. Claude는 관련성이 있을 때 일부 번들된 스킬을 자동으로 호출합니다. /verify를 포함한 다른 스킬은 사용자가 호출할 때만 실행되므로, 이러한 더 오래 실행되는 검사가 시간과 토큰을 소비하는 시점을 제어할 수 있습니다.

대부분의 번들된 스킬은 모든 세션에서 사용 가능합니다. 일부는 특정 기능에 따라 달라집니다. 예를 들어 /workflow-authoring은 동적 워크플로우가 활성화된 경우에만 사용 가능합니다.

번들된 스킬을 끄려면 disableBundledSkills 설정을 사용하면 되며, 이는 /doctor를 제외한 모든 번들된 스킬을 비활성화합니다.

번들된 스킬은 명령어 참조에서 기본 제공 명령어와 함께 나열되며, 목적 열에 Skill로 표시됩니다.

앱 실행 및 확인

세 가지 번들된 스킬이 함께 작동하여 앱을 시작하고 테스트만이 아닌 실행 중인 앱에 대해 변경 사항을 확인합니다.

스킬	목적
`/run`	앱을 시작하고 실행하여 변경 사항이 작동하는지 확인
`/verify`	앱을 빌드하고 실행하여 코드 변경이 의도한 대로 작동하는지 확인하며, 테스트나 타입 검사로 폴백하지 않음
`/run-skill-generator`	`/run`과 `/verify`에 프로젝트를 빌드하고 시작하는 방법을 학습시킴

/run과 /verify는 설정 없이 작동합니다. 프로젝트 유형(CLI, 서버, TUI, 브라우저 기반)과 README, package.json 또는 Makefile의 내용으로부터 시작을 추론합니다. 이 추론은 표준 시작 이상의 것이 필요한 프로젝트(데이터베이스, env 파일, 그래픽 세션, 다단계 빌드)에서는 신뢰할 수 없게 됩니다.

/run-skill-generator는 대신 레시피를 기록합니다. 깨끗한 환경에서 앱을 실행하고, 작동한 것(설치 명령어, env 변수, 시작 스크립트)을 캡처하고, 프로젝트별 스킬로 .claude/skills/run-<name>/에 커밋합니다. 그 후 /run, /verify 및 리포지토리의 다른 에이전트는 레시피를 다시 발견하는 대신 기록된 레시피를 따릅니다. 프로젝트당 한 번 /run-skill-generator를 실행하고, 빌드 또는 시작 프로세스가 변경되면 다시 실행합니다.

/verify는 자체 레시피를 기록할 수도 있습니다. 기록된 레시피 없이 앱을 빌드하고 실행해야 할 때, 작동한 것을 리포지토리 루트의 .claude/skills/verify/SKILL.md에 또는 모노레포의 터치된 패키지 디렉토리에 작성하므로 나중의 실행과 다른 에이전트가 동일한 단계를 따릅니다. 리포지토리 루트에서 기록된 스킬은 번들된 /verify를 대체합니다. 이는 Claude Code v2.1.200 이상이 필요합니다.

Claude는 실패한 명령어나 누락된 단계와 같이 실행을 잘못 조종한 경우에만 기록된 파일을 편집하므로 세션별 diff 없이 파일을 커밋할 수 있습니다. v2.1.205 이전에는 번들된 스킬이 Claude에 실행이 학습한 모든 것을 포함하도록 지시했으므로 빈번한 병합 충돌이 발생했습니다.

시작하기

첫 번째 skill 만들기

이 예제는 git 저장소의 커밋되지 않은 변경 사항을 요약하고 위험한 부분을 표시하는 skill을 만듭니다. 실시간 diff를 Claude가 읽기 전에 프롬프트로 가져오므로, 응답이 Claude가 열린 파일에서 추측할 수 있는 것이 아니라 실제 작업 트리에 기반합니다. Claude는 변경 사항에 대해 물어볼 때 자동으로 skill을 로드하거나, /summarize-changes로 직접 호출할 수 있습니다.

skill 디렉토리 만들기

개인 skills 폴더에 skill용 디렉토리를 만듭니다. 개인 skills는 모든 프로젝트에서 사용할 수 있습니다.

mkdir -p ~/.claude/skills/summarize-changes

SKILL.md 작성

모든 skill에는 SKILL.md 파일이 필요합니다. 이 파일은 두 부분으로 구성됩니다: Claude에게 skill을 언제 사용할지 알려주는 --- 마커 사이의 YAML frontmatter와 skill이 실행될 때 Claude가 따르는 지침이 포함된 markdown 콘텐츠입니다. 디렉토리 이름이 입력하는 명령어가 되고, description은 Claude가 skill을 자동으로 로드할지 결정하는 데 도움이 됩니다.

이를 ~/.claude/skills/summarize-changes/SKILL.md에 저장합니다:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

!`git diff HEAD` 줄은 동적 컨텍스트 주입을 사용합니다: Claude Code는 명령어를 실행하고 Claude가 skill 콘텐츠를 보기 전에 줄을 출력으로 바꾸므로, 지침이 현재 diff가 이미 인라인된 상태로 도착합니다.

skill 테스트

git 프로젝트를 열고, 파일을 약간 편집한 후 claude를 실행하여 Claude Code를 시작합니다. skill을 두 가지 방법으로 테스트할 수 있습니다.

설명과 일치하는 내용을 물어봐서 Claude가 자동으로 호출하도록 하기:

What did I change?

또는 skill 이름으로 직접 호출:

/summarize-changes

어느 쪽이든 Claude는 편집 내용의 짧은 요약과 위험 목록으로 응답해야 합니다.

스킬이 로드되는 위치 선택

스킬을 저장하는 위치에 따라 어떤 세션에서 로드될지가 결정됩니다. 홈 디렉토리에 저장하면 모든 프로젝트에서 로드되고, 저장소에 커밋하면 그곳에서 작업하는 모든 사람이 사용할 수 있으며, 플러그인이나 관리형 설정을 통해 배포하면 전체 팀이 접근할 수 있습니다.

위치	경로	로드되는 위치
Enterprise	`.claude/skills/<skill-name>/SKILL.md` in the managed settings directory	조직이 배포한 머신의 모든 사용자
Personal	`~/.claude/skills/<skill-name>/SKILL.md`	이 머신의 모든 프로젝트, 단 Cowork 또는 클라우드 세션은 제외
Project	`.claude/skills/<skill-name>/SKILL.md`	이 저장소의 세션. 커밋하면 팀도 사용할 수 있습니다
Nested	`<subdir>/.claude/skills/<skill-name>/SKILL.md`	`<subdir>`에서 시작되거나 그 아래에서 시작된 세션. `<subdir>` 위에서 시작된 세션은 Claude가 그곳의 파일에서 작업할 때 스킬을 한 번 로드합니다. 모노레포 및 하위 디렉토리 참조
Additional directory	`.claude/skills/<skill-name>/SKILL.md` in a directory you pass with `--add-dir`	해당 세션. 프로젝트 외부의 디렉토리 참조
Plugin	`<plugin>/skills/<skill-name>/SKILL.md`	플러그인이 활성화된 곳, `/plugin-name:skill-name`으로 표시
claude.ai account	claude.ai 설정에서 활성화한 스킬	Cowork 및 클라우드 세션. 로컬 세션의 경우 claude.ai에서 동기화된 스킬 참조

스킬 폴더는 또한 다음 규칙을 따릅니다:

심볼릭 링크된 폴더: enterprise, personal 또는 project 위치의 <skill-name> 항목은 디스크의 다른 곳에 있는 디렉토리로의 심볼릭 링크일 수 있습니다. Claude Code는 대상에서 SKILL.md를 읽고 여러 위치가 같은 대상을 가리키더라도 스킬을 한 번만 로드합니다. 플러그인 스킬은 심볼릭 링크를 다르게 처리합니다.
예약된 이름: 스킬 폴더를 synced로 이름 지으면 안 됩니다(대소문자 상관없음). Claude Code는 ~/.claude/skills/synced/를 claude.ai에서 다운로드한 스킬에 사용하고 enterprise, personal 및 project 위치에서 해당 이름으로 작성한 스킬을 건너뜁니다.
명령 파일: .claude/commands/의 Markdown 파일은 이전 형식이며 여전히 작동합니다. name 및 paths를 제외한 동일한 frontmatter를 지원하며, 파일 이름으로 호출합니다. 새 작업에는 스킬을 선호하세요. 스킬은 지원 파일도 지원하기 때문입니다.
플러그인으로서의 스킬 폴더: 스킬 폴더에 .claude-plugin/plugin.json을 추가하면 <name>@skills-dir이라는 이름의 플러그인으로 로드되므로 에이전트, hooks 및 MCP 서버를 번들할 수 있습니다. 프로젝트의 .claude/skills/에서는 먼저 워크스페이스 신뢰 대화를 수락해야 합니다.

모노레포 및 하위 디렉토리에서 스킬 로드

Claude Code는 시작한 디렉토리와 저장소 루트까지의 모든 상위 디렉토리에서 .claude/skills/의 프로젝트 스킬을 로드하므로, packages/frontend/에서 시작해도 루트에 정의된 스킬을 선택합니다. v2.1.246 이상에서 /cd로 세션을 이동할 때, Claude Code는 새 디렉토리의 프로젝트 스킬을 추가합니다.

시작한 위치 아래의 .claude/skills/ 디렉토리에 있는 스킬은 시작 시 로드되지 않습니다. Claude가 해당 하위 디렉토리의 파일을 처음 읽거나 편집할 때 로드되고 세션의 나머지 기간 동안 사용 가능합니다. 그때까지는 / 메뉴에 나타나지 않으며 이름으로 호출할 수 없습니다. 더 빨리 로드하려면 하위 디렉토리의 경로로 /add-dir을 실행하세요. 이는 Claude Code v2.1.257 이상이 필요합니다.

중첩된 스킬이 다른 스킬과 이름을 공유할 때, 둘 다 사용 가능합니다. 저장소 루트에 deploy 스킬이 있고 apps/web/.claude/skills/에 다른 스킬이 있을 때:

/deploy는 루트 스킬을 실행합니다. Claude Code는 또한 Claude를 위해 디렉토리 한정 변형을 나열하며, 작업 중인 파일이 있는 디렉토리의 스킬을 호출하도록 지시하므로 중첩된 스킬은 여전히 apps/web/의 작업에 적용됩니다.
/apps/web:deploy는 중첩된 스킬을 독립적으로 실행합니다. 설명에 적용되는 디렉토리의 이름이 지정됩니다.

프로젝트 외부의 디렉토리에서 스킬 로드

--add-dir 또는 /add-dir으로 디렉토리를 추가할 때, Claude Code는 해당 디렉토리의 .claude/skills/에 있는 스킬과 .claude/commands/ 및 .claude/agents/를 로드합니다. Agent SDK가 TypeScript의 additionalDirectories 또는 Python의 add_dirs를 통해 추가하는 디렉토리는 SDK가 --add-dir으로 전달하기 때문에 동일한 방식으로 로드됩니다. settings.json의 permissions.additionalDirectories 설정은 파일 액세스만 부여하고 이 중 어느 것도 로드하지 않습니다.

Claude Code는 시작 시 --add-dir으로 전달한 디렉토리의 .claude/skills/를 세션 중 스킬 편집에서 설명하는 대로 감시합니다. 추가된 디렉토리의 .claude/commands/ 또는 .claude/agents/는 감시하지 않으므로 파일을 변경한 후 세션을 다시 시작하세요.

이러한 로드는 기본적으로 켜져 있는 project 설정 소스에 따라 달라집니다. strictPluginOnlyCustomization 정책, bare mode 및 --safe-mode는 각각 이를 더 제한하며, 해당 페이지에서 설명합니다. 추가된 디렉토리가 로드하는 것(CLAUDE.md 및 플러그인 설정 포함)의 전체 표는 추가 디렉토리는 파일 액세스를 부여하지만 구성은 부여하지 않습니다를 참조하세요.

두 스킬이 이름을 공유할 때, 각각이 어디에서 왔는지가 /name이 실행하는 스킬을 결정합니다. 표는 enterprise, personal, project, nested, plugin 및 claude.ai 위치, 번들된 스킬 및 명령 파일을 다룹니다:

같은 이름 위치	실행되는 스킬
Enterprise, personal 및 project 중 두 개	Enterprise가 personal보다 우선하고, personal이 project보다 우선합니다. `~/.claude/skills/`와 프로젝트의 `.claude/skills/` 모두에 `deploy`가 있으면 `/deploy`는 personal 스킬을 실행합니다
위의 위치 중 하나와 번들된 스킬	사용자 스킬이 번들된 명령을 대체하지만 별칭은 대체하지 않습니다. 프로젝트 `code-review` 스킬은 `/code-review`를 대체하고, 번들된 별칭 `/review`는 사용자 스킬을 실행하지 않습니다
스킬과 `.claude/commands/`의 파일	스킬
프로젝트 루트 스킬과 중첩된 스킬	둘 다 로드됩니다. 모노레포 및 하위 디렉토리 참조
플러그인 스킬과 위의 위치 중 하나의 스킬	플러그인 스킬이 `/plugin-name:skill-name`으로 네임스페이스되기 때문에 둘 다 로드됩니다
위의 모든 것과 claude.ai에서 동기화된 스킬	다른 스킬 또는 명령. 동기화된 스킬 이름이 다른 명령과 일치할 때 참조

Cowork 및 클라우드 세션에서 스킬 사용

Cowork 세션 및 클라우드 세션(루틴 포함)은 머신의 ~/.claude/skills/를 읽지 않습니다. 대화형 및 예약된 Cowork 세션 모두 claude.ai 계정에 대해 활성화된 스킬을 로드하며, 세션 시작 시 동기화됩니다. Desktop 앱 사이드바의 Customize에서 또는 claude.ai의 스킬 설정에서 관리하세요. 클라우드 세션은 추가로 복제된 저장소의 .claude/skills/에 커밋된 프로젝트 스킬을 로드합니다.

스킬이 머신의 ~/.claude/skills/에만 있으면, 루틴이 호출할 때 Claude Code는 스킬을 찾을 수 없다고 보고합니다. 각 루틴 실행이 새로운 원격 세션으로 시작되기 때문입니다. 이러한 세션에서 personal 스킬을 사용 가능하게 하려면:

Cowork 및 클라우드 세션의 경우 claude.ai 계정에 대해 스킬을 활성화하세요.
클라우드 세션의 경우 대신 저장소의 .claude/skills/에 스킬을 커밋하거나, 저장소의 .claude/settings.json에 선언된 플러그인에 포함시킬 수 있습니다. 저장소 선언 플러그인은 세션 시작 시 설치됩니다. 사용자 설정에서만 활성화된 플러그인은 전송되지 않습니다.

Desktop 예약된 작업은 머신에서 로컬로 실행되므로 ~/.claude/skills/를 로드합니다.

claude.ai에서 동기화된 스킬

이 섹션은 claude.ai 계정에 대해 스킬을 활성화한 경우에 적용됩니다. Cowork 및 클라우드 세션에서 Claude Code는 머신에서 설정할 필요 없이 해당 스킬을 로드합니다. 머신의 다른 세션에서 Claude Code는 비대화형 실행에서 CLAUDE_CODE_SYNC_SKILLS로 동기화를 켠 후에만 로드합니다. 동기화된 스킬이 로드되는 위치에서 설명합니다.

Claude Code는 세션이 실행되는 머신에서 작성한 파일을 읽는 대신 계정에서 동기화된 스킬을 다운로드하므로, 스킬 위치에 저장하는 스킬에 적용되지 않는 규칙을 동기화된 스킬에 적용합니다.

동기화된 스킬이 로드되는 위치

Cowork 또는 클라우드 세션에서 Claude Code는 claude.ai 계정에 대해 활성화된 스킬을 로드하며, Cowork 및 클라우드 세션에서 스킬 사용에서 해당 세션이 어떤 스킬을 받을지 선택하는 방법을 설명합니다.

머신의 다른 세션에서 Claude Code는 비대화형 실행에서 한 번 다운로드한 후에만 로드합니다:

claude.ai 계정에 대해 스킬 활성화

Cowork 및 클라우드 세션에서 스킬 사용에서 설명하는 대로 claude.ai 계정에 대해 원하는 각 스킬을 활성화하세요. Claude Code는 활성화한 스킬만 다운로드하며, 다운로드하려면 claude.ai 로그인이 필요합니다.

동기화가 켜진 비대화형 모드에서 Claude Code 실행

Claude Code는 CLAUDE_CODE_SYNC_SKILLS를 1로 설정하고 -p 플래그로 비대화형 모드에서 실행할 때만 동기화된 스킬을 다운로드합니다. 전달하는 프롬프트는 다운로드에 영향을 주지 않습니다.

CLAUDE_CODE_SYNC_SKILLS=1 claude -p "List the skills you have available"

Claude Code는 스킬을 ~/.claude/skills/synced/로 다운로드하고, 프롬프트에 답하고, 다른 비대화형 실행처럼 종료합니다. 다운로드된 스킬은 종료 후 디스크에 남아 있으므로 실행을 계속 열어 둘 필요가 없습니다. Claude Code는 CLAUDE_CODE_SYNC_SKILLS가 설정된 실행 중에만 스킬을 다운로드하므로, claude.ai에서 스킬을 활성화하거나 변경한 후 명령을 다시 실행하세요. 동기화를 기다리는 실행 시간을 변경하려면 CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS를 설정하세요.

로컬 세션에서 스킬이 로드되는지 확인

CLAUDE_CODE_SYNC_SKILLS를 설정하지 않고 대화형 세션을 시작하고 /skills를 실행하세요. 메뉴는 다운로드된 스킬을 claude.ai sync 아래에 나열합니다. 같은 claude.ai 로그인으로 시작하는 모든 후속 로컬 세션도 ~/.claude/skills/synced/에서 로드합니다.

동기화된 스킬 이름이 다른 명령과 일치할 때

Claude Code는 이름이 다른 명령과 일치하는 동기화된 스킬을 건너뛰고, 그 다른 명령이 실행됩니다. 다른 명령은 기본 제공 명령, 번들된 스킬, 로컬 수준 중 하나의 스킬, 플러그인 스킬, .claude/commands/의 파일 또는 MCP 프롬프트일 수 있습니다. Claude Code는 또한 번들된 스킬을 끈 후처럼 세션에서 사용할 수 없을 때도 자체 기본 제공 명령 및 번들된 스킬의 이름을 예약하므로, 해당 이름의 동기화된 스킬을 건너뜁니다.

Claude Code는 동기화된 스킬에 레이블을 지정하므로 어디에서 왔는지 알 수 있습니다. /skills 메뉴와 /context는 동기화된 스킬을 claude.ai sync 아래에 그룹화하고, / 명령 메뉴는 claude.ai에서 온 것으로 표시합니다.

이름을 비교할 때, Claude Code는 대소문자, 공백 및 보이지 않는 문자를 무시하고, 전자 문자 및 대시 변형과 같은 호환성 형식을 일반 등가물로 취급하므로, 동기화된 Commit은 로컬 commit 옆에 로드될 수 없습니다. 다른 알파벳의 모양이 비슷한 문자로만 다른 이름은 다른 이름으로 간주되며, claude.ai sync 레이블은 두 개를 구분하는 방법입니다.

Claude Code가 동기화된 스킬의 frontmatter를 처리하는 방법

Claude Code는 동기화된 스킬의 frontmatter에 두 가지 규칙을 적용합니다:

Claude Code는 모든 종류의 세션에서 frontmatter를 준수하므로, allowed-tools 부여는 일반 권한 흐름을 거칩니다.
Claude Code는 스킬이 제공하는 표시 텍스트(예: 설명)를 정제합니다. 제어 문자를 제거하고, Claude에 도달하는 텍스트(예: 설명)에서 꺾쇠 괄호를 이스케이프하여 텍스트가 Claude Code의 내부 형식을 모방할 수 없도록 합니다.

Claude Code가 동기화된 스킬의 본문을 처리하는 방법

Claude Code가 동기화된 스킬의 본문으로 수행하는 작업은 세션이 실행되는 위치에 따라 달라집니다:

클라우드 세션에서 본문은 로컬 스킬이 가지는 동작을 유지합니다. 세션이 격리된 컨테이너에서 실행되기 때문입니다.
데스크톱의 Cowork 세션에서 본문은 로컬 스킬이 가지는 동작을 유지합니다. 단, Claude Code는 모든 ! 명령 줄을 disableSkillShellExecution 플레이스홀더로 바꿉니다. 모든 스킬에 대해 그곳에서 제공하는 것처럼 말입니다.
머신의 다른 세션에서 Claude Code는 ! 명령을 실행하지 않고, @ 참조가 로컬 스킬에 대해 이름을 지정하는 방식으로 파일을 첨부하지 않으며, ${CLAUDE_PROJECT_DIR} 및 ${CLAUDE_SESSION_ID} 플레이스홀더를 대체하지 않으므로, @ 참조와 두 플레이스홀더 모두 Claude에 리터럴 텍스트로 도달합니다. ! 명령 줄도 리터럴 텍스트로 도달하거나, disableSkillShellExecution이 켜져 있을 때 해당 플레이스홀더로 도달합니다.

세션 중 스킬 편집

Claude Code는 bare mode를 제외하고 스킬 디렉토리의 파일 변경을 감시합니다. ~/.claude/skills/, 프로젝트 .claude/skills/ 또는 --add-dir 디렉토리 내의 .claude/skills/ 아래에서 스킬을 추가, 편집 또는 제거할 때, Claude Code는 재시작 없이 현재 세션 내에서 변경 사항을 선택합니다. 세션 시작 시 존재하지 않던 최상위 스킬 디렉토리를 만들면 Claude Code를 다시 시작하여 새 디렉토리를 감시할 수 있도록 하세요.

라이브 변경 감지는 SKILL.md 텍스트만 다룹니다. 플러그인이기도 한 스킬 폴더의 경우, hooks/, .mcp.json, agents/ 및 output-styles/의 변경 사항은 /reload-plugins가 적용되어야 합니다.

스킬 제거

스킬을 제거하는 방법은 어디에서 왔는지에 따라 다릅니다:

Personal 또는 project 스킬: 스킬의 디렉토리 ~/.claude/skills/<skill-name>/ 또는 .claude/skills/<skill-name>/을 삭제하세요. Claude Code는 현재 세션의 /skills에서 삭제합니다. Claude Code가 이미 로드한 콘텐츠는 스킬 콘텐츠 수명 주기를 따릅니다.
Enterprise 스킬: 관리자가 관리형 설정 디렉토리 내의 .claude/skills/에서 스킬의 디렉토리를 삭제합니다. 예를 들어 Linux의 /etc/claude-code/.claude/skills/<skill-name>/.
Plugin 스킬: /plugin 메뉴에서 또는 /plugin uninstall <plugin-name>@<marketplace-name>으로 스킬을 제공하는 플러그인을 비활성화하거나 제거하세요. Claude Code는 /reload-plugins를 실행하거나 다시 시작한 후 플러그인의 스킬을 언로드합니다. 플러그인 변경 사항을 다시 시작하지 않고 적용 참조.
claude.ai에서 동기화된 스킬: 활성화한 것과 같은 위치에서 claude.ai 계정에 대해 스킬을 끄세요. Claude Code는 다음 번 스킬을 동기화할 때 ~/.claude/skills/synced/에서 제거합니다. 대신 디렉토리를 직접 삭제하면 다음 동기화가 스킬이 claude.ai에서 활성화된 상태로 유지되는 동안 다시 다운로드합니다.
번들된 스킬: disableBundledSkills를 true로 설정하여 /doctor를 제외한 모든 번들된 스킬을 끄거나, skillOverrides에서 하나의 스킬을 "off"로 설정하여 숨기세요.

Personal 또는 project 스킬을 유지하지만 Claude가 자동으로 호출하지 않도록 하려면, frontmatter에서 disable-model-invocation: true를 설정하거나, 파일을 편집하지 않으려면 skillOverrides에서 "user-invocable-only"를 설정하세요.

스킬 구성

스킬은 SKILL.md 상단의 YAML 프론트매터와 그 뒤에 오는 마크다운 콘텐츠를 통해 구성됩니다.

스킬 콘텐츠의 유형

스킬 파일은 모든 지침을 포함할 수 있지만, 스킬을 어떻게 호출하고 싶은지 생각하면 포함할 내용을 결정하는 데 도움이 됩니다.

참고 콘텐츠는 Claude가 현재 작업에 적용하는 지식을 추가합니다. 규칙, 패턴, 스타일 가이드, 도메인 지식입니다. 이 콘텐츠는 인라인으로 실행되므로 Claude가 대화 컨텍스트와 함께 사용할 수 있습니다.

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

작업 콘텐츠는 Claude에게 배포, 커밋 또는 코드 생성과 같은 특정 작업에 대한 단계별 지침을 제공합니다. 이러한 작업은 Claude가 실행 시기를 결정하도록 하기보다는 /skill-name으로 직접 호출하려는 작업인 경우가 많습니다. Claude가 자동으로 트리거하는 것을 방지하려면 disable-model-invocation: true를 추가합니다. 아래 예제는 context: fork를 추가하며, 이는 스킬을 자체 서브에이전트 컨텍스트에서 실행합니다. 서브에이전트에서 스킬 실행을 참조하세요.

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

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

본문 자체는 간결하게 유지합니다. 스킬이 로드되면 해당 콘텐츠는 여러 턴에 걸쳐 컨텍스트에 유지되므로 모든 줄이 반복되는 토큰 비용입니다. 어떻게 또는 왜인지 설명하기보다는 무엇을 해야 하는지 명시하고, CLAUDE.md 콘텐츠에 적용할 동일한 간결성 테스트를 적용합니다.

프론트매터 참고

마크다운 콘텐츠 외에도 SKILL.md 파일 상단의 --- 마커 사이의 YAML 프론트매터 필드를 사용하여 스킬 동작을 구성할 수 있습니다.

---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---

Your skill instructions here...

모든 필드는 선택 사항입니다. Claude가 스킬을 언제 사용할지 알 수 있도록 description만 권장됩니다.

Claude Code는 파일의 첫 번째 줄이 ---일 때만 프론트매터를 읽습니다. 그렇지 않으면 --- 마커를 포함한 전체 파일을 스킬 콘텐츠로 취급합니다.

부울 필드는 true 및 false 외에도 모든 문자 케이스에서 yes, no, on, off, 1, 0을 허용합니다. v2.1.218 이전에는 Claude Code가 true 및 false만 인식했습니다.

필드	필수	설명
`name`	아니요	스킬 목록에 표시되는 표시 이름입니다. 기본값은 디렉토리 이름입니다. 스킬이 명령 이름을 얻는 방법을 참조하여 필드가 스킬을 호출하기 위해 입력하는 이름과 어떻게 상호 작용하는지 확인하세요.
`description`	권장	스킬이 무엇을 하는지, 언제 사용할지입니다. Claude는 이를 사용하여 스킬을 적용할 시기를 결정합니다. 생략하면 마크다운 콘텐츠의 첫 번째 단락을 사용합니다. 주요 사용 사례를 먼저 입력하세요. 결합된 `description` 및 `when_to_use` 텍스트는 컨텍스트 사용을 줄이기 위해 스킬 목록에서 1,536자로 잘립니다.
`when_to_use`	아니요	Claude가 스킬을 호출해야 할 때에 대한 추가 컨텍스트입니다. 예를 들어 트리거 구문이나 예제 요청입니다. 스킬 목록의 `description`에 추가되며 1,536자 제한에 포함됩니다.
`argument-hint`	아니요	자동 완성 중에 표시되는 힌트로 예상 인수를 나타냅니다. 예: `[issue-number]` 또는 `[filename] [format]`.
`arguments`	아니요	스킬 콘텐츠에서 `$name` 치환을 위한 명명된 위치 인수입니다. 공백으로 구분된 문자열 또는 YAML 목록을 허용합니다. 이름은 순서대로 인수 위치에 매핑됩니다.
`disable-model-invocation`	아니요	Claude가 이 스킬을 자동으로 로드하는 것을 방지하려면 `true`로 설정합니다. `/name`으로 수동으로 트리거하려는 워크플로우에 사용합니다. 또한 스킬이 서브에이전트에 사전 로드되는 것을 방지합니다. v2.1.196부터 스킬이 예약된 작업이 스킬을 프롬프트로 하여 실행될 때 실행되는 것도 방지합니다. 기본값: `false`.
`user-invocable`	아니요	Claude만 스킬을 호출해야 할 때 `false`로 설정합니다. Claude Code는 `/` 메뉴에서 숨기고 `/name`을 입력할 때 실행하지 않습니다. 사용자가 직접 호출하지 않아야 하는 배경 지식에 사용합니다. 기본값: `true`.
`allowed-tools`	아니요	이 스킬을 호출하는 턴 중에 Claude가 권한을 요청하지 않고 사용할 수 있는 도구입니다. 다음 메시지를 보낼 때 권한이 해제됩니다. 공백 또는 쉼표로 구분된 문자열 또는 YAML 목록을 허용합니다. 스킬에 대한 도구 사전 승인을 참조하세요.
`disallowed-tools`	아니요	이 스킬이 활성화되는 동안 Claude의 사용 가능한 도구 풀에서 제거되는 도구입니다. 자동 루프와 같이 특정 도구를 호출하지 않아야 하는 자율 스킬에 사용합니다(예: `AskUserQuestion`). 공백 또는 쉼표로 구분된 문자열 또는 YAML 목록을 허용합니다. 다음 메시지를 보낼 때 제한이 해제됩니다. 거부 규칙과 마찬가지로 다른 도구가 남아 있는 동안 이 필드는 `EndConversation`을 제거할 수 없습니다.
`model`	아니요	이 스킬이 활성화될 때 사용할 모델입니다. 재정의는 현재 턴의 나머지 부분에 적용되며 설정에 저장되지 않습니다. 다음 프롬프트를 보낼 때 세션 모델이 재개됩니다. `/model`과 동일한 값을 허용하거나 활성 모델을 유지하려면 `inherit`을 허용합니다. 조직의 `availableModels` 허용 목록에서 제외된 값은 사용되지 않으며 세션은 현재 모델을 유지합니다. 자동 모드에서, 그리고 분류자가 명령을 검토하는 동안 계획 모드에서 자동 모드가 지원하지 않는 모델도 사용되지 않으며 세션은 현재 모델을 유지합니다. `context: fork`를 사용하면 값이 포크된 서브에이전트의 모델을 설정하고 제외된 값은 서브에이전트 모델 재정의와 동일한 규칙을 따릅니다.
`effort`	아니요	이 스킬이 활성화될 때의 노력 수준입니다. 세션 노력 수준을 재정의합니다. 기본값: 세션에서 상속됩니다. 옵션: `low`, `medium`, `high`, `xhigh`, `max`. 사용 가능한 수준은 모델에 따라 다릅니다.
`context`	아니요	포크된 서브에이전트 컨텍스트에서 실행하려면 `fork`로 설정합니다. 서브에이전트에서 스킬 실행을 참조하세요.
`agent`	아니요	`context: fork`가 설정되었을 때 사용할 서브에이전트 유형입니다.
`background`	아니요	`context: fork`에만 적용됩니다. 스킬을 호출하는 턴에서 포크된 서브에이전트의 결과를 기다리려면 `false`로 설정합니다. 백그라운드에서 실행 대신입니다. 기본값: `true`. Claude Code v2.1.218 이상이 필요합니다.
`hooks`	아니요	Claude Code가 스킬을 호출할 때 등록하고 세션의 나머지 부분 동안 계속 실행되는 훅입니다. 구성 형식 및 `once` 옵션은 스킬 및 에이전트의 훅을 참조하세요.
`paths`	아니요	이 스킬이 활성화되는 시기를 제한하는 Glob 패턴입니다. 쉼표로 구분된 문자열 또는 YAML 목록을 허용합니다. 설정되면 Claude는 패턴과 일치하는 파일로 작업할 때만 스킬을 자동으로 로드합니다. 경로별 규칙과 동일한 형식을 사용합니다.
`shell`	아니요	이 스킬에서 !`command` 및 ```! 블록에 사용할 셸입니다. `bash`(기본값) 또는 `powershell`을 허용합니다. `powershell`을 설정하면 PowerShell 도구가 활성화되었을 때 PowerShell을 통해 인라인 셸 명령을 실행합니다. Git Bash가 없는 Windows에서는 기본적으로 켜져 있고, Git Bash가 있는 claude.ai 및 Console 계정에서는 기본적으로 켜져 있으며, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 세션 및 macOS, Linux, WSL에서는 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`이 필요합니다. 도구를 끄려면 `0`으로 설정합니다.
`metadata`	아니요	자격 또는 카탈로그 필드와 같은 자신의 키-값 데이터를 위한 자유 형식 YAML 맵으로, `SKILL.md`에서 자신의 도구로 읽습니다. Claude Code는 해당 콘텐츠에 대해 작동하지 않으며 맵이 아닌 값을 삭제합니다. `paths`와 같은 프론트매터 필드 이름을 키로 재사용하지 마세요.
`license`	아니요	스킬을 다루는 라이선스입니다. Agent Skills 사양의 일부입니다. Claude Code 외부에서 스킬 프론트매터 사용을 참조하세요. Claude Code는 필드를 허용하지만 작동하지 않습니다.
`compatibility`	아니요	Agent Skills 사양에서 정의한 대로 의도된 제품 또는 시스템 전제 조건과 같은 스킬의 환경 요구 사항입니다. Claude Code 외부에서 스킬 프론트매터 사용을 참조하세요. 최대 500자의 문자열을 허용합니다. Claude Code는 필드를 허용하지만 작동하지 않습니다.

Claude Code 외부에서 스킬 프론트매터 사용

Claude Code는 위 표의 모든 필드를 허용합니다. Claude Code 외부에서는 Agent Skills 사양의 필드만 사용할 수 있습니다.

배포 경로	사용할 수 있는 프론트매터 필드
모든 수준의 Claude Code 스킬(예: 플러그인 스킬 포함)	위 표의 모든 필드
claude.ai 스킬 업로드, Skills API, anthropics/skills의 `package_skill.py`로 패키징	`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`

Cowork 및 클라우드 세션(루틴 포함)에 대해 개인 스킬을 활성화하면 claude.ai에 업로드되므로 동일한 규칙이 적용됩니다.

사양이 허용하지 않는 필드를 포함하면 필드를 무시하는 대신 하드 오류로 패키징 또는 업로드가 실패합니다.

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

프론트매터를 사양의 6개 필드로 제한하면 위의 예상치 못한 키 오류를 피할 수 있습니다. Agent Skills 사양 및 Skills API 요구 사항은 이러한 경로가 검증하는 다른 모든 것을 정의합니다. Claude Code 전용 본문 기능(예: 동적 컨텍스트 주입)은 claude.ai 채팅 또는 API를 통해 작동하지 않습니다. Claude Code는 6개 필드를 모두 허용하므로 사양을 따르는 프론트매터는 변경 없이 Claude Code에 로드됩니다.

스킬이 명령 이름을 얻는 방법

스킬을 호출하기 위해 입력하는 명령은 스킬 파일이 있는 위치와 플러그인 스킬의 경우 프론트매터 name 필드에서 나옵니다. 개인 또는 프로젝트 스킬에서 name은 스킬 목록에 표시되는 표시 레이블만 설정하고 명령은 여전히 디렉토리 이름에서 나옵니다. 플러그인 스킬에서 name은 명령의 마지막 세그먼트를 설정하고 플러그인 접두사는 제자리에 유지됩니다.

아래 표는 각 레이아웃에 대해 명령 이름이 어디에서 나오는지 보여줍니다.

스킬 위치	명령 이름 소스	예제
`~/.claude/skills/` 또는 `.claude/skills/` 아래의 스킬 디렉토리	디렉토리 이름	`.claude/skills/deploy-staging/SKILL.md` → `/deploy-staging`
중첩된 `.claude/skills/` 디렉토리(이름이 다른 스킬과 충돌할 때)	작업 디렉토리를 기준으로 한 서브디렉토리 경로, 그 다음 스킬 디렉토리 이름	`apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy`
`.claude/commands/` 아래의 파일	확장자 없는 파일 이름	`.claude/commands/deploy.md` → `/deploy`
플러그인 `skills/` 서브디렉토리	프론트매터 `name` 또는 디렉토리 이름(플러그인으로 네임스페이스됨)	`my-plugin/skills/review/SKILL.md` → `/my-plugin:review`, 또는 `name: fancy`를 사용하면 `/my-plugin:fancy`
플러그인 루트 `SKILL.md`	프론트매터 `name`(플러그인 디렉토리 이름이 폴백)	`my-plugin/SKILL.md`에서 `name: review` → `/my-plugin:review`. 경로 동작 규칙을 참조하세요.

플러그인 스킬에서 프론트매터 name은 명령의 마지막 세그먼트에서 디렉토리 이름을 대체하므로 my-plugin/skills/review/SKILL.md에서 name: fancy는 /my-plugin:fancy가 됩니다. 다른 명령이 이미 해당 이름을 사용하지 않으면 /fancy도 스킬을 호출합니다. 작성한 name이 이미 플러그인 자체의 접두사로 시작하면 v2.1.246 이상에서 Claude Code는 접두사를 다시 추가하지 않습니다. 예를 들어 name: my-plugin:fancy는 여전히 /my-plugin:fancy가 됩니다. v2.1.216부터 v2.1.245까지 Claude Code는 name이 이미 접두사를 가지고 있을 때 접두사를 두 배로 했습니다.

비대화형 세션에서 help 및 feedback 이름은 터미널 전용 기본 제공 명령에 대해 예약되지 않으므로 이러한 이름을 가진 플러그인 스킬은 베어 명령을 유지합니다. /login과 같은 다른 모든 터미널 전용 기본 제공은 해당 명령이 이러한 세션에서 실행될 수 없더라도 예약된 상태로 유지됩니다. help 또는 feedback이라는 이름의 동기화된 스킬은 여전히 건너뛰어집니다. Claude Code가 동기화된 스킬을 건너뜁니다. 해당 이름이 다른 기본 제공 명령과 일치하는 경우 해당 명령이 실행될 수 있는지 여부와 관계없이.

플러그인 루트 SKILL.md의 경우 스킬 디렉토리가 없으므로 name이 전체 마지막 세그먼트를 제공합니다. name 필드가 없으면 Claude Code는 플러그인의 디렉토리 이름으로 폴백합니다.

사용 가능한 문자열 치환

스킬은 스킬 콘텐츠의 동적 값에 대한 문자열 치환을 지원합니다.

변수	설명
`$ARGUMENTS`	스킬을 호출할 때 전달된 모든 인수입니다. 플레이스홀더가 인수를 받지 않으면 Claude Code는 `ARGUMENTS: <value>`를 스킬 콘텐츠 끝에 추가합니다. 스킬에 인수 전달을 참조하세요.
`$ARGUMENTS[N]`	`$ARGUMENTS[0]`(첫 번째 인수)과 같이 0 기반 인덱스로 특정 인수에 액세스합니다.
`$N`	`$0`(첫 번째 인수) 또는 `$1`(두 번째 인수)과 같이 `$ARGUMENTS[N]`의 약자입니다.
`$name`	`arguments` 프론트매터 목록에 선언된 명명된 인수입니다. 이름은 순서대로 위치에 매핑되므로 `arguments: [issue, branch]`를 사용하면 플레이스홀더 `$issue`는 첫 번째 인수로 확장되고 `$branch`는 두 번째 인수로 확장됩니다.
`${CLAUDE_SESSION_ID}`	현재 세션 ID입니다. 로깅, 세션별 파일 생성 또는 스킬 출력을 세션과 연관시키는 데 유용합니다.
`${CLAUDE_EFFORT}`	현재 노력 수준: `low`, `medium`, `high`, `xhigh`, 또는 `max`. Ultracode는 별개의 수준이 아니며 `xhigh`로 보고됩니다. 이를 사용하여 활성 노력 설정에 스킬 지침을 조정합니다.
`${CLAUDE_SKILL_DIR}`	스킬의 `SKILL.md` 파일을 포함하는 디렉토리입니다. 플러그인 스킬의 경우 플러그인 루트가 아닌 플러그인 내 스킬의 서브디렉토리입니다. 현재 작업 디렉토리와 관계없이 스킬과 함께 번들된 스크립트 또는 파일을 참조하려면 bash 주입 명령에서 사용합니다.
`${CLAUDE_PROJECT_DIR}`	프로젝트 루트 디렉토리입니다. 이는 훅 및 MCP 서버가 `CLAUDE_PROJECT_DIR`로 받는 동일한 경로입니다. 스킬이 설치된 위치와 관계없이 프로젝트 로컬 스크립트 또는 파일(예: `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`)을 참조하려면 사용합니다.
`${CLAUDE_PLUGIN_ROOT}`	플러그인의 설치 디렉토리입니다. 플러그인 스킬에서만 치환됩니다. 플러그인의 스킬 간에 공유되는 리소스를 포함하여 플러그인의 어디에나 번들된 스크립트 또는 파일을 참조하려면 사용합니다. 플러그인 환경 변수를 참조하세요.
`${CLAUDE_PLUGIN_DATA}`	플러그인의 지속적인 데이터 디렉토리로, 플러그인 업데이트를 통해 유지됩니다. 플러그인 스킬에서만 치환됩니다. 설치된 종속성, 생성된 파일 또는 업데이트를 초과해야 하는 캐시를 참조하려면 사용합니다.

Claude Code는 ${CLAUDE_SKILL_DIR} 및 ${CLAUDE_PROJECT_DIR}을 두 위치에서 치환합니다. 스킬의 마크다운 콘텐츠 및 allowed-tools 프론트매터의 Bash 규칙입니다. 플러그인 스킬에서 Claude Code는 ${CLAUDE_PLUGIN_ROOT} 및 ${CLAUDE_PLUGIN_DATA}를 동일한 두 위치에서 치환합니다. 두 위치에서 동일한 변수를 사용하면 스킬이 권한 프롬프트 없이 번들된 스크립트를 실행할 수 있습니다. 다음 스킬은 패턴을 보여줍니다.

---
name: render-chart
description: Render a chart from a CSV file
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

이 스킬이 ~/.claude/skills/render-chart/에 설치되면 ${CLAUDE_SKILL_DIR}의 두 발생 모두 해당 디렉토리로 확장됩니다. allowed-tools 규칙은 스킬 본문이 Claude에게 실행하도록 지시하는 정확한 명령과 일치하므로 스크립트는 프롬프트 없이 실행됩니다.

${CLAUDE_PROJECT_DIR} 치환에는 Claude Code v2.1.196 이상이 필요합니다.

인덱싱된 인수는 셸 스타일 인용을 사용하므로 다중 단어 값을 따옴표로 감싸서 단일 인수로 전달합니다. 예를 들어 /my-skill "hello world" second는 $0을 hello world로 확장하고 $1을 second로 확장합니다. $ARGUMENTS 플레이스홀더는 항상 입력한 대로 전체 인수 문자열로 확장됩니다.

해당 인수가 없는 인덱싱된 플레이스홀더(예: 하나의 인수만 전달되었을 때 $2)는 콘텐츠에서 변경되지 않은 상태로 유지됩니다. arguments 프론트매터의 일치하는 인수가 없는 명명된 플레이스홀더는 빈 문자열로 확장됩니다.

$1 또는 $ARGUMENTS와 같은 텍스트를 포함하는 인수 값을 전달하면 Claude Code는 이를 리터럴 텍스트로 삽입하고 확장하지 않습니다. 예를 들어 스킬의 본문에 Summarize $0이 포함되어 있고 /summarize "$ARGUMENTS from yesterday"를 실행하면 Claude는 Summarize $ARGUMENTS from yesterday를 받습니다. Claude Code는 여전히 인수를 삽입한 후 ${CLAUDE_SKILL_DIR}과 같은 ${CLAUDE_*} 변수를 대체합니다.

산문에서 $1.00과 같이 숫자, ARGUMENTS 또는 선언된 인수 이름 앞에 리터럴 $를 포함하려면 백슬래시로 이스케이프합니다. \$1.00. 다른 $ 앞의 백슬래시는 변경되지 않은 상태로 유지됩니다. 토큰 바로 앞의 단일 백슬래시만 이스케이프합니다. \\$1과 같은 이중 백슬래시는 두 백슬래시를 제자리에 두고 $1은 여전히 인수 값으로 확장됩니다. 백슬래시 이스케이프는 이러한 인수 플레이스홀더만 다룹니다. 백슬래시는 변수가 적용되는 ${CLAUDE_*} 변수의 치환을 방지하지 않습니다.

치환을 사용한 예제:

---
name: session-logger
description: Log activity for this session
---

Log the following to logs/${CLAUDE_SESSION_ID}.log:

$ARGUMENTS

지원 파일 추가

스킬은 디렉토리에 여러 파일을 포함할 수 있습니다. 이렇게 하면 SKILL.md가 필수 사항에 집중하면서 Claude가 필요할 때만 상세 참고 자료에 액세스할 수 있습니다. 큰 참고 문서, API 사양 또는 예제 컬렉션은 스킬이 실행될 때마다 컨텍스트에 로드될 필요가 없습니다.

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

SKILL.md에서 지원 파일을 참조하여 Claude가 각 파일의 내용과 로드 시기를 알 수 있도록 합니다.

## Additional resources

- For complete API details, see [reference.md](/anthropic/claude-code/history/docs/ko/2026-09-08-2000..2026-09-09-2258/reference/)
- For usage examples, see [examples.md](/anthropic/claude-code/history/docs/ko/2026-09-08-2000..2026-09-09-2258/examples/)

스킬을 호출할 수 있는 사람 제어

기본적으로 사용자와 Claude 모두 모든 스킬을 호출할 수 있습니다. /skill-name을 입력하여 직접 호출할 수 있고 Claude는 대화와 관련이 있을 때 자동으로 로드할 수 있습니다. 두 개의 프론트매터 필드를 사용하여 이를 제한할 수 있습니다.

disable-model-invocation: true: 사용자만 스킬을 호출할 수 있습니다. /commit, /deploy 또는 /send-slack-message와 같이 부작용이 있거나 타이밍을 제어하려는 워크플로우에 사용합니다. Claude가 코드가 준비된 것처럼 보이기 때문에 배포하기로 결정하지 않기를 원합니다.
user-invocable: false: Claude만 스킬을 호출할 수 있습니다. 명령으로 실행할 수 없는 배경 지식에 사용합니다. legacy-system-context 스킬은 이전 시스템이 어떻게 작동하는지 설명합니다. Claude는 관련이 있을 때 이를 알아야 하지만 /legacy-system-context는 사용자가 취할 의미 있는 작업이 아닙니다.

이 예제는 사용자만 트리거할 수 있는 배포 스킬을 만듭니다. disable-model-invocation: true를 설정하면 Claude는 스킬을 자동으로 실행할 수 없습니다.

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

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

Claude가 어쨌든 시도하면 Claude Code는 호출을 차단하고 배포 단계를 다른 방식으로 재현하지 않도록 지시하므로 Claude가 /deploy를 직접 실행하도록 제안할 것으로 예상합니다.

두 필드가 호출 및 컨텍스트 로딩에 어떻게 영향을 미치는지는 다음과 같습니다.

프론트매터	사용자가 호출할 수 있음	Claude가 호출할 수 있음	컨텍스트에 로드되는 시기
(기본값)	예	예	설명은 항상 컨텍스트에 있고, 호출될 때 전체 스킬이 로드됨
`disable-model-invocation: true`	예	아니요	설명은 컨텍스트에 없고, 사용자가 호출할 때 전체 스킬이 로드됨
`user-invocable: false`	아니요	예	설명은 항상 컨텍스트에 있고, 호출될 때 전체 스킬이 로드됨

스킬 콘텐츠 수명 주기

사용자 또는 Claude가 스킬을 호출하면 렌더링된 SKILL.md 콘텐츠가 대화에 단일 메시지로 들어가고 이후 턴에 걸쳐 유지됩니다. 이 지속성은 스킬의 지침에 적용되며 권한에는 적용되지 않습니다. allowed-tools 권한은 다음 메시지를 보낼 때 해제됩니다. Claude Code는 이후 턴에서 스킬 파일을 다시 읽지 않으므로 작업 전체에 적용되어야 하는 지침을 일회성 단계가 아닌 상시 지침으로 작성합니다.

Claude가 렌더링된 콘텐츠가 이미 컨텍스트에 있는 복사본과 동일한 스킬을 다시 호출할 때 Claude Code는 스킬이 이미 로드되었다는 짧은 메모를 추가합니다. 인수가 변경되었거나 동적 컨텍스트 명령이 새 출력을 생성했기 때문에 렌더링된 콘텐츠가 다를 때 Claude Code는 전체 콘텐츠를 다시 추가합니다.

자동 압축은 토큰 예산 내에서 호출된 스킬을 전달합니다. 대화가 컨텍스트를 확보하기 위해 요약될 때 Claude Code는 각 스킬의 처음 5,000토큰을 유지하면서 가장 최근의 각 스킬 호출을 다시 첨부합니다. 다시 첨부된 스킬은 25,000토큰의 결합 예산을 공유합니다. Claude Code는 가장 최근에 호출된 스킬부터 시작하여 이 예산을 채우므로 한 세션에서 많은 스킬을 호출한 경우 압축 후 이전 스킬이 완전히 삭제될 수 있습니다.

스킬이 첫 번째 응답 후 동작에 영향을 미치지 않는 것처럼 보이면 콘텐츠는 일반적으로 여전히 존재하며 모델이 다른 도구나 접근 방식을 선택하고 있습니다. 스킬의 description 및 지침을 강화하여 모델이 계속 선호하도록 하거나 훅을 사용하여 동작을 결정론적으로 적용합니다. 스킬이 크거나 그 후에 다른 스킬을 많이 호출한 경우 압축 후 다시 호출하여 전체 콘텐츠를 복원합니다.

스킬에 대한 도구 사전 승인

allowed-tools 필드는 스킬을 호출하는 턴 중에 나열된 도구에 대한 권한을 부여하므로 Claude는 승인을 요청하지 않고 사용할 수 있습니다. 다음 메시지를 보낼 때 권한이 해제되지만 스킬 콘텐츠는 컨텍스트에 유지됩니다. 스킬을 다시 호출하면 해당 턴에 대해 다시 적용됩니다. 이는 사용 가능한 도구를 제한하지 않습니다. 모든 도구는 호출 가능하며 권한 설정은 나열되지 않은 도구를 계속 관리합니다. 단일 턴이 아닌 전체 세션에 대해 도구를 사전 승인하려면 대신 해당 권한 설정에 허용 규칙을 추가합니다.

작업 공간 신뢰는 이 필드를 제어하지 않습니다. Claude Code는 프로젝트 스킬의 allowed-tools를 사용자 또는 Claude가 스킬을 호출할 때마다 적용합니다. 이는 신뢰한 적이 없는 폴더에서 -p 실행을 포함합니다. 스킬은 자신에게 광범위한 도구 액세스를 부여할 수 있으므로 리포지토리에 체크인된 스킬의 allowed-tools를 Claude Code를 실행하기 전에 검토합니다.

이 스킬을 호출할 때마다 Claude가 승인을 요청하지 않고 git 명령을 실행할 수 있습니다.

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

스킬이 활성화되는 동안 Claude의 사용 가능한 도구 풀에서 도구를 제거하려면 스킬의 프론트매터에서 disallowed-tools에 나열합니다. 다음 메시지를 보낼 때 제한이 해제됩니다. 거부 규칙과 마찬가지로 다른 도구가 남아 있는 동안 이 필드는 EndConversation을 제거할 수 없습니다. 모든 스킬 및 프롬프트에서 도구를 차단하려면 권한 설정에 거부 규칙을 추가합니다.

스킬에 인수 전달

사용자와 Claude 모두 스킬을 호출할 때 인수를 전달할 수 있습니다. 인수는 $ARGUMENTS 플레이스홀더를 통해 사용 가능합니다.

이 스킬은 번호로 GitHub 문제를 수정합니다. $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..."를 받습니다.

스킬의 콘텐츠에서 플레이스홀더가 인수를 받지 않으면 Claude Code는 ARGUMENTS: <your input>을 스킬 콘텐츠 끝에 추가하므로 Claude는 여전히 입력한 내용을 봅니다. 플레이스홀더는 $ARGUMENTS, $1과 같은 인덱싱된 형식 또는 명명된 인수입니다. 위치에 인수가 없는 인덱싱된 플레이스홀더는 리터럴 텍스트로 유지되며 하나를 받는 것으로 계산되지 않습니다. 명명된 플레이스홀더는 위치에 인수가 없어도 계산됩니다. 빈 문자열로 확장되기 때문입니다.

한 메시지의 시작 부분에 여러 스킬을 스택할 수도 있습니다. /write-tests /fix-issue 123을 입력하면 두 스킬이 모두 로드되고 후행 텍스트 123이 각각에 $ARGUMENTS로 전달됩니다. v2.1.199 이전에는 첫 번째 스킬만 로드되고 /fix-issue 123을 리터럴 인수 텍스트로 받았습니다.

Claude Code는 첫 번째 스킬과 그 뒤에 스택된 최대 5개를 확장합니다. 확장은 인라인 사용자 호출 가능 스킬이 아닌 첫 번째 토큰에서 중지되므로 포크된 서브에이전트로 실행되는 스킬(예: /code-review) 또는 인수 자체가 슬래시 명령으로 시작할 수 있는 스킬(예: /loop)도 거기서 끝납니다. 해당 토큰 및 그 뒤의 모든 것이 확장된 모든 스킬의 인수 텍스트가 됩니다. v2.1.218부터 /code-review는 포크된 서브에이전트로 실행됩니다. 이전 버전에서는 인라인으로 실행되고 스택되었습니다.

위치별로 개별 인수에 액세스하려면 $ARGUMENTS[N] 또는 더 짧은 $N을 사용합니다.

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

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

/migrate-component SearchBar JavaScript TypeScript를 실행하면 $ARGUMENTS[0]을 SearchBar로, $ARGUMENTS[1]을 JavaScript로, $ARGUMENTS[2]를 TypeScript로 대체합니다. $N 약자를 사용하는 동일한 스킬:

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

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

고급 패턴

동적 컨텍스트 주입

!`<command>` 구문은 스킬 콘텐츠가 Claude에 전송되기 전에 셸 명령을 실행합니다. 명령 출력이 플레이스홀더를 대체하므로 Claude는 명령 자체가 아닌 실제 데이터를 받습니다. Claude Code는 스킬이 claude.ai 계정에서 동기화될 때 이러한 명령을 머신에서 실행하지 않습니다.

이 스킬은 GitHub CLI를 사용하여 라이브 PR 데이터를 가져와 풀 요청을 요약합니다. !`gh pr diff` 및 기타 명령이 먼저 실행되고 해당 출력이 프롬프트에 삽입됩니다:

---
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>` 플레이스홀더에 대해 다시 스캔되지 않으므로 명령은 나중의 패스를 위해 플레이스홀더를 내보낼 수 없습니다.

인라인 형식은 !이 줄의 시작 또는 공백 직후에 나타날 때만 인식됩니다. !이 KEY=!`cmd`처럼 다른 문자 뒤에 오면 플레이스홀더는 리터럴 텍스트로 남고 명령은 실행되지 않습니다.

여러 줄 명령의 경우 인라인 형식 대신 ```!로 열린 펜스 코드 블록을 사용합니다:

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

사용자, 프로젝트, 플러그인 또는 additional-directory 소스의 스킬 및 사용자 정의 명령에 대해 이 동작을 비활성화하려면 settings에서 "disableSkillShellExecution": true를 설정합니다. 각 명령은 실행되는 대신 [shell command execution disabled by policy]로 대체됩니다. 번들된 스킬과 관리되는 스킬은 영향을 받지 않습니다. 이 설정은 사용자가 재정의할 수 없는 managed settings에서 가장 유용합니다.

Claude Code는 claude.ai 계정에서 동기화된 스킬에 나타나는 이러한 명령을 머신에서 절대 실행하지 않습니다. 이 설정과 관계없이 Claude Code가 동기화된 스킬의 본문을 처리하는 방법은 각 종류의 세션에서 Claude가 명령 대신 받는 것을 설명합니다.

주입된 명령이 실행되는 방식

Claude Code는 스킬의 프론트매터에 있는 shell 키와 사용자 환경에서 스킬의 주입된 명령을 실행할 도구를 선택합니다. 모든 조합은 Bash 도구 또는 PowerShell 도구를 통해 명령을 실행하며, 호출을 완전히 실패하게 하는 하나의 조합을 제외합니다:

shell: powershell, PowerShell 도구가 활성화된 경우: 명령은 PowerShell 도구를 통해 실행됩니다.
shell: bash (bash를 사용할 수 없는 경우): 명령이 실행되기 전에 호출이 실패합니다. 이는 Git Bash가 없는 Windows에서 발생합니다. Claude Code는 Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found를 표시합니다.
기타 모든 조합: bash를 사용할 수 있을 때 명령은 Bash 도구를 통해 실행됩니다. 사용할 수 없을 때는 PowerShell 도구를 통해 실행됩니다.

두 도구 모두 Claude의 자체 셸 명령을 실행하는 것과 동일한 방식으로 명령을 실행합니다. 이들은 작업 디렉토리, 타임아웃 및 출력 처리를 공유합니다:

작업 디렉토리: Claude Code는 각 명령을 세션 셸의 현재 작업 디렉토리에서 실행합니다. Claude가 cd를 실행할 때 해당 디렉토리가 이동합니다. 매번 동일하게 확인되어야 하는 경로에서 ${CLAUDE_SKILL_DIR} 또는 ${CLAUDE_PROJECT_DIR}을 사용합니다.
stderr: 기본 bash 셸을 사용하면 Claude Code는 stderr를 stdout으로 병합합니다. 명령이 stderr에 쓰는 모든 것이 주입된 텍스트에 나타납니다.
타임아웃: 각 명령은 Bash 도구의 기본 2분 타임아웃 아래에서 실행됩니다. Bash 도구가 시간 초과된 명령을 백그라운드로 이동할 때 스킬은 여전히 렌더링됩니다. 주입된 텍스트는 이동을 보고하고 백그라운드 작업과 명령의 출력을 수집하는 파일의 이름을 지정합니다. 명령이 Bash 도구가 절대 자동으로 백그라운드하지 않는 명령인 경우 Claude Code는 타임아웃에서 이를 종료합니다. 이 실패는 호출을 중단합니다.
출력 크기: Bash 도구의 인라인 상한을 초과하는 출력은 잘린 텍스트가 아닌 파일 경로와 짧은 미리보기로 도착합니다. 출력 제한은 상한과 각 경계를 조정하는 방법을 다룹니다.

PowerShell 도구는 실행하는 명령에 동일한 타임아웃, 백그라운드 처리 및 출력 상한 동작을 적용합니다. 해당 세부 사항은 PowerShell 도구 섹션을 참조합니다.

주입된 명령이 실패할 때

실패한 명령은 자신의 플레이스홀더뿐만 아니라 전체 스킬 호출을 중단합니다. Claude는 해당 호출에 대한 스킬 콘텐츠를 절대 보지 않습니다. 중단은 Shell command failed for pattern "..."를 표시합니다. 오류 메시지는 [stderr] 아래의 명령 출력을 포함합니다.

기본 bash 셸을 사용하면 0이 아닌 종료 코드는 실패로 계산됩니다. 하나의 예외가 적용됩니다: Claude Code는 검색 및 비교 명령에서 종료 코드 1을 정상 결과로 취급하고 해당 출력을 주입합니다. 종료 코드 2 이상은 이러한 명령에 대해서도 실패합니다.

어떤 명령이 예외를 받는지는 셸에 따라 다릅니다:

기본 bash 셸: 출력 제한 아래에 나열된 명령
shell: powershell, PowerShell 도구가 활성화된 경우: grep 및 git diff를 포함하지만 find 또는 diff는 포함하지 않는 다른 집합

기본 bash 셸을 사용하면 0이 아닌 종료를 예상하는 다른 명령에 || true를 추가합니다. 문제를 찾을 때 1을 종료하는 검사 스크립트가 한 예입니다.

주입된 명령은 절대 권한을 요청하지 않습니다. 명령의 권한 확인이 허용 이외의 것을 반환하면 Claude Code는 호출을 중단합니다. 여기에는 일반적으로 요청할 규칙이 포함됩니다. 중단은 Shell command permission check failed for pattern "..."를 표시합니다.

일치하지 않는 명령이 여기서 중단되지 않도록 하려면 allowed-tools로 미리 승인합니다. 일치하는 요청 또는 거부 규칙은 allowed-tools와 관계없이 호출을 중단합니다. 권한 관리를 참조합니다.

서브에이전트에서 스킬 실행

스킬을 격리된 상태에서 실행하려면 프론트매터에 context: fork를 추가합니다. 스킬 콘텐츠는 서브에이전트를 구동하는 프롬프트가 됩니다. 대화 기록에 액세스할 수 없습니다.

포크된 서브에이전트는 백그라운드에서 실행됩니다: 실행되는 동안 계속 작업하고 완료되면 결과가 대화에 도착합니다. 프론트매터에서 background: false를 설정하여 대신 스킬을 호출한 턴에서 결과를 기다립니다. v2.1.218 이전에는 포크된 스킬이 항상 완료될 때까지 턴을 차단했습니다.

Claude Code는 다음과 같은 경우에도 스킬이 background: false를 설정하지 않더라도 결과를 기다립니다:

-p 플래그 또는 Agent SDK를 사용한 비대화형 모드
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS를 1로 설정할 때 (모든 다른 백그라운드 작업 기능도 끕니다)
동일한 스킬의 이전 호출이 여전히 실행 중인 동안 포크된 스킬을 호출할 때
예약된 작업이 스킬을 프롬프트로 하여 실행될 때

백그라운드에서 실행되는 포크는 백그라운드 서브에이전트에 적용되는 더 좁은 도구 집합으로도 실행됩니다: 스킬의 서브에이전트는 일반 에이전트 유형이므로 대화를 포크하는 서브에이전트에 대한 예외는 적용되지 않습니다. 스킬의 단계가 해당 집합 외부의 도구에 따라 다르면 background: false를 설정하여 전체 도구 집합을 유지합니다.

백그라운드에서 실행되는 포크된 스킬은 세션의 체크포인트 외부에서 편집을 적용하므로 /rewind는 이를 실행 취소하지 않습니다. git을 사용하여 되돌립니다.

스킬과 서브에이전트는 두 방향으로 함께 작동합니다:

접근 방식	시스템 프롬프트	작업	또한 로드
`context: fork`가 있는 스킬	에이전트 유형에서	SKILL.md 콘텐츠	CLAUDE.md (에이전트가 Explore 또는 Plan인 경우 제외)
`skills` 필드가 있는 서브에이전트	서브에이전트의 마크다운 본문	Claude의 위임 메시지	사전 로드된 스킬 + CLAUDE.md

context: fork를 사용하면 스킬에 작업을 작성하고 에이전트 유형을 선택하여 실행합니다. 기본 제공 Explore 및 Plan 에이전트는 CLAUDE.md 및 git 상태를 건너뜁니다 컨텍스트를 작게 유지하므로 agent: Explore를 사용하는 포크된 스킬은 SKILL.md 콘텐츠와 에이전트의 자체 시스템 프롬프트만 봅니다. 역으로 스킬을 참조 자료로 사용하는 사용자 정의 서브에이전트를 정의하려면 서브에이전트를 참조합니다.

예: Explore 에이전트를 사용하는 연구 스킬

이 스킬은 포크된 Explore 에이전트에서 연구를 실행합니다. 스킬 콘텐츠는 작업이 되고 에이전트는 코드베이스 탐색에 최적화된 읽기 전용 도구를 제공합니다:

---
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

이 스킬이 실행될 때:

새로운 격리된 컨텍스트가 생성됩니다
서브에이전트는 스킬 콘텐츠를 프롬프트로 받습니다 ("Research $ARGUMENTS thoroughly...")
agent 필드는 실행 환경 (모델, 도구 및 권한)을 결정합니다
서브에이전트는 결과를 요약하고 완료되면 주 대화에 반환합니다

agent 필드는 사용할 서브에이전트 구성을 지정합니다. 옵션에는 기본 제공 에이전트 (Explore, Plan, general-purpose) 또는 .claude/agents/의 모든 사용자 정의 서브에이전트가 포함됩니다. 생략하면 general-purpose를 사용합니다.

Claude의 스킬 액세스 제한

기본적으로 Claude는 disable-model-invocation: true가 설정되지 않은 모든 스킬을 호출할 수 있습니다. allowed-tools를 정의하는 스킬은 스킬을 호출하는 턴 동안 Claude에게 사용자별 승인 없이 해당 도구에 대한 액세스를 부여합니다. 승인은 다음 메시지를 보낼 때 지워집니다. 권한 설정은 여전히 다른 모든 도구에 대한 기본 승인 동작을 관리합니다. /init 및 /security-review를 포함한 몇 가지 기본 제공 명령도 스킬 도구를 통해 사용할 수 있습니다. /compact와 같은 다른 기본 제공 명령은 그렇지 않습니다.

Claude가 호출할 수 있는 스킬을 제어하는 세 가지 방법:

스킬 도구를 /permissions에서 거부하여 모든 스킬 비활성화:

# Add to deny rules:
Skill

권한 규칙을 사용하여 특정 스킬 허용 또는 거부:

# Allow only specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skills
Skill(deploy *)

권한 구문: 정확한 일치의 경우 Skill(name), 모든 인수를 사용한 접두사 일치의 경우 Skill(name *).

deny 규칙이 스킬의 자체 이름이 아닌 별칭 또는 정규화되지 않은 이름을 지정하면 Claude Code는 여전히 스킬을 차단합니다: Skill(review)를 사용하면 번들된 /code-review를 /review 별칭을 통해 차단하고, Skill(deploy)를 사용하면 중첩된 스킬을 apps/web:deploy로 나열된 정규화되지 않은 이름을 통해 차단합니다. v2.1.260 이전에는 Claude Code가 deny 규칙이 정규화되지 않은 이름만 지정할 때 정규화된 이름 아래에 나열된 중첩된 스킬을 차단하지 않았습니다.

Claude Code는 allow 규칙을 스킬의 자체 이름과 Claude의 호출에서의 이름에 대해서만 일치시킵니다.

프론트매터에 disable-model-invocation: true를 추가하여 개별 스킬 숨기기. 이는 Claude의 컨텍스트에서 스킬을 제거합니다.

설정에서 스킬 가시성 재정의

skillOverrides 설정은 스킬의 자체 프론트매터 대신 설정에서 스킬 가시성을 제어합니다. SKILL.md를 편집하고 싶지 않은 스킬 (예: 공유 프로젝트 리포지토리에 체크인된 스킬)에 사용합니다. /skills 메뉴는 사용자를 위해 작성합니다: 스킬을 강조하고 Space를 눌러 상태를 순환한 다음 Esc를 눌러 .claude/settings.local.json에 저장합니다.

각 키는 스킬 이름이고 각 값은 다음 네 가지 상태 중 하나입니다:

값	Claude에 나열됨	`/` 메뉴에서
`"on"`	이름 및 설명	예
`"name-only"`	이름만	예
`"user-invocable-only"`	숨김	예
`"off"`	숨김	숨김

/skills 메뉴는 "user-invocable-only" 상태를 user-only로 레이블합니다.

v2.1.199부터 "off"는 터미널 / 메뉴 외에도 Remote Control 클라이언트 및 Agent SDK 호출자에게 광고되는 명령 목록에서 스킬을 숨깁니다. 전체 이름으로 숨겨진 스킬을 호출하면 여전히 실행하는 대신 skillOverrides 오류를 반환합니다.

skillOverrides에 없는 스킬은 "on"으로 취급됩니다. 아래 예제는 한 스킬을 이름으로 축소하고 다른 스킬을 완전히 끕니다:

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

일부 번들된 스킬에는 /doctor에 대한 checkup과 같은 별칭이 있습니다. managed settings에서 또는 --settings 플래그로 전달하는 파일에서 별칭 아래에 skillOverrides 항목을 설정하면 Claude Code는 이를 별칭 뒤의 스킬에 적용합니다. 별칭을 통해 스킬을 더 제한할 수만 있으며 더 가시적으로 만들 수는 없으며, managed settings에서 스킬의 자체 이름 아래에도 항목을 설정하면 해당 항목이 우선합니다. v2.1.260 이전에는 Claude Code가 모든 설정 소스의 스킬에 별칭 아래의 항목을 적용하지 않았습니다.

사용자, 프로젝트 및 로컬 설정에서 Claude Code는 스킬 이름에 대해서만 항목을 일치시킵니다. 거기서 review에 대한 항목을 설정하면 /review 별칭을 통해 번들된 /code-review가 아닌 review라는 스킬에 적용됩니다.

플러그인 스킬은 skillOverrides의 영향을 받지 않습니다. /plugin을 통해 이를 관리합니다.

사용하지 않는 스킬 찾기

스킬 목록의 모든 스킬은 Claude가 절대 사용하지 않더라도 모든 턴에서 컨텍스트에 추가됩니다. /skill-doctor를 실행하여 각 스킬의 비용과 사용 빈도를 확인하고 어떤 스킬을 끌지 결정합니다. 대화형 세션에서 보고서는 /plugin 관리자의 Stats 탭에서 열립니다. -p를 사용한 비대화형 모드에서 Claude Code는 이를 텍스트로 인쇄합니다.

보고서는 번들된 스킬 및 엔터프라이즈 스킬을 제외한 세션의 스킬을 다룹니다. 목록에서 절대 호출되지 않은 스킬에 플래그를 지정하고 끌 위치를 알려줍니다. 끌 위치를 알려주는 스킬 중에서 가장 높은 컨텍스트 비용을 가진 스킬부터 시작합니다. 보고서는 또한 최근에 사용하지 않은 플러그인을 나열합니다.

/skill-doctor는 Claude Code v2.1.252 이상이 필요하며 기능 플래그 가져오기를 건너뛰는 세션에서는 사용할 수 없습니다. Remote Control에서 휴대폰 또는 브라우저를 통해 /skill-doctor를 실행하면 Claude Code는 Skill usage reports are not available on this connection. 대신 회신합니다. 세션이 실행 중인 머신의 터미널에서 /skill-doctor를 실행합니다.

스킬 평가 및 반복

스킬이 트리거되는 것을 보는 것은 Claude가 스킬을 찾았다는 의미이지, 의도한 대로 작동했다는 의미는 아닙니다. 스킬이 제대로 작동하는지 알기 위해서는 두 가지를 별도로 측정해야 합니다. Claude가 해야 할 프롬프트에서 스킬을 호출하는지 여부와 호출할 때 출력이 예상과 일치하는지 여부입니다.

두 가지 모두에 대한 확인은 기준선 비교입니다. 현실적인 프롬프트 몇 개를 수집하고, 스킬을 사용할 수 있는 새로운 세션에서 각각을 실행한 후 비활성화된 상태에서 다시 실행하고 결과를 비교합니다. 새로운 세션이 중요한 이유는 스킬 작성 시 남겨진 컨텍스트가 작성된 지침의 간격을 숨길 수 있기 때문입니다.

skill-creator로 평가 실행

skill-creator 플러그인은 Claude Code 내에서 비교 루프를 자동화합니다. 공식 마켓플레이스에서 설치합니다:

/plugin install skill-creator@claude-plugins-official

설치가 실패하면 Claude Code가 보고한 메시지와 일치시킵니다:

Marketplace "claude-plugins-official" not found: /plugin marketplace add anthropics/claude-plugins-official로 마켓플레이스를 추가한 후 설치를 다시 시도합니다.
플러그인이 마켓플레이스에서 찾을 수 없음: 플러그인 이름을 확인합니다.

설치 요약에서 Run /reload-plugins to activate.를 보고하면 해당 명령을 실행하여 현재 세션에서 플러그인의 스킬을 사용할 수 있게 합니다. 그런 다음 Claude에게 기존 스킬을 평가하도록 요청합니다. 예를 들어 evaluate my summarize-changes skill with skill-creator입니다. 플러그인은 테스트 케이스 작성을 안내하고 루프를 실행합니다:

테스트 케이스: 프롬프트, 입력 파일 및 예상 동작을 스킬 디렉토리 내 evals/evals.json에 저장합니다
격리된 실행: 각 테스트 케이스마다 서브에이전트를 생성하여 각 실행이 깨끗한 컨텍스트로 시작되도록 하고, 토큰 수와 지속 시간을 기록합니다
채점: 각 어설션을 출력과 비교하고 grading.json에 증거와 함께 통과 또는 실패를 작성합니다
벤치마크: 스킬 사용 여부에 따른 통과율, 시간 및 토큰을 benchmark.json에 집계하여 토큰 및 시간 오버헤드에 대한 통과율 개선을 비교할 수 있습니다
버전 비교: 스킬의 두 버전 간에 블라인드 A/B를 실행하여 편집이 커밋하기 전에 개선 사항인지 확인할 수 있습니다
설명 튜닝: 트리거해야 하는 프롬프트와 트리거하지 않아야 하는 프롬프트를 생성하고, 히트율을 측정하고, 스킬이 잘못된 요청에서 활성화될 때 설명 편집을 제안합니다
검토 뷰어: 각 출력을 검사하고 다음 반복이 읽을 정성적 피드백을 기록할 수 있는 HTML 보고서를 엽니다

평가 파일 형식 및 전체 반복 워크플로우는 agentskills.io의 스킬 출력 품질 평가를 참조합니다. 벤치마크 및 비교 모드의 배경은 skill-creator 공지를 참조합니다.

스킬은 대상에 따라 다양한 범위에서 배포할 수 있습니다:

프로젝트 스킬: .claude/skills/를 버전 관리에 커밋합니다
플러그인: 플러그인에서 skills/ 디렉토리를 생성합니다
관리형: 관리형 설정을 통해 조직 전체에 배포합니다

시각적 출력 생성

스킬은 모든 언어의 스크립트를 번들로 제공하고 실행할 수 있으므로 Claude에 단일 프롬프트로는 불가능한 기능을 제공합니다. 한 가지 패턴은 시각적 출력을 생성하는 것입니다: 브라우저에서 열리는 대화형 HTML 파일로 데이터 탐색, 디버깅 또는 보고서 작성에 사용할 수 있습니다.

이 예제는 코드베이스 탐색기를 생성합니다: 디렉토리를 확장 및 축소할 수 있는 대화형 트리 뷰로, 파일 크기를 한눈에 볼 수 있고 색상으로 파일 유형을 식별할 수 있습니다.

스킬 디렉토리를 생성합니다:

mkdir -p ~/.claude/skills/codebase-visualizer/scripts

이를 ~/.claude/skills/codebase-visualizer/SKILL.md에 저장합니다. 설명은 Claude에게 이 스킬을 언제 활성화할지 알려주고, 지침은 Claude에게 번들된 스크립트를 실행하도록 지시합니다. 스크립트 경로는 ${CLAUDE_SKILL_DIR}를 사용하므로 스킬이 개인, 프로젝트 또는 플러그인 수준에서 설치되었는지 여부에 관계없이 올바르게 해석됩니다:

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python3 *)
---

# Codebase Visualizer

Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.

## Usage

Run the visualization script from your project root:

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
```

This creates `codebase-map.html` in the current directory and opens it in your default browser.

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

이를 ~/.claude/skills/codebase-visualizer/scripts/visualize.py에 저장합니다. 이 스크립트는 디렉토리 트리를 스캔하고 다음을 포함하는 자체 포함된 HTML 파일을 생성합니다:

파일 개수, 디렉토리 개수, 총 크기 및 파일 유형 수를 표시하는 요약 사이드바
파일 유형별로 코드베이스를 분석하는 막대 차트 (크기 기준 상위 8개)
디렉토리를 확장 및 축소할 수 있는 축소 가능한 트리로, 색상으로 구분된 파일 유형 표시기가 있습니다

스크립트는 Python 3이 필요하지만 기본 제공 라이브러리만 사용하므로 설치할 패키지가 없습니다:

#!/usr/bin/env python3
"""Generate an interactive collapsible tree visualization of a codebase."""

import json
import sys
import webbrowser
from html import escape
from pathlib import Path
from collections import Counter

IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'}

def scan(path: Path, stats: dict) -> dict:
    result = {"name": path.name, "children": [], "size": 0}
    try:
        for item in sorted(path.iterdir()):
            if item.name in IGNORE or item.name.startswith('.'):
                continue
            if item.is_file():
                size = item.stat().st_size
                ext = item.suffix.lower() or '(no ext)'
                result["children"].append({"name": item.name, "size": size, "ext": ext})
                result["size"] += size
                stats["files"] += 1
                stats["extensions"][ext] += 1
                stats["ext_sizes"][ext] += size
            elif item.is_dir():
                stats["dirs"] += 1
                child = scan(item, stats)
                if child["children"]:
                    result["children"].append(child)
                    result["size"] += child["size"]
    except PermissionError:
        pass
    return result

def generate_html(data: dict, stats: dict, output: Path) -> None:
    ext_sizes = stats["ext_sizes"]
    total_size = sum(ext_sizes.values()) or 1
    sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8]
    colors = {
        '.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8',
        '.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26',
        '.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e',
        '.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25',
    }
    lang_bars = "".join(
        f'<div class="bar-row"><span class="bar-label">{ext}</span>'
        f'<div class="bar" style="width:{(size/total_size)*100}%;background:{colors.get(ext,"#6b7280")}"></div>'
        f'<span class="bar-pct">{(size/total_size)*100:.1f}%</span></div>'
        for ext, size in sorted_exts
    )
    def fmt(b):
        if b < 1024: return f"{b} B"
        if b < 1048576: return f"{b/1024:.1f} KB"
        return f"{b/1048576:.1f} MB"

    html = f'''<!DOCTYPE html>
<html><head>
  <meta charset="utf-8"><title>Codebase Explorer</title>
  <style>
    body {{ font: 14px/1.5 system-ui, sans-serif; margin: 0; background: #1a1a2e; color: #eee; }}
    .container {{ display: flex; height: 100vh; }}
    .sidebar {{ width: 280px; background: #252542; padding: 20px; border-right: 1px solid #3d3d5c; overflow-y: auto; flex-shrink: 0; }}
    .main {{ flex: 1; padding: 20px; overflow-y: auto; }}
    h1 {{ margin: 0 0 10px 0; font-size: 18px; }}
    h2 {{ margin: 20px 0 10px 0; font-size: 14px; color: #888; text-transform: uppercase; }}
    .stat {{ display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #3d3d5c; }}
    .stat-value {{ font-weight: bold; }}
    .bar-row {{ display: flex; align-items: center; margin: 6px 0; }}
    .bar-label {{ width: 55px; font-size: 12px; color: #aaa; }}
    .bar {{ height: 18px; border-radius: 3px; }}
    .bar-pct {{ margin-left: 8px; font-size: 12px; color: #666; }}
    .tree {{ list-style: none; padding-left: 20px; }}
    details {{ cursor: pointer; }}
    summary {{ padding: 4px 8px; border-radius: 4px; }}
    summary:hover {{ background: #2d2d44; }}
    .folder {{ color: #ffd700; }}
    .file {{ display: flex; align-items: center; padding: 4px 8px; border-radius: 4px; }}
    .file:hover {{ background: #2d2d44; }}
    .size {{ color: #888; margin-left: auto; font-size: 12px; }}
    .dot {{ width: 8px; height: 8px; border-radius: 50%; margin-right: 8px; }}
  </style>
</head><body>
  <div class="container">
    <div class="sidebar">
      <h1>📊 Summary</h1>
      <div class="stat"><span>Files</span><span class="stat-value">{stats["files"]:,}</span></div>
      <div class="stat"><span>Directories</span><span class="stat-value">{stats["dirs"]:,}</span></div>
      <div class="stat"><span>Total size</span><span class="stat-value">{fmt(data["size"])}</span></div>
      <div class="stat"><span>File types</span><span class="stat-value">{len(stats["extensions"])}</span></div>
      <h2>By file type</h2>
      {lang_bars}
    </div>
    <div class="main">
      <h1>📁 {escape(data["name"])}</h1>
      <ul class="tree" id="root"></ul>
    </div>
  </div>
</body></html>'''
    output.write_text(html)

if __name__ == '__main__':
    target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()
    stats = {"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()}
    data = scan(target, stats)
    out = Path('codebase-map.html')
    generate_html(data, stats, out)
    print(f'Generated {out.absolute()}')
    webbrowser.open(f'file://{out.absolute()}')

테스트하려면 Claude Code를 모든 프로젝트에서 열고 "Visualize this codebase."라고 요청합니다. Claude가 스크립트를 실행하면 생성된 파일의 경로(예: Generated /path/to/codebase-map.html)를 출력하고 브라우저에서 엽니다. 브라우저가 열리지 않는 헤드리스 환경에서 작업하는 경우 출력된 경로는 스크립트가 성공했음을 확인합니다.

이 패턴은 모든 시각적 출력에 적용됩니다: 종속성 그래프, 테스트 커버리지 보고서, API 문서 또는 데이터베이스 스키마 시각화입니다. 번들된 스크립트가 작업을 수행하는 동안 Claude는 오케스트레이션을 처리합니다.

문제 해결

스킬이 트리거되지 않음

Claude가 예상대로 스킬을 사용하지 않는 경우:

설명에 사용자가 자연스럽게 말할 만한 키워드가 포함되어 있는지 확인하세요
스킬이 What skills are available?에 나타나는지 확인하세요
설명과 더 가깝게 일치하도록 요청을 다시 표현해 보세요
스킬이 사용자 호출 가능한 경우 /skill-name으로 직접 호출하세요

frontmatter YAML이 잘못된 형식이면 Claude Code는 스킬 본문을 빈 메타데이터로 로드하므로 /skill-name은 여전히 작동하지만 Claude는 일치시킬 description이 없습니다. --debug로 실행하여 파싱 오류를 확인하세요.

frontmatter가 파싱되지 않는 SKILL.md 파일을 찾으려면 스킬 디렉토리에서 claude plugin validate를 실행하세요. 예를 들어 프로젝트 스킬의 경우 claude plugin validate .claude/skills 또는 개인 스킬의 경우 claude plugin validate ~/.claude/skills입니다. Claude Code v2.1.233 이상이 필요합니다.

스킬이 너무 자주 트리거됨

Claude가 원하지 않을 때 스킬을 사용하는 경우:

설명을 더 구체적으로 만드세요
수동 호출만 원하는 경우 disable-model-invocation: true를 추가하세요

스킬 설명이 잘려 있음

Claude Code는 스킬 이름과 설명 목록을 컨텍스트에 로드하여 Claude가 사용 가능한 항목을 알 수 있도록 합니다. 목록에는 항상 모든 스킬 이름이 포함되지만 스킬이 많으면 Claude Code는 목록의 문자 예산에 맞추기 위해 설명을 단축하므로 Claude가 요청과 일치시키는 데 필요한 키워드가 제거될 수 있습니다. 예산은 모델의 컨텍스트 윈도우의 1%로 조정됩니다. 목록이 초과되면 Claude Code는 가장 적게 호출하는 스킬부터 설명을 삭제하므로 가장 자주 사용하는 스킬이 전체 텍스트를 유지합니다.

목록의 컨텍스트 비용 추정치와 가장 큰 기여자를 보려면 /doctor를 실행하세요. 사용하지 않는 스킬을 찾으려면 /skill-doctor를 실행하세요. 목록이 예산을 초과하면 Claude Code는 --debug로 볼 수 있는 디버그 로그에 경고를 작성합니다.

/context의 Skills 행은 예산이 적용된 후 목록의 크기를 보고하므로 모델이 수신하는 것과 일치합니다. v2.1.196 이전에는 행이 모든 설명의 전체 텍스트를 계산했으며 구성된 예산보다 몇 배 더 큰 값을 표시할 수 있었습니다.

예산을 높이려면 skillListingBudgetFraction 설정(예: 0.02 = 2%) 또는 SLASH_COMMAND_TOOL_CHAR_BUDGET 환경 변수를 고정 문자 수로 설정하세요. 다른 스킬을 위해 예산을 확보하려면 skillOverrides에서 낮은 우선순위 항목을 "name-only"로 설정하여 설명 없이 나열되도록 하세요. 또한 소스에서 description 및 when_to_use 텍스트를 자르세요. 각 항목의 결합된 텍스트는 예산에 관계없이 1,536자로 제한되므로 주요 사용 사례를 먼저 배치하세요. 상한은 skillListingMaxDescChars로 구성할 수 있습니다.

구성 디버깅: skill이 나타나지 않거나 트리거되지 않는 이유 진단
Skill 출력 품질 평가: agentskills.io의 eval 파일 형식 및 반복 워크플로우
Skill 작성 모범 사례: Claude 제품 전체에 적용되는 작성 지침
Subagents: 특화된 에이전트에 작업 위임
플러그인: 다른 확장과 함께 skills 패키징 및 배포
Hooks: 도구 이벤트 주변 워크플로우 자동화
메모리: 지속적인 컨텍스트를 위한 CLAUDE.md 파일 관리
명령어: 기본 제공 명령어 및 번들 skills 참조
권한: 도구 및 skill 액세스 제어
Claude Tag skills: 리포지토리에 커밋된 프로젝트 skills는 해당 리포지토리가 Claude Tag 채널에서 사용될 때도 로드됩니다

skills.md +473 −257

4 4

5# Claude를 skills로 확장하기5# Claude를 skills로 확장하기

6 6

~~7> Claude Code에서 skills를 생성, 관리, 공유하여 Claude의 기능을 확장합니다. 사용자 정의 명령어와 번들 skills를 포함합니다.~~7> Claude Code에서 skills를 생성, 관리 및 공유하여 Claude의 기능을 확장합니다. 사용자 정의 명령어 및 번들 skills를 포함합니다.

8 8

9Skills는 Claude가 할 수 있는 작업을 확장합니다. `SKILL.md` 파일을 지침과 함께 생성하면 Claude가 이를 자신의 도구 모음에 추가합니다. Claude는 관련이 있을 때 skills를 사용하거나 `/skill-name`으로 직접 호출할 수 있습니다.9Skills는 Claude가 할 수 있는 작업을 확장합니다. `SKILL.md` 파일을 지침과 함께 생성하면 Claude가 이를 자신의 도구 모음에 추가합니다. Claude는 관련성이 있을 때 skills를 사용하거나, `/skill-name`으로 직접 호출할 수 있습니다.

10 10

11같은 지침, 체크리스트 또는 다단계 절차를 계속 채팅에 붙여넣거나, CLAUDE.md의 섹션이 사실이 아닌 절차로 성장했을 때 skill을 생성합니다. CLAUDE.md 콘텐츠와 달리, skill의 본문은 사용할 때만 로드되므로 긴 참조 자료는 필요할 때까지 거의 비용이 들지 않습니다.11동일한 지침, 체크리스트 또는 다단계 절차를 반복해서 채팅에 붙여넣거나, CLAUDE.md의 섹션이 사실이 아닌 절차로 성장했을 때 skill을 생성합니다. CLAUDE.md 콘텐츠와 달리, skill의 본문은 사용할 때만 로드되므로 긴 참고 자료는 필요할 때까지 거의 비용이 들지 않습니다.

12 12

13<Note>13<Note>

~~14 `/help` 및 `/compact`와 같은 기본 제공 명령어와 `/debug` 및 `/code-review`와 같은 번들 skills는 [명령어 참조](/docs/ko/commands)를 참조하세요.~~14 `/help` 및 `/compact`와 같은 기본 제공 명령어와 `/debug` 및 `/code-review`와 같은 번들 skills의 경우 [명령어 참조](/docs/ko/commands)를 참조하세요.

15 15

16 **사용자 정의 명령어가 skills로 병합되었습니다.** `.claude/commands/deploy.md`의 파일과 `.claude/skills/deploy/SKILL.md`의 skill은 모두 `/deploy`를 생성하고 동일하게 작동합니다. 기존 `.claude/commands/` 파일은 계속 작동합니다. Skills는 선택적 기능을 추가합니다: 지원 파일을 위한 디렉토리, [skill을 누가 호출하는지 제어](#control-who-invokes-a-skill)하기 위한 frontmatter, 그리고 Claude가 관련이 있을 때 자동으로 로드할 수 있는 기능입니다.16 **사용자 정의 명령어가 skills로 병합되었습니다.** `.claude/commands/deploy.md`의 파일과 `.claude/skills/deploy/SKILL.md`의 skill은 모두 `/deploy`를 생성하고 동일한 방식으로 작동합니다. 기존 `.claude/commands/` 파일은 계속 작동합니다. Skills는 선택적 기능을 추가합니다: 지원 파일을 위한 디렉토리, [사용자 또는 Claude가 호출하는지 제어](#control-who-invokes-a-skill)하기 위한 frontmatter, 그리고 Claude가 관련성이 있을 때 자동으로 로드할 수 있는 기능입니다.

17</Note>17</Note>

18 18

19Claude Code skills는 [Agent Skills](https://agentskills.io) 개방형 표준을 따르며, 이는 여러 AI 도구에서 작동합니다. Claude Code는 [호출 제어](#control-who-invokes-a-skill), [subagent 실행](#run-skills-in-a-subagent), [동적 컨텍스트 주입](#inject-dynamic-context)과 같은 추가 기능으로 표준을 확장합니다.19Claude Code skills는 여러 AI 도구에서 작동하는 [Agent Skills](https://agentskills.io) 개방형 표준을 따릅니다. Claude Code는 [호출 제어](#control-who-invokes-a-skill), [subagent 실행](#run-skills-in-a-subagent), [동적 컨텍스트 주입](#inject-dynamic-context)과 같은 추가 기능으로 표준을 확장합니다. [Claude Code 외부에서 skill frontmatter 사용](#using-skill-frontmatter-outside-claude-code)에서 어떤 frontmatter 필드가 표준의 일부이고 어떤 필드가 Claude Code 확장인지 확인하세요.

20 20

21<h2 id="bundled-skills">21<h2 id="bundled-skills">

~~22 번들 skills~~22 번들된 스킬

23</h2>23</h2>

24 24

25Claude Code에는 모든 세션에서 사용 가능한 번들 skills 세트가 포함되어 있으며, [`disableBundledSkills`](/docs/ko/settings#available-settings) 설정으로 비활성화하지 않는 한 `/doctor`, `/code-review`, `/batch`, `/debug`, `/loop`, `/claude-api`를 포함합니다. 고정 로직을 직접 실행하는 대부분의 기본 제공 명령어와 달리, 번들 skills는 프롬프트 기반입니다: Claude에 상세한 지시사항을 제공하고 도구를 사용하여 작업을 조율하도록 합니다. 다른 skill과 동일한 방식으로 호출합니다: `/` 다음에 skill 이름을 입력합니다.25Claude Code에는 `/doctor`, `/code-review`, `/batch`, `/debug`, `/loop`, `/claude-api` 등의 번들된 스킬 세트가 포함되어 있습니다. 번들된 스킬은 프롬프트 기반입니다. 즉, Claude에 상세한 지침을 제공하고 도구를 사용하여 작업을 조율하도록 합니다. 대부분의 기본 제공 명령어는 대신 고정된 로직을 직접 실행합니다.

26 26

27[`/doctor`](/docs/ko/commands#all-commands) 설정 점검은 Claude Code v2.1.205 이상에서 `disableBundledSkills`의 예외입니다: 설정이 켜져 있을 때도 입력 가능합니다. 이를 숨기려면 `DISABLE_DOCTOR_COMMAND` 환경 변수를 설정하거나 [`skillOverrides`](#override-skill-visibility-from-settings) 항목에서 `"doctor": "off"`를 설정합니다. v2.1.205 이전에는 `/doctor`가 번들 skill이 아닌 기본 제공 명령어였습니다.27번들된 스킬은 다른 스킬과 동일한 방식으로 호출합니다. `/` 다음에 스킬 이름을 입력하면 됩니다. Claude는 관련성이 있을 때 일부 번들된 스킬을 자동으로 호출합니다. `/verify`를 포함한 다른 스킬은 사용자가 호출할 때만 실행되므로, 이러한 더 오래 실행되는 검사가 시간과 토큰을 소비하는 시점을 제어할 수 있습니다.

28 28

~~29번들 skills는 [명령어 참조](/docs/ko/commands)에 나열되어 있으며, 목적 열에 **Skill**로 표시됩니다.~~29대부분의 번들된 스킬은 모든 세션에서 사용 가능합니다. 일부는 특정 기능에 따라 달라집니다. 예를 들어 `/workflow-authoring`은 [동적 워크플로우](/docs/ko/workflows)가 활성화된 경우에만 사용 가능합니다.

31번들된 스킬을 끄려면 [`disableBundledSkills`](/docs/ko/settings-reference#disablebundledskills) 설정을 사용하면 되며, 이는 `/doctor`를 제외한 모든 번들된 스킬을 비활성화합니다.

33<Note>

34 [`/doctor`](/docs/ko/commands#all-commands) 설정 점검은 Claude Code v2.1.205 이상에서 `disableBundledSkills`가 켜져 있을 때도 입력 가능합니다. 이를 숨기려면 `DISABLE_DOCTOR_COMMAND` 환경 변수를 설정하거나 [`skillOverrides`](#override-skill-visibility-from-settings) 항목을 `"doctor": "off"`로 설정하면 됩니다. v2.1.205 이전에는 `/doctor`가 번들된 스킬이 아닌 기본 제공 명령어였습니다.

35</Note>

37번들된 스킬은 [명령어 참조](/docs/ko/commands)에서 기본 제공 명령어와 함께 나열되며, 목적 열에 **Skill**로 표시됩니다.

30 38

31<h3 id="run-and-verify-your-app">39<h3 id="run-and-verify-your-app">

32 앱 실행 및 확인40 앱 실행 및 확인

33</h3>41</h3>

34 42

~~35세 가지 번들 skills는 함께 작동하여 앱을 시작하고 테스트만이 아닌 실행 중인 앱에 대해 변경 사항을 확인합니다:~~43세 가지 번들된 스킬이 함께 작동하여 앱을 시작하고 테스트만이 아닌 실행 중인 앱에 대해 변경 사항을 확인합니다.

45| 스킬 | 목적 |

46| :--------------------- | :--------------------------------------------------------- |

47| `/run` | 앱을 시작하고 실행하여 변경 사항이 작동하는지 확인 |

48| `/verify` | 앱을 빌드하고 실행하여 코드 변경이 의도한 대로 작동하는지 확인하며, 테스트나 타입 검사로 폴백하지 않음 |

49| `/run-skill-generator` | `/run`과 `/verify`에 프로젝트를 빌드하고 시작하는 방법을 학습시킴 |

36 50

~~37| Skill | 목적 |~~51`/run`과 `/verify`는 설정 없이 작동합니다. 프로젝트 유형(CLI, 서버, TUI, 브라우저 기반)과 README, `package.json` 또는 `Makefile`의 내용으로부터 시작을 추론합니다. 이 추론은 표준 시작 이상의 것이 필요한 프로젝트(데이터베이스, env 파일, 그래픽 세션, 다단계 빌드)에서는 신뢰할 수 없게 됩니다.

~~38| :--------------------- | :----------------------------------------------------------- |~~

~~39| `/run` | 앱을 시작하고 변경 사항이 작동하는지 확인하기 위해 앱을 실행합니다 |~~

~~40| `/verify` | 앱을 빌드하고 실행하여 코드 변경이 의도한 대로 작동하는지 확인하며, 테스트나 타입 체크로 돌아가지 않습니다 |~~

~~41| `/run-skill-generator` | `/run`과 `/verify`에 프로젝트를 빌드하고 시작하는 방법을 가르칩니다 |~~

42 52

~~43세 가지 skills 모두 Claude Code v2.1.145 이상이 필요합니다.~~53`/run-skill-generator`는 대신 레시피를 기록합니다. 깨끗한 환경에서 앱을 실행하고, 작동한 것(설치 명령어, env 변수, 시작 스크립트)을 캡처하고, 프로젝트별 스킬로 `.claude/skills/run-<name>/`에 커밋합니다. 그 후 `/run`, `/verify` 및 리포지토리의 다른 에이전트는 레시피를 다시 발견하는 대신 기록된 레시피를 따릅니다. 프로젝트당 한 번 `/run-skill-generator`를 실행하고, 빌드 또는 시작 프로세스가 변경되면 다시 실행합니다.

44 54

45`/run`과 `/verify`는 설정 없이 작동합니다. 프로젝트 유형(CLI, 서버, TUI, 브라우저 기반)과 README, `package.json` 또는 `Makefile`의 내용으로부터 시작을 추론합니다. 이 추론은 표준 시작 이상의 것이 필요한 프로젝트(데이터베이스, env 파일, 그래픽 세션, 다단계 빌드)에 대해서는 신뢰할 수 없게 됩니다.55`/verify`는 자체 레시피를 기록할 수도 있습니다. 기록된 레시피 없이 앱을 빌드하고 실행해야 할 때, 작동한 것을 리포지토리 루트의 `.claude/skills/verify/SKILL.md`에 또는 모노레포의 터치된 패키지 디렉토리에 작성하므로 나중의 실행과 다른 에이전트가 동일한 단계를 따릅니다. 리포지토리 루트에서 기록된 스킬은 번들된 `/verify`를 대체합니다. 이는 Claude Code v2.1.200 이상이 필요합니다.

46 56

47`/run-skill-generator`는 대신 레시피를 기록합니다. 깨끗한 환경에서 앱을 실행하고, 작동한 것(설치 명령어, env 변수, 시작 스크립트)을 캡처하고, 프로젝트별 skill로 `.claude/skills/run-<name>/`에 커밋합니다. 그 후 `/run`, `/verify` 및 리포지토리의 다른 모든 에이전트는 레시피를 다시 발견하는 대신 기록된 레시피를 따릅니다. 프로젝트당 한 번 `/run-skill-generator`를 실행하고, 빌드 또는 시작 프로세스가 변경되면 다시 실행합니다.57Claude는 실패한 명령어나 누락된 단계와 같이 실행을 잘못 조종한 경우에만 기록된 파일을 편집하므로 세션별 diff 없이 파일을 커밋할 수 있습니다. v2.1.205 이전에는 번들된 스킬이 Claude에 실행이 학습한 모든 것을 포함하도록 지시했으므로 빈번한 병합 충돌이 발생했습니다.

48 58

49<h2 id="getting-started">59<h2 id="getting-started">

50 시작하기60 시작하기

51</h2>61</h2>

52 62

53<h3 id="create-your-first-skill">63<h3 id="create-your-first-skill">

~~54 첫 번째 skill 생성~~64 첫 번째 skill 만들기

55</h3>65</h3>

56 66

57이 예제는 git 저장소의 커밋되지 않은 변경 사항을 요약하고 위험한 항목을 표시하는 skill을 생성합니다. 라이브 diff를 Claude가 읽기 전에 프롬프트로 가져오므로, 응답은 Claude가 열린 파일에서 추측할 수 있는 것이 아니라 실제 작업 트리에 기반합니다. Claude는 변경 사항에 대해 물어볼 때 자동으로 skill을 로드하거나 `/summarize-changes`로 직접 호출할 수 있습니다.67이 예제는 git 저장소의 커밋되지 않은 변경 사항을 요약하고 위험한 부분을 표시하는 skill을 만듭니다. 실시간 diff를 Claude가 읽기 전에 프롬프트로 가져오므로, 응답이 Claude가 열린 파일에서 추측할 수 있는 것이 아니라 실제 작업 트리에 기반합니다. Claude는 변경 사항에 대해 물어볼 때 자동으로 skill을 로드하거나, `/summarize-changes`로 직접 호출할 수 있습니다.

58 68

59<Steps>69<Steps>

~~60 <Step title="skill 디렉토리 생성">~~70 <Step title="skill 디렉토리 만들기">

~~61 개인 skills 폴더에 skill을 위한 디렉토리를 생성합니다. 개인 skills는 모든 프로젝트에서 사용 가능합니다.~~71 개인 skills 폴더에 skill용 디렉토리를 만듭니다. 개인 skills는 모든 프로젝트에서 사용할 수 있습니다.

62 72

63 ```bash theme={null}73 ```bash theme={null}

64 mkdir -p ~/.claude/skills/summarize-changes74 mkdir -p ~/.claude/skills/summarize-changes

66 </Step>76 </Step>

67 77

68 <Step title="SKILL.md 작성">78 <Step title="SKILL.md 작성">

69 모든 skill에는 두 부분이 있는 `SKILL.md` 파일이 필요합니다: Claude에게 skill을 언제 사용할지 알려주는 YAML frontmatter (`---` 마커 사이)와 skill이 실행될 때 Claude가 따르는 지침이 있는 markdown 콘텐츠입니다. 디렉토리 이름이 입력하는 명령어가 되고, `description`은 Claude가 자동으로 skill을 로드할 시기를 결정하는 데 도움이 됩니다.79 모든 skill에는 `SKILL.md` 파일이 필요합니다. 이 파일은 두 부분으로 구성됩니다: Claude에게 skill을 언제 사용할지 알려주는 `---` 마커 사이의 YAML frontmatter와 skill이 실행될 때 Claude가 따르는 지침이 포함된 markdown 콘텐츠입니다. 디렉토리 이름이 입력하는 명령어가 되고, `description`은 Claude가 skill을 자동으로 로드할지 결정하는 데 도움이 됩니다.

70 80

71 이를 `~/.claude/skills/summarize-changes/SKILL.md`에 저장합니다:81 이를 `~/.claude/skills/summarize-changes/SKILL.md`에 저장합니다:

72 82

84 Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.94 Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

85 ```95 ```

86 96

87 `` !`git diff HEAD` `` 줄은 [동적 컨텍스트 주입](#inject-dynamic-context)을 사용합니다: Claude Code는 명령어를 실행하고 Claude가 skill 콘텐츠를 보기 전에 줄을 출력으로 바꾸므로, 지침은 현재 diff가 이미 인라인된 상태로 도착합니다.97 `` !`git diff HEAD` `` 줄은 [동적 컨텍스트 주입](#inject-dynamic-context)을 사용합니다: Claude Code는 명령어를 실행하고 Claude가 skill 콘텐츠를 보기 전에 줄을 출력으로 바꾸므로, 지침이 현재 diff가 이미 인라인된 상태로 도착합니다.

88 </Step>98 </Step>

89 99

90 <Step title="skill 테스트">100 <Step title="skill 테스트">

~~91 git 프로젝트를 열고, 파일을 약간 편집한 후, `claude`를 실행하여 Claude Code를 시작합니다. 두 가지 방법으로 skill을 테스트할 수 있습니다.~~101 git 프로젝트를 열고, 파일을 약간 편집한 후 `claude`를 실행하여 Claude Code를 시작합니다. skill을 두 가지 방법으로 테스트할 수 있습니다.

92 102

~~93 **Claude가 자동으로 호출하도록 하기** - 설명과 일치하는 항목을 물어봅니다:~~103 **설명과 일치하는 내용을 물어봐서 Claude가 자동으로 호출하도록 하기:**

94 104

95 ```text theme={null}105 ```text theme={null}

96 What did I change?106 What did I change?

97 ```107 ```

98 108

~~99 **또는 skill 이름으로 직접 호출하기**:~~109 **또는 skill 이름으로 직접 호출:**

100 110

101 ```text theme={null}111 ```text theme={null}

102 /summarize-changes112 /summarize-changes

103 ```113 ```

104 114

105 어느 쪽이든 Claude는 편집의 짧은 요약과 위험 목록으로 응답해야 합니다.115 어느 쪽이든 Claude는 편집 내용의 짧은 요약과 위험 목록으로 응답해야 합니다.

106 </Step>116 </Step>

107</Steps>117</Steps>

108 118

109<h3 id="where-skills-live">119<h2 id="where-skills-live">

110 Skills가 있는 위치120 스킬이 로드되는 위치 선택

121</h2>

122

123스킬을 저장하는 위치에 따라 어떤 세션에서 로드될지가 결정됩니다. 홈 디렉토리에 저장하면 모든 프로젝트에서 로드되고, 저장소에 커밋하면 그곳에서 작업하는 모든 사람이 사용할 수 있으며, 플러그인이나 관리형 설정을 통해 배포하면 전체 팀이 접근할 수 있습니다.

124

125| 위치 | 경로 | 로드되는 위치 |

126| :------------------- | :------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |

127| Enterprise | `.claude/skills/<skill-name>/SKILL.md` in the [managed settings directory](/docs/ko/managed-settings#delivery-mechanisms) | 조직이 배포한 머신의 모든 사용자 |

128| Personal | `~/.claude/skills/<skill-name>/SKILL.md` | 이 머신의 모든 프로젝트, 단 [Cowork 또는 클라우드 세션](#skills-in-cowork-and-cloud-sessions)은 제외 |

129| Project | `.claude/skills/<skill-name>/SKILL.md` | 이 저장소의 세션. 커밋하면 팀도 사용할 수 있습니다 |

130| Nested | `<subdir>/.claude/skills/<skill-name>/SKILL.md` | `<subdir>`에서 시작되거나 그 아래에서 시작된 세션. `<subdir>` 위에서 시작된 세션은 Claude가 그곳의 파일에서 작업할 때 스킬을 한 번 로드합니다. [모노레포 및 하위 디렉토리](#discovery-from-parent-and-nested-directories) 참조 |

131| Additional directory | `.claude/skills/<skill-name>/SKILL.md` in a directory you pass with `--add-dir` | 해당 세션. [프로젝트 외부의 디렉토리](#skills-from-additional-directories) 참조 |

132| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | [플러그인](/docs/ko/plugins)이 활성화된 곳, `/plugin-name:skill-name`으로 표시 |

133| claude.ai account | claude.ai 설정에서 활성화한 스킬 | Cowork 및 클라우드 세션. 로컬 세션의 경우 [claude.ai에서 동기화된 스킬](#how-synced-skills-behave) 참조 |

134

135스킬 폴더는 또한 다음 규칙을 따릅니다:

136

137* **심볼릭 링크된 폴더**: enterprise, personal 또는 project 위치의 `<skill-name>` 항목은 디스크의 다른 곳에 있는 디렉토리로의 심볼릭 링크일 수 있습니다. Claude Code는 대상에서 `SKILL.md`를 읽고 여러 위치가 같은 대상을 가리키더라도 스킬을 한 번만 로드합니다. 플러그인 스킬은 [심볼릭 링크를 다르게 처리합니다](/docs/ko/plugins-reference#share-files-within-a-marketplace-with-symlinks).

138* **예약된 이름**: 스킬 폴더를 `synced`로 이름 지으면 안 됩니다(대소문자 상관없음). Claude Code는 `~/.claude/skills/synced/`를 [claude.ai에서 다운로드한 스킬](#where-synced-skills-load)에 사용하고 enterprise, personal 및 project 위치에서 해당 이름으로 작성한 스킬을 건너뜁니다.

139* **명령 파일**: `.claude/commands/`의 Markdown 파일은 이전 형식이며 여전히 작동합니다. `name` 및 `paths`를 제외한 동일한 [frontmatter](#frontmatter-reference)를 지원하며, 파일 이름으로 호출합니다. 새 작업에는 스킬을 선호하세요. 스킬은 [지원 파일](#add-supporting-files)도 지원하기 때문입니다.

140* **플러그인으로서의 스킬 폴더**: 스킬 폴더에 `.claude-plugin/plugin.json`을 추가하면 `<name>@skills-dir`이라는 이름의 [플러그인](/docs/ko/plugins-reference#skills-directory-plugins)으로 로드되므로 에이전트, hooks 및 MCP 서버를 번들할 수 있습니다. 프로젝트의 `.claude/skills/`에서는 먼저 워크스페이스 신뢰 대화를 수락해야 합니다.

141

142<h3 id="discovery-from-parent-and-nested-directories">

143 모노레포 및 하위 디렉토리에서 스킬 로드

111</h3>144</h3>

112 145

113skill을 저장하는 위치에 따라 누가 사용할 수 있는지가 결정됩니다:146Claude Code는 시작한 디렉토리와 저장소 루트까지의 모든 상위 디렉토리에서 `.claude/skills/`의 프로젝트 스킬을 로드하므로, `packages/frontend/`에서 시작해도 루트에 정의된 스킬을 선택합니다. v2.1.246 이상에서 [`/cd`로 세션을 이동](/docs/ko/permissions#move-the-session-to-another-directory)할 때, Claude Code는 새 디렉토리의 프로젝트 스킬을 추가합니다.

114 147

115| 위치 | 경로 | 적용 대상 |148시작한 위치 아래의 `.claude/skills/` 디렉토리에 있는 스킬은 시작 시 로드되지 않습니다. Claude가 해당 하위 디렉토리의 파일을 처음 읽거나 편집할 때 로드되고 세션의 나머지 기간 동안 사용 가능합니다. 그때까지는 `/` 메뉴에 나타나지 않으며 이름으로 호출할 수 없습니다. 더 빨리 로드하려면 하위 디렉토리의 경로로 `/add-dir`을 실행하세요. 이는 Claude Code v2.1.257 이상이 필요합니다.

116| :--------- | :--------------------------------------- | :------------ |

117| Enterprise | [관리 설정](/docs/ko/settings#settings-files) 참조 | 조직의 모든 사용자 |

118| Personal | `~/.claude/skills/<skill-name>/SKILL.md` | 모든 프로젝트 |

119| Project | `.claude/skills/<skill-name>/SKILL.md` | 이 프로젝트만 |

120| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | 플러그인이 활성화된 위치 |

121 149

122skills가 여러 수준에서 같은 이름을 공유할 때, enterprise가 personal을 재정의하고, personal이 project를 재정의합니다. 예를 들어, 프로젝트의 `.claude/skills/`에 있는 `code-review` skill은 번들된 `/code-review`를 대체합니다. Plugin skills는 `plugin-name:skill-name` 네임스페이스를 사용하므로 다른 수준과 충돌할 수 없습니다. `.claude/commands/`에 파일이 있으면 동일한 방식으로 작동하지만, skill과 명령어가 같은 이름을 공유하면 skill이 우선합니다.150중첩된 스킬이 다른 스킬과 이름을 공유할 때, 둘 다 사용 가능합니다. 저장소 루트에 `deploy` 스킬이 있고 `apps/web/.claude/skills/`에 다른 스킬이 있을 때:

123 151

124Skills는 또한 작업 디렉토리 아래의 중첩된 `.claude/skills/` 디렉토리에서 로드됩니다. Claude가 하위 디렉토리의 파일을 읽거나 편집할 때, 해당 하위 디렉토리의 `.claude/skills/`에 있는 skills가 사용 가능해집니다. 이를 통해 monorepo 패키지가 자신의 skills를 제공할 수 있으며, 세션이 저장소 루트에서 시작되었더라도 해당 패키지에서 작업할 때 적용됩니다.152* `/deploy`는 루트 스킬을 실행합니다. Claude Code는 또한 Claude를 위해 디렉토리 한정 변형을 나열하며, 작업 중인 파일이 있는 디렉토리의 스킬을 호출하도록 지시하므로 중첩된 스킬은 여전히 `apps/web/`의 작업에 적용됩니다.

153* `/apps/web:deploy`는 중첩된 스킬을 독립적으로 실행합니다. 설명에 적용되는 디렉토리의 이름이 지정됩니다.

125 154

126중첩된 skill이 다른 skill과 같은 이름을 공유하면, 둘 다 사용 가능합니다. 예를 들어, 프로젝트 루트에 `deploy` skill이 있고 `apps/web/.claude/skills/`에 다른 skill이 있는 경우:155<h3 id="skills-from-additional-directories">

156 프로젝트 외부의 디렉토리에서 스킬 로드

157</h3>

127 158

128* 중첩된 skill은 디렉토리 한정 이름 `apps/web:deploy` 아래에 나타납니다.159`--add-dir` 또는 `/add-dir`으로 디렉토리를 추가할 때, Claude Code는 해당 디렉토리의 `.claude/skills/`에 있는 스킬과 `.claude/commands/` 및 `.claude/agents/`를 로드합니다. Agent SDK가 TypeScript의 [`additionalDirectories`](/docs/ko/agent-sdk/typescript#options) 또는 Python의 [`add_dirs`](/docs/ko/agent-sdk/python#claudeagentoptions)를 통해 추가하는 디렉토리는 SDK가 `--add-dir`으로 전달하기 때문에 동일한 방식으로 로드됩니다. `settings.json`의 `permissions.additionalDirectories` 설정은 파일 액세스만 부여하고 이 중 어느 것도 로드하지 않습니다.

129* 해당 설명은 어느 디렉토리에 적용되는지 나타냅니다.

130* Claude는 작업 중인 파일과 일치하는 변형을 선택합니다.

131 160

132`/deploy`를 입력하면 프로젝트 루트 skill이 실행됩니다. 중첩된 변형을 명시적으로 실행하려면 한정된 이름 `/apps/web:deploy`를 입력합니다.161Claude Code는 시작 시 `--add-dir`으로 전달한 디렉토리의 `.claude/skills/`를 [세션 중 스킬 편집](#live-change-detection)에서 설명하는 대로 감시합니다. 추가된 디렉토리의 `.claude/commands/` 또는 `.claude/agents/`는 감시하지 않으므로 파일을 변경한 후 세션을 다시 시작하세요.

133 162

134한정되지 않은 이름을 호출하거나 Claude가 호출할 때, 프로젝트 루트 skill이 로드되고, Claude Code는 디렉토리 한정 변형 목록을 해당 콘텐츠에 추가하며, Claude가 작업 중인 파일을 보유한 변형도 호출하도록 지시합니다. 따라서 중첩된 skill은 한정되지 않은 이름만 호출할 때도 해당 디렉토리의 작업에 계속 적용됩니다. Claude Code v2.1.203 이상이 필요합니다.163이러한 로드는 기본적으로 켜져 있는 `project` [설정 소스](/docs/ko/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources)에 따라 달라집니다. [`strictPluginOnlyCustomization`](/docs/ko/settings-reference#strictpluginonlycustomization) 정책, [bare mode](/docs/ko/headless#start-faster-with-bare-mode) 및 [`--safe-mode`](/docs/ko/cli-reference#cli-flags)는 각각 이를 더 제한하며, 해당 페이지에서 설명합니다. 추가된 디렉토리가 로드하는 것(CLAUDE.md 및 플러그인 설정 포함)의 전체 표는 [추가 디렉토리는 파일 액세스를 부여하지만 구성은 부여하지 않습니다](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration)를 참조하세요.

135 164

136`<skill-name>` 항목이 enterprise, personal 또는 project 위치에 있을 수 있으며, 디스크의 다른 곳에 있는 디렉토리로의 symlink일 수 있습니다. Claude Code는 symlink를 따라가고 대상 디렉토리에서 `SKILL.md`를 읽으며, 같은 대상에 둘 이상의 위치에서 도달할 수 있으면 Claude Code는 skill을 한 번만 로드합니다. Plugin skills는 symlinks를 다르게 처리합니다. [마켓플레이스 내에서 symlinks를 사용하여 파일 공유](/docs/ko/plugins-reference#share-files-within-a-marketplace-with-symlinks)를 참조하세요.165<h3 id="resolve-skills-that-share-a-name">

166 이름을 공유하는 스킬 해결

167</h3>

137 168

138<Note>169두 스킬이 이름을 공유할 때, 각각이 어디에서 왔는지가 `/name`이 실행하는 스킬을 결정합니다. 표는 enterprise, personal, project, nested, plugin 및 claude.ai 위치, 번들된 스킬 및 명령 파일을 다룹니다:

139 `.claude-plugin/plugin.json`을 skill 폴더에 추가하면 `<name>@skills-dir`이라는 [플러그인](/docs/ko/plugins-reference#skills-directory-plugins)으로 로드되므로, agents, hooks 및 MCP 서버를 번들로 제공할 수 있습니다. 프로젝트의 `.claude/skills/`에서는 먼저 작업 공간 신뢰 대화를 수락해야 합니다.

140</Note>

141 170

142<h4 id="live-change-detection">171| 같은 이름 위치 | 실행되는 스킬 |

143 라이브 변경 감지172| :------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------- |

173| Enterprise, personal 및 project 중 두 개 | Enterprise가 personal보다 우선하고, personal이 project보다 우선합니다. `~/.claude/skills/`와 프로젝트의 `.claude/skills/` 모두에 `deploy`가 있으면 `/deploy`는 personal 스킬을 실행합니다 |

174| 위의 위치 중 하나와 [번들된 스킬](#bundled-skills) | 사용자 스킬이 번들된 명령을 대체하지만 별칭은 대체하지 않습니다. 프로젝트 `code-review` 스킬은 `/code-review`를 대체하고, 번들된 별칭 `/review`는 사용자 스킬을 실행하지 않습니다 |

175| 스킬과 `.claude/commands/`의 파일 | 스킬 |

176| 프로젝트 루트 스킬과 중첩된 스킬 | 둘 다 로드됩니다. [모노레포 및 하위 디렉토리](#discovery-from-parent-and-nested-directories) 참조 |

177| 플러그인 스킬과 위의 위치 중 하나의 스킬 | 플러그인 스킬이 `/plugin-name:skill-name`으로 네임스페이스되기 때문에 둘 다 로드됩니다 |

178| 위의 모든 것과 claude.ai에서 동기화된 스킬 | 다른 스킬 또는 명령. [동기화된 스킬 이름이 다른 명령과 일치할 때](#when-a-synced-skill-name-matches-another-command) 참조 |

179

180<h3 id="skills-in-cowork-and-cloud-sessions">

181 Cowork 및 클라우드 세션에서 스킬 사용

182</h3>

183

184[Cowork](https://claude.com/product/cowork) 세션 및 [클라우드 세션](/docs/ko/cloud-environments#what-carries-over-from-your-setup)([루틴](/docs/ko/routines) 포함)은 머신의 `~/.claude/skills/`를 읽지 않습니다. 대화형 및 예약된 Cowork 세션 모두 claude.ai 계정에 대해 활성화된 스킬을 로드하며, 세션 시작 시 동기화됩니다. Desktop 앱 사이드바의 **Customize**에서 또는 claude.ai의 스킬 설정에서 관리하세요. 클라우드 세션은 추가로 복제된 저장소의 `.claude/skills/`에 커밋된 프로젝트 스킬을 로드합니다.

185

186스킬이 머신의 `~/.claude/skills/`에만 있으면, [루틴](/docs/ko/routines)이 호출할 때 Claude Code는 스킬을 찾을 수 없다고 보고합니다. 각 루틴 실행이 새로운 원격 세션으로 시작되기 때문입니다. 이러한 세션에서 personal 스킬을 사용 가능하게 하려면:

187

188* Cowork 및 클라우드 세션의 경우 claude.ai 계정에 대해 스킬을 활성화하세요.

189* 클라우드 세션의 경우 대신 저장소의 `.claude/skills/`에 스킬을 커밋하거나, 저장소의 `.claude/settings.json`에 선언된 플러그인에 포함시킬 수 있습니다. 저장소 선언 플러그인은 [세션 시작 시 설치됩니다](/docs/ko/cloud-environments#what-carries-over-from-your-setup). 사용자 설정에서만 활성화된 플러그인은 전송되지 않습니다.

190

191[Desktop 예약된 작업](/docs/ko/desktop-scheduled-tasks)은 머신에서 로컬로 실행되므로 `~/.claude/skills/`를 로드합니다.

192

193<h3 id="how-synced-skills-behave">

194 claude.ai에서 동기화된 스킬

195</h3>

196

197이 섹션은 claude.ai 계정에 대해 스킬을 활성화한 경우에 적용됩니다. Cowork 및 클라우드 세션에서 Claude Code는 머신에서 설정할 필요 없이 해당 스킬을 로드합니다. 머신의 다른 세션에서 Claude Code는 비대화형 실행에서 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/ko/env-vars#variables)로 동기화를 켠 후에만 로드합니다. [동기화된 스킬이 로드되는 위치](#where-synced-skills-load)에서 설명합니다.

198

199Claude Code는 세션이 실행되는 머신에서 작성한 파일을 읽는 대신 계정에서 동기화된 스킬을 다운로드하므로, [스킬 위치](#where-skills-live)에 저장하는 스킬에 적용되지 않는 규칙을 동기화된 스킬에 적용합니다.

200

201<h4 id="where-synced-skills-load">

202 동기화된 스킬이 로드되는 위치

144</h4>203</h4>

145 204

146Claude Code는 skill 디렉토리의 파일 변경을 감시합니다. `~/.claude/skills/`, 프로젝트 `.claude/skills/`, 또는 `--add-dir` 디렉토리 내의 `.claude/skills/` 아래에서 skill을 추가, 편집 또는 제거하면 Claude Code를 다시 시작하지 않고도 현재 세션 내에서 적용됩니다. 세션이 시작되었을 때 존재하지 않았던 최상위 skills 디렉토리를 생성하려면 Claude Code를 다시 시작해야 새 디렉토리를 감시할 수 있습니다.205Cowork 또는 클라우드 세션에서 Claude Code는 claude.ai 계정에 대해 활성화된 스킬을 로드하며, [Cowork 및 클라우드 세션에서 스킬 사용](#skills-in-cowork-and-cloud-sessions)에서 해당 세션이 어떤 스킬을 받을지 선택하는 방법을 설명합니다.

147 206

148<Note>207머신의 다른 세션에서 Claude Code는 비대화형 실행에서 한 번 다운로드한 후에만 로드합니다:

149 라이브 변경 감지는 `SKILL.md` 텍스트만 포함합니다. skill 폴더가 [플러그인](/docs/ko/plugins-reference#skills-directory-plugins)이기도 한 경우, `hooks/`, `.mcp.json`, `agents/` 및 `output-styles/`의 변경 사항은 `/reload-plugins`를 실행해야 적용됩니다.

150</Note>

151 208

152<h4 id="automatic-discovery-from-parent-and-nested-directories">209<Steps>

153 상위 및 중첩된 디렉토리에서 자동 검색210 <Step title="claude.ai 계정에 대해 스킬 활성화">

211 [Cowork 및 클라우드 세션에서 스킬 사용](#skills-in-cowork-and-cloud-sessions)에서 설명하는 대로 claude.ai 계정에 대해 원하는 각 스킬을 활성화하세요. Claude Code는 활성화한 스킬만 다운로드하며, 다운로드하려면 claude.ai 로그인이 필요합니다.

212 </Step>

213

214 <Step title="동기화가 켜진 비대화형 모드에서 Claude Code 실행">

215 Claude Code는 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/ko/env-vars#variables)를 `1`로 설정하고 `-p` 플래그로 [비대화형 모드](/docs/ko/headless)에서 실행할 때만 동기화된 스킬을 다운로드합니다. 전달하는 프롬프트는 다운로드에 영향을 주지 않습니다.

216

217 ```bash theme={null}

218 CLAUDE_CODE_SYNC_SKILLS=1 claude -p "List the skills you have available"

219 ```

220

221 Claude Code는 스킬을 `~/.claude/skills/synced/`로 다운로드하고, 프롬프트에 답하고, 다른 비대화형 실행처럼 종료합니다. 다운로드된 스킬은 종료 후 디스크에 남아 있으므로 실행을 계속 열어 둘 필요가 없습니다. Claude Code는 `CLAUDE_CODE_SYNC_SKILLS`가 설정된 실행 중에만 스킬을 다운로드하므로, claude.ai에서 스킬을 활성화하거나 변경한 후 명령을 다시 실행하세요. 동기화를 기다리는 실행 시간을 변경하려면 [`CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`](/docs/ko/env-vars#variables)를 설정하세요.

222 </Step>

223

224 <Step title="로컬 세션에서 스킬이 로드되는지 확인">

225 `CLAUDE_CODE_SYNC_SKILLS`를 설정하지 않고 대화형 세션을 시작하고 `/skills`를 실행하세요. 메뉴는 다운로드된 스킬을 `claude.ai sync` 아래에 나열합니다. 같은 claude.ai 로그인으로 시작하는 모든 후속 로컬 세션도 `~/.claude/skills/synced/`에서 로드합니다.

226 </Step>

227</Steps>

228

229<h4 id="when-a-synced-skill-name-matches-another-command">

230 동기화된 스킬 이름이 다른 명령과 일치할 때

154</h4>231</h4>

155 232

156프로젝트 skills는 시작 디렉토리의 `.claude/skills/`와 저장소 루트까지의 모든 상위 디렉토리에서 로드되므로, 하위 디렉토리에서 Claude를 시작해도 루트에서 정의된 skills를 선택합니다. 시작 디렉토리 아래의 하위 디렉토리에 있는 파일로 작업할 때, Claude Code는 필요에 따라 중첩된 `.claude/skills/` 디렉토리에서 skills를 검색합니다. 예를 들어, `packages/frontend/`의 파일을 편집하는 경우, Claude Code는 `packages/frontend/.claude/skills/`에서도 skills를 찾습니다. 이는 패키지가 자신의 skills를 가진 monorepo 설정을 지원합니다.233Claude Code는 이름이 다른 명령과 일치하는 동기화된 스킬을 건너뛰고, 그 다른 명령이 실행됩니다. 다른 명령은 기본 제공 명령, [번들된 스킬](#bundled-skills), [로컬 수준](#where-skills-live) 중 하나의 스킬, 플러그인 스킬, `.claude/commands/`의 파일 또는 [MCP 프롬프트](/docs/ko/mcp#use-mcp-prompts-as-commands)일 수 있습니다. Claude Code는 또한 번들된 스킬을 끈 후처럼 세션에서 사용할 수 없을 때도 자체 기본 제공 명령 및 번들된 스킬의 이름을 예약하므로, 해당 이름의 동기화된 스킬을 건너뜁니다.

157 234

158각 skill은 `SKILL.md`를 진입점으로 하는 디렉토리입니다:235Claude Code는 동기화된 스킬에 레이블을 지정하므로 어디에서 왔는지 알 수 있습니다. `/skills` 메뉴와 `/context`는 동기화된 스킬을 `claude.ai sync` 아래에 그룹화하고, `/` 명령 메뉴는 claude.ai에서 온 것으로 표시합니다.

159 236

160```text theme={null}237이름을 비교할 때, Claude Code는 대소문자, 공백 및 보이지 않는 문자를 무시하고, 전자 문자 및 대시 변형과 같은 호환성 형식을 일반 등가물로 취급하므로, 동기화된 `Commit`은 로컬 `commit` 옆에 로드될 수 없습니다. 다른 알파벳의 모양이 비슷한 문자로만 다른 이름은 다른 이름으로 간주되며, `claude.ai sync` 레이블은 두 개를 구분하는 방법입니다.

161my-skill/238

162├── SKILL.md # 주요 지침 (필수)239<h4 id="how-claude-code-handles-the-frontmatter-of-a-synced-skill">

163├── template.md # Claude가 채울 템플릿240 Claude Code가 동기화된 스킬의 frontmatter를 처리하는 방법

164├── examples/241</h4>

165│ └── sample.md # 예상 형식을 보여주는 예제 출력

166└── scripts/

167 └── validate.sh # Claude가 실행할 수 있는 스크립트

168```

169 242

170`SKILL.md`는 주요 지침을 포함하며 필수입니다. 다른 파일은 선택적이며 더 강력한 skills를 구축할 수 있습니다: Claude가 채울 템플릿, 예상 형식을 보여주는 예제 출력, Claude가 실행할 수 있는 스크립트 또는 상세한 참조 문서. `SKILL.md`에서 이러한 파일을 참조하여 Claude가 각 파일의 내용과 로드 시기를 알 수 있도록 합니다. 자세한 내용은 [지원 파일 추가](#add-supporting-files)를 참조하세요.243Claude Code는 동기화된 스킬의 frontmatter에 두 가지 규칙을 적용합니다:

171 244

172<Note>245* Claude Code는 모든 종류의 세션에서 frontmatter를 준수하므로, `allowed-tools` 부여는 일반 [권한 흐름](/docs/ko/permissions)을 거칩니다.

173 `.claude/commands/`의 파일은 계속 작동하며 동일한 [frontmatter](#frontmatter-reference)를 지원합니다. Skills는 지원 파일과 같은 추가 기능을 지원하므로 권장됩니다.246* Claude Code는 스킬이 제공하는 표시 텍스트(예: 설명)를 정제합니다. 제어 문자를 제거하고, Claude에 도달하는 텍스트(예: 설명)에서 꺾쇠 괄호를 이스케이프하여 텍스트가 Claude Code의 내부 형식을 모방할 수 없도록 합니다.

174</Note>

175 247

176<h4 id="skills-from-additional-directories">248<h4 id="how-claude-code-handles-the-body-of-a-synced-skill">

177 추가 디렉토리의 Skills249 Claude Code가 동기화된 스킬의 본문을 처리하는 방법

178</h4>250</h4>

179 251

180`--add-dir` 플래그와 `/add-dir` 명령어는 [파일 액세스를 부여](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration)하지만 구성 검색은 하지 않습니다. 그러나 skills는 예외입니다: 추가된 디렉토리 내의 `.claude/skills/`는 자동으로 로드됩니다. 이 예외는 `--add-dir`과 `/add-dir`에만 적용됩니다. `settings.json`의 `permissions.additionalDirectories` 설정은 파일 액세스만 부여하며 skills를 로드하지 않습니다. [라이브 변경 감지](#live-change-detection)를 참조하여 세션 중에 편집이 어떻게 선택되는지 확인하세요.252Claude Code가 동기화된 스킬의 본문으로 수행하는 작업은 세션이 실행되는 위치에 따라 달라집니다:

181 253

182다른 `.claude/` 구성(예: 명령어 및 출력 스타일)은 추가 디렉토리에서 로드되지 않습니다. 로드되는 항목과 로드되지 않는 항목의 전체 목록과 프로젝트 간 구성을 공유하는 권장 방법은 [예외 표](/docs/ko/permissions#additional-directories-grant-file-access-not-configuration)를 참조하세요.254* 클라우드 세션에서 본문은 로컬 스킬이 가지는 동작을 유지합니다. 세션이 격리된 컨테이너에서 실행되기 때문입니다.

255* 데스크톱의 Cowork 세션에서 본문은 로컬 스킬이 가지는 동작을 유지합니다. 단, Claude Code는 모든 `!` 명령 줄을 [`disableSkillShellExecution` 플레이스홀더](#inject-dynamic-context)로 바꿉니다. 모든 스킬에 대해 그곳에서 제공하는 것처럼 말입니다.

256* 머신의 다른 세션에서 Claude Code는 [`!` 명령](#inject-dynamic-context)을 실행하지 않고, `@` 참조가 로컬 스킬에 대해 이름을 지정하는 방식으로 파일을 첨부하지 않으며, `${CLAUDE_PROJECT_DIR}` 및 `${CLAUDE_SESSION_ID}` 플레이스홀더를 대체하지 않으므로, `@` 참조와 두 플레이스홀더 모두 Claude에 리터럴 텍스트로 도달합니다. `!` 명령 줄도 리터럴 텍스트로 도달하거나, `disableSkillShellExecution`이 켜져 있을 때 해당 플레이스홀더로 도달합니다.

183 257

184<Note>258<h3 id="live-change-detection">

185 `--add-dir` 디렉토리의 CLAUDE.md 파일은 기본적으로 로드되지 않습니다. 로드하려면 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`을 설정하세요. [추가 디렉토리에서 로드](/docs/ko/memory#load-from-additional-directories)를 참조하세요.259 세션 중 스킬 편집

186</Note>260</h3>

261

262Claude Code는 [bare mode](/docs/ko/headless#start-faster-with-bare-mode)를 제외하고 스킬 디렉토리의 파일 변경을 감시합니다. `~/.claude/skills/`, 프로젝트 `.claude/skills/` 또는 `--add-dir` 디렉토리 내의 `.claude/skills/` 아래에서 스킬을 추가, 편집 또는 제거할 때, Claude Code는 재시작 없이 현재 세션 내에서 변경 사항을 선택합니다. 세션 시작 시 존재하지 않던 최상위 스킬 디렉토리를 만들면 Claude Code를 다시 시작하여 새 디렉토리를 감시할 수 있도록 하세요.

263

264라이브 변경 감지는 `SKILL.md` 텍스트만 다룹니다. [플러그인](/docs/ko/plugins-reference#skills-directory-plugins)이기도 한 스킬 폴더의 경우, `hooks/`, `.mcp.json`, `agents/` 및 `output-styles/`의 변경 사항은 `/reload-plugins`가 적용되어야 합니다.

265

266<h3 id="remove-a-skill">

267 스킬 제거

268</h3>

269

270스킬을 제거하는 방법은 어디에서 왔는지에 따라 다릅니다:

271

272* **Personal 또는 project 스킬**: 스킬의 디렉토리 `~/.claude/skills/<skill-name>/` 또는 `.claude/skills/<skill-name>/`을 삭제하세요. Claude Code는 [현재 세션의 `/skills`에서 삭제합니다](#live-change-detection). Claude Code가 이미 로드한 콘텐츠는 [스킬 콘텐츠 수명 주기](#skill-content-lifecycle)를 따릅니다.

273* **Enterprise 스킬**: 관리자가 [관리형 설정 디렉토리](/docs/ko/managed-settings#delivery-mechanisms) 내의 `.claude/skills/`에서 스킬의 디렉토리를 삭제합니다. 예를 들어 Linux의 `/etc/claude-code/.claude/skills/<skill-name>/`.

274* **Plugin 스킬**: `/plugin` 메뉴에서 또는 `/plugin uninstall <plugin-name>@<marketplace-name>`으로 스킬을 제공하는 플러그인을 비활성화하거나 제거하세요. Claude Code는 `/reload-plugins`를 실행하거나 다시 시작한 후 플러그인의 스킬을 언로드합니다. [플러그인 변경 사항을 다시 시작하지 않고 적용](/docs/ko/discover-plugins#apply-plugin-changes-without-restarting) 참조.

275* **claude.ai에서 동기화된 스킬**: [활성화](#skills-in-cowork-and-cloud-sessions)한 것과 같은 위치에서 claude.ai 계정에 대해 스킬을 끄세요. Claude Code는 다음 번 [스킬을 동기화](#where-synced-skills-load)할 때 `~/.claude/skills/synced/`에서 제거합니다. 대신 디렉토리를 직접 삭제하면 다음 동기화가 스킬이 claude.ai에서 활성화된 상태로 유지되는 동안 다시 다운로드합니다.

276* **번들된 스킬**: [`disableBundledSkills`](#bundled-skills)를 `true`로 설정하여 `/doctor`를 제외한 모든 번들된 스킬을 끄거나, [`skillOverrides`](#override-skill-visibility-from-settings)에서 하나의 스킬을 `"off"`로 설정하여 숨기세요.

277

278Personal 또는 project 스킬을 유지하지만 Claude가 자동으로 호출하지 않도록 하려면, frontmatter에서 [`disable-model-invocation: true`](#control-who-invokes-a-skill)를 설정하거나, 파일을 편집하지 않으려면 [`skillOverrides`](#override-skill-visibility-from-settings)에서 `"user-invocable-only"`를 설정하세요.

187 279

188<h2 id="configure-skills">280<h2 id="configure-skills">

189 Skills 구성281 스킬 구성

190</h2>282</h2>

191 283

192Skills는 `SKILL.md` 상단의 YAML frontmatter와 그 뒤의 markdown 콘텐츠를 통해 구성됩니다.284스킬은 `SKILL.md` 상단의 YAML 프론트매터와 그 뒤에 오는 마크다운 콘텐츠를 통해 구성됩니다.

193 285

194<h3 id="types-of-skill-content">286<h3 id="types-of-skill-content">

195 Skill 콘텐츠 유형287 스킬 콘텐츠의 유형

196</h3>288</h3>

197 289

198Skill 파일은 모든 지침을 포함할 수 있지만, 호출 방식을 생각하면 포함할 내용을 안내하는 데 도움이 됩니다:290스킬 파일은 모든 지침을 포함할 수 있지만, 스킬을 어떻게 호출하고 싶은지 생각하면 포함할 내용을 결정하는 데 도움이 됩니다.

199 291

200**참조 콘텐츠**는 Claude가 현재 작업에 적용하는 지식을 추가합니다. 규칙, 패턴, 스타일 가이드, 도메인 지식. 이 콘텐츠는 인라인으로 실행되므로 Claude가 대화 컨텍스트와 함께 사용할 수 있습니다.292**참고 콘텐츠**는 Claude가 현재 작업에 적용하는 지식을 추가합니다. 규칙, 패턴, 스타일 가이드, 도메인 지식입니다. 이 콘텐츠는 인라인으로 실행되므로 Claude가 대화 컨텍스트와 함께 사용할 수 있습니다.

201 293

202```yaml theme={null}294```yaml theme={null}

203---295---

211- Include request validation303- Include request validation

212```304```

213 305

214**작업 콘텐츠**는 배포, 커밋 또는 코드 생성과 같은 특정 작업에 대한 단계별 지침을 제공합니다. 이는 Claude가 자동으로 실행하도록 하기보다는 `/skill-name`으로 직접 호출하려는 작업입니다. `disable-model-invocation: true`를 추가하여 Claude가 자동으로 트리거하는 것을 방지합니다.306**작업 콘텐츠**는 Claude에게 배포, 커밋 또는 코드 생성과 같은 특정 작업에 대한 단계별 지침을 제공합니다. 이러한 작업은 Claude가 실행 시기를 결정하도록 하기보다는 `/skill-name`으로 직접 호출하려는 작업인 경우가 많습니다. Claude가 자동으로 트리거하는 것을 방지하려면 `disable-model-invocation: true`를 추가합니다. 아래 예제는 `context: fork`를 추가하며, 이는 스킬을 자체 서브에이전트 컨텍스트에서 실행합니다. [서브에이전트에서 스킬 실행](#run-skills-in-a-subagent)을 참조하세요.

215 307

216```yaml theme={null}308```yaml theme={null}

217---309---

2273. Push to the deployment target3193. Push to the deployment target

228```320```

229 321

230`SKILL.md`는 모든 것을 포함할 수 있지만, skill을 호출하는 방식(사용자, Claude 또는 둘 다)과 실행 위치(인라인 또는 subagent)를 생각하면 포함할 내용을 안내하는 데 도움이 됩니다. 복잡한 skills의 경우, [지원 파일을 추가](#add-supporting-files)하여 주요 skill을 집중적으로 유지할 수도 있습니다.322본문 자체는 간결하게 유지합니다. 스킬이 로드되면 해당 콘텐츠는 [여러 턴에 걸쳐 컨텍스트에 유지](#skill-content-lifecycle)되므로 모든 줄이 반복되는 토큰 비용입니다. 어떻게 또는 왜인지 설명하기보다는 무엇을 해야 하는지 명시하고, [CLAUDE.md 콘텐츠](/docs/ko/best-practices#write-an-effective-claude-md)에 적용할 동일한 간결성 테스트를 적용합니다.

~~231~~

232본문 자체는 간결하게 유지합니다. Skill이 로드되면, 그 콘텐츠는 [턴 전체에 걸쳐 컨텍스트에 유지](#skill-content-lifecycle)되므로, 모든 줄이 반복되는 토큰 비용입니다. 어떻게 또는 왜인지 설명하기보다는 무엇을 할지 명시하고, [CLAUDE.md 콘텐츠](/docs/ko/best-practices#write-an-effective-claude-md)에 적용할 동일한 간결성 테스트를 적용합니다.

233 323

234<h3 id="frontmatter-reference">324<h3 id="frontmatter-reference">

235 Frontmatter 참조325 프론트매터 참고

236</h3>326</h3>

237 327

238markdown 콘텐츠 외에도, `SKILL.md` 파일 상단의 `---` 마커 사이의 YAML frontmatter 필드를 사용하여 skill 동작을 구성할 수 있습니다:328마크다운 콘텐츠 외에도 `SKILL.md` 파일 상단의 `---` 마커 사이의 YAML 프론트매터 필드를 사용하여 스킬 동작을 구성할 수 있습니다.

239 329

240```yaml theme={null}330```yaml theme={null}

241---331---

248Your skill instructions here...338Your skill instructions here...

249```339```

250 340

251모든 필드는 선택적입니다. Claude가 skill을 언제 사용할지 알 수 있도록 `description`만 권장됩니다.341모든 필드는 선택 사항입니다. Claude가 스킬을 언제 사용할지 알 수 있도록 `description`만 권장됩니다.

342

343Claude Code는 파일의 첫 번째 줄이 `---`일 때만 프론트매터를 읽습니다. 그렇지 않으면 `---` 마커를 포함한 전체 파일을 스킬 콘텐츠로 취급합니다.

344

345부울 필드는 `true` 및 `false` 외에도 모든 문자 케이스에서 `yes`, `no`, `on`, `off`, `1`, `0`을 허용합니다. v2.1.218 이전에는 Claude Code가 `true` 및 `false`만 인식했습니다.

252 346

253| 필드 | 필수 | 설명 |347| 필드 | 필수 | 설명 |

254| :------------------------- | :-- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |348| :------------------------- | :-- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

255| `name` | 아니오 | skill 목록에 표시되는 표시 이름입니다. 디렉토리 이름으로 기본값이 설정됩니다. skill을 호출하기 위해 입력하는 이름과 어떻게 다른지는 [skill이 명령어 이름을 얻는 방법](#how-a-skill-gets-its-command-name)을 참조하세요. |349| `name` | 아니요 | 스킬 목록에 표시되는 표시 이름입니다. 기본값은 디렉토리 이름입니다. [스킬이 명령 이름을 얻는 방법](#how-a-skill-gets-its-command-name)을 참조하여 필드가 스킬을 호출하기 위해 입력하는 이름과 어떻게 상호 작용하는지 확인하세요. |

256| `description` | 권장 | skill이 무엇을 하는지, 언제 사용할지. Claude는 이를 사용하여 skill을 자동으로 적용할 시기를 결정합니다. 생략하면 markdown 콘텐츠의 첫 번째 단락을 사용합니다. 주요 사용 사례를 앞에 배치합니다: 결합된 `description` 및 `when_to_use` 텍스트는 컨텍스트 사용을 줄이기 위해 skill 목록에서 1,536자로 잘립니다. |350| `description` | 권장 | 스킬이 무엇을 하는지, 언제 사용할지입니다. Claude는 이를 사용하여 스킬을 적용할 시기를 결정합니다. 생략하면 마크다운 콘텐츠의 첫 번째 단락을 사용합니다. 주요 사용 사례를 먼저 입력하세요. 결합된 `description` 및 `when_to_use` 텍스트는 컨텍스트 사용을 줄이기 위해 스킬 목록에서 1,536자로 잘립니다. |

257| `when_to_use` | 아니오 | Claude가 skill을 호출해야 할 때에 대한 추가 컨텍스트(예: 트리거 구문 또는 예제 요청). skill 목록에서 `description`에 추가되며 1,536자 제한에 포함됩니다. |351| `when_to_use` | 아니요 | Claude가 스킬을 호출해야 할 때에 대한 추가 컨텍스트입니다. 예를 들어 트리거 구문이나 예제 요청입니다. 스킬 목록의 `description`에 추가되며 1,536자 제한에 포함됩니다. |

258| `argument-hint` | 아니오 | 예상 인수를 나타내기 위해 자동 완성 중에 표시되는 힌트. 예: `[issue-number]` 또는 `[filename] [format]`. |352| `argument-hint` | 아니요 | 자동 완성 중에 표시되는 힌트로 예상 인수를 나타냅니다. 예: `[issue-number]` 또는 `[filename] [format]`. |

259| `arguments` | 아니오 | skill 콘텐츠에서 [`$name` 치환](#available-string-substitutions)을 위한 명명된 위치 인수. 공백으로 구분된 문자열 또는 YAML 목록을 허용합니다. 이름은 순서대로 인수 위치에 매핑됩니다. |353| `arguments` | 아니요 | 스킬 콘텐츠에서 [`$name` 치환](#available-string-substitutions)을 위한 명명된 위치 인수입니다. 공백으로 구분된 문자열 또는 YAML 목록을 허용합니다. 이름은 순서대로 인수 위치에 매핑됩니다. |

260| `disable-model-invocation` | 아니오 | Claude가 이 skill을 자동으로 로드하는 것을 방지하려면 `true`로 설정합니다. `/name`으로 수동으로 트리거하려는 워크플로우에 사용합니다. 또한 skill이 [subagents에 미리 로드되는 것](/docs/ko/sub-agents#preload-skills-into-subagents)을 방지합니다. v2.1.196부터는 [예약된 작업](/docs/ko/scheduled-tasks)이 skill을 프롬프트로 하여 실행될 때 skill이 실행되는 것도 방지합니다. 기본값: `false`. |354| `disable-model-invocation` | 아니요 | Claude가 이 스킬을 자동으로 로드하는 것을 방지하려면 `true`로 설정합니다. `/name`으로 수동으로 트리거하려는 워크플로우에 사용합니다. 또한 스킬이 [서브에이전트에 사전 로드되는 것을 방지합니다](/docs/ko/sub-agents#preload-skills-into-subagents). v2.1.196부터 스킬이 [예약된 작업](/docs/ko/scheduled-tasks)이 스킬을 프롬프트로 하여 실행될 때 실행되는 것도 방지합니다. 기본값: `false`. |

261| `user-invocable` | 아니오 | `/` 메뉴에서 숨기려면 `false`로 설정합니다. 사용자가 직접 호출하지 않아야 하는 배경 지식에 사용합니다. 기본값: `true`. |355| `user-invocable` | 아니요 | Claude만 스킬을 호출해야 할 때 `false`로 설정합니다. Claude Code는 `/` 메뉴에서 숨기고 `/name`을 입력할 때 실행하지 않습니다. 사용자가 직접 호출하지 않아야 하는 배경 지식에 사용합니다. 기본값: `true`. |

262| `allowed-tools` | 아니오 | 이 skill이 활성화되었을 때 Claude가 권한을 요청하지 않고 사용할 수 있는 도구. 공백 또는 쉼표로 구분된 문자열 또는 YAML 목록을 허용합니다. |356| `allowed-tools` | 아니요 | 이 스킬을 호출하는 턴 중에 Claude가 권한을 요청하지 않고 사용할 수 있는 도구입니다. 다음 메시지를 보낼 때 권한이 해제됩니다. 공백 또는 쉼표로 구분된 문자열 또는 YAML 목록을 허용합니다. [스킬에 대한 도구 사전 승인](#pre-approve-tools-for-a-skill)을 참조하세요. |

263| `disallowed-tools` | 아니오 | 이 skill이 활성화되었을 때 Claude의 사용 가능한 도구 풀에서 제거되는 도구. `AskUserQuestion`과 같이 배경 루프에 대해 특정 도구를 호출하지 않아야 하는 자율 skills에 사용합니다. 공백 또는 쉼표로 구분된 문자열 또는 YAML 목록을 허용합니다. 다음 메시지를 보낼 때 제한이 해제됩니다. |357| `disallowed-tools` | 아니요 | 이 스킬이 활성화되는 동안 Claude의 사용 가능한 도구 풀에서 제거되는 도구입니다. 자동 루프와 같이 특정 도구를 호출하지 않아야 하는 자율 스킬에 사용합니다(예: `AskUserQuestion`). 공백 또는 쉼표로 구분된 문자열 또는 YAML 목록을 허용합니다. 다음 메시지를 보낼 때 제한이 해제됩니다. 거부 규칙과 마찬가지로 다른 도구가 남아 있는 동안 이 필드는 [`EndConversation`](/docs/ko/tools-reference#endconversation-tool-behavior)을 제거할 수 없습니다. |

264| `model` | 아니오 | 이 skill이 활성화되었을 때 사용할 모델. 재정의는 현재 턴의 나머지 부분에 적용되며 설정에 저장되지 않습니다. 다음 프롬프트에서 세션 모델이 재개됩니다. [`/model`](/docs/ko/model-config)과 동일한 값을 허용하거나 활성 모델을 유지하려면 `inherit`을 허용합니다. 조직의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록에서 제외된 값은 사용되지 않으며 세션은 현재 모델을 유지합니다. |358| `model` | 아니요 | 이 스킬이 활성화될 때 사용할 모델입니다. 재정의는 현재 턴의 나머지 부분에 적용되며 설정에 저장되지 않습니다. 다음 프롬프트를 보낼 때 세션 모델이 재개됩니다. [`/model`](/docs/ko/model-config)과 동일한 값을 허용하거나 활성 모델을 유지하려면 `inherit`을 허용합니다. 조직의 [`availableModels`](/docs/ko/model-config#restrict-model-selection) 허용 목록에서 제외된 값은 사용되지 않으며 세션은 현재 모델을 유지합니다. [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서, 그리고 [분류자가 명령을 검토하는 동안 계획 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서 자동 모드가 지원하지 않는 모델도 사용되지 않으며 세션은 현재 모델을 유지합니다. `context: fork`를 사용하면 값이 [포크된 서브에이전트의 모델](#run-skills-in-a-subagent)을 설정하고 제외된 값은 [서브에이전트 모델 재정의와 동일한 규칙을 따릅니다](/docs/ko/model-config#restrict-model-selection). |

265| `effort` | 아니오 | [노력 수준](/docs/ko/model-config#adjust-effort-level) - 이 skill이 활성화되었을 때. 세션 노력 수준을 재정의합니다. 기본값: 세션에서 상속. 옵션: `low`, `medium`, `high`, `xhigh`, `max`; 사용 가능한 수준은 모델에 따라 다릅니다. |359| `effort` | 아니요 | 이 스킬이 활성화될 때의 [노력 수준](/docs/ko/model-config#adjust-effort-level)입니다. 세션 노력 수준을 재정의합니다. 기본값: 세션에서 상속됩니다. 옵션: `low`, `medium`, `high`, `xhigh`, `max`. 사용 가능한 수준은 모델에 따라 다릅니다. |

266| `context` | 아니오 | forked subagent 컨텍스트에서 실행하려면 `fork`로 설정합니다. |360| `context` | 아니요 | 포크된 서브에이전트 컨텍스트에서 실행하려면 `fork`로 설정합니다. [서브에이전트에서 스킬 실행](#run-skills-in-a-subagent)을 참조하세요. |

267| `agent` | 아니오 | `context: fork`가 설정되었을 때 사용할 subagent 유형. |361| `agent` | 아니요 | `context: fork`가 설정되었을 때 사용할 서브에이전트 유형입니다. |

268| `hooks` | 아니오 | 이 skill의 라이프사이클에 범위가 지정된 hooks. 구성 형식은 [Skills 및 agents의 Hooks](/docs/ko/hooks#hooks-in-skills-and-agents)를 참조하세요. |362| `background` | 아니요 | `context: fork`에만 적용됩니다. 스킬을 호출하는 턴에서 포크된 서브에이전트의 결과를 기다리려면 `false`로 설정합니다. [백그라운드에서 실행](#run-skills-in-a-subagent) 대신입니다. 기본값: `true`. Claude Code v2.1.218 이상이 필요합니다. |

269| `paths` | 아니오 | 이 skill이 활성화되는 시기를 제한하는 Glob 패턴. 쉼표로 구분된 문자열 또는 YAML 목록을 허용합니다. 설정하면 Claude는 패턴과 일치하는 파일로 작업할 때만 자동으로 skill을 로드합니다. [경로별 규칙](/docs/ko/memory#path-specific-rules)과 동일한 형식을 사용합니다. |363| `hooks` | 아니요 | Claude Code가 스킬을 호출할 때 등록하고 세션의 나머지 부분 동안 계속 실행되는 훅입니다. 구성 형식 및 `once` 옵션은 [스킬 및 에이전트의 훅](/docs/ko/hooks#hooks-in-skills-and-agents)을 참조하세요. |

270| `shell` | 아니오 | 이 skill의 `` !`command` `` 및 ` ```! ` 블록에 사용할 shell. `bash`(기본값) 또는 `powershell`을 허용합니다. `powershell`을 설정하면 Windows에서 PowerShell을 통해 인라인 shell 명령어를 실행합니다. `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`이 필요합니다. |364| `paths` | 아니요 | 이 스킬이 활성화되는 시기를 제한하는 Glob 패턴입니다. 쉼표로 구분된 문자열 또는 YAML 목록을 허용합니다. 설정되면 Claude는 패턴과 일치하는 파일로 작업할 때만 스킬을 자동으로 로드합니다. [경로별 규칙](/docs/ko/memory#path-specific-rules)과 동일한 형식을 사용합니다. |

365| `shell` | 아니요 | 이 스킬에서 `` !`command` `` 및 ` ```! ` 블록에 사용할 셸입니다. `bash`(기본값) 또는 `powershell`을 허용합니다. `powershell`을 설정하면 [PowerShell 도구](/ko/tools-reference#powershell-tool)가 활성화되었을 때 PowerShell을 통해 인라인 셸 명령을 실행합니다. Git Bash가 없는 Windows에서는 기본적으로 켜져 있고, Git Bash가 있는 claude.ai 및 Console 계정에서는 기본적으로 켜져 있으며, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 세션 및 macOS, Linux, WSL에서는 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`이 필요합니다. 도구를 끄려면 `0`으로 설정합니다. |

366| `metadata` | 아니요 | 자격 또는 카탈로그 필드와 같은 자신의 키-값 데이터를 위한 자유 형식 YAML 맵으로, `SKILL.md`에서 자신의 도구로 읽습니다. Claude Code는 해당 콘텐츠에 대해 작동하지 않으며 맵이 아닌 값을 삭제합니다. `paths`와 같은 프론트매터 필드 이름을 키로 재사용하지 마세요. |

367| `license` | 아니요 | 스킬을 다루는 라이선스입니다. [Agent Skills](https://agentskills.io) 사양의 일부입니다. [Claude Code 외부에서 스킬 프론트매터 사용](#using-skill-frontmatter-outside-claude-code)을 참조하세요. Claude Code는 필드를 허용하지만 작동하지 않습니다. |

368| `compatibility` | 아니요 | [Agent Skills](https://agentskills.io) 사양에서 정의한 대로 의도된 제품 또는 시스템 전제 조건과 같은 스킬의 환경 요구 사항입니다. [Claude Code 외부에서 스킬 프론트매터 사용](#using-skill-frontmatter-outside-claude-code)을 참조하세요. 최대 500자의 문자열을 허용합니다. Claude Code는 필드를 허용하지만 작동하지 않습니다. |

369

370<h4 id="using-skill-frontmatter-outside-claude-code">

371 Claude Code 외부에서 스킬 프론트매터 사용

372</h4>

373

374Claude Code는 위 표의 모든 필드를 허용합니다. Claude Code 외부에서는 [Agent Skills](https://agentskills.io) 사양의 필드만 사용할 수 있습니다.

375

376| 배포 경로 | 사용할 수 있는 프론트매터 필드 |

377| :--------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |

378| [모든 수준](#where-skills-live)의 Claude Code 스킬(예: [플러그인](/docs/ko/plugins) 스킬 포함) | 위 표의 모든 필드 |

379| claude.ai 스킬 업로드, Skills API, [anthropics/skills](https://github.com/anthropics/skills)의 `package_skill.py`로 패키징 | `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` |

380

381[Cowork 및 클라우드 세션](#skills-in-cowork-and-cloud-sessions)(루틴 포함)에 대해 개인 스킬을 활성화하면 claude.ai에 업로드되므로 동일한 규칙이 적용됩니다.

382

383사양이 허용하지 않는 필드를 포함하면 필드를 무시하는 대신 하드 오류로 패키징 또는 업로드가 실패합니다.

384

385```

386Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

387```

388

389프론트매터를 사양의 6개 필드로 제한하면 위의 예상치 못한 키 오류를 피할 수 있습니다. [Agent Skills 사양](https://agentskills.io) 및 [Skills API 요구 사항](https://docs.claude.com/en/api/skills-guide)은 이러한 경로가 검증하는 다른 모든 것을 정의합니다. Claude Code 전용 본문 기능(예: [동적 컨텍스트 주입](#inject-dynamic-context))은 claude.ai 채팅 또는 API를 통해 작동하지 않습니다. Claude Code는 6개 필드를 모두 허용하므로 사양을 따르는 프론트매터는 변경 없이 Claude Code에 로드됩니다.

271 390

272<h4 id="how-a-skill-gets-its-command-name">391<h4 id="how-a-skill-gets-its-command-name">

273 Skill이 명령어 이름을 얻는 방법392 스킬이 명령 이름을 얻는 방법

274</h4>393</h4>

275 394

276skill을 호출하기 위해 입력하는 명령어는 skill 파일이 있는 위치에서 나옵니다. frontmatter `name` 필드는 skill 목록에 표시되는 표시 레이블을 설정하며, plugin 루트 `SKILL.md`를 제외하고는 `/` 뒤에 입력하는 내용을 변경하지 않습니다.395스킬을 호출하기 위해 입력하는 명령은 스킬 파일이 있는 위치와 플러그인 스킬의 경우 프론트매터 `name` 필드에서 나옵니다. 개인 또는 프로젝트 스킬에서 `name`은 스킬 목록에 표시되는 표시 레이블만 설정하고 명령은 여전히 디렉토리 이름에서 나옵니다. 플러그인 스킬에서 `name`은 명령의 마지막 세그먼트를 설정하고 플러그인 접두사는 제자리에 유지됩니다.

277 396

278아래 표는 각 레이아웃에 대해 명령어 이름이 어디에서 나오는지 보여줍니다:397아래 표는 각 레이아웃에 대해 명령 이름이 어디에서 나오는지 보여줍니다.

279 398

280| Skill 위치 | 명령어 이름 소스 | 예제 |399| 스킬 위치 | 명령 이름 소스 | 예제 |

281| :-------------------------------------------------------------------- | :--------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |400| :----------------------------------------------------------------- | :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |

283| [중첩된](#where-skills-live) `.claude/skills/` 디렉토리, 다른 skill과 이름이 충돌할 때 | 작업 디렉토리를 기준으로 한 하위 디렉토리 경로, 그 다음 skill 디렉토리 이름 | `apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy` |402| [중첩된](#where-skills-live) `.claude/skills/` 디렉토리(이름이 다른 스킬과 충돌할 때) | 작업 디렉토리를 기준으로 한 서브디렉토리 경로, 그 다음 스킬 디렉토리 이름 | `apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy` |

286| Plugin 루트 `SKILL.md` | Frontmatter `name`, plugin 디렉토리 이름을 폴백으로 사용 | `my-plugin/SKILL.md`에서 `name: review` → `/my-plugin:review`. [경로 동작 규칙](/docs/ko/plugins-reference#path-behavior-rules) 참조 |405| 플러그인 루트 `SKILL.md` | 프론트매터 `name`(플러그인 디렉토리 이름이 폴백) | `my-plugin/SKILL.md`에서 `name: review` → `/my-plugin:review`. [경로 동작 규칙](/docs/ko/plugins-reference#path-behavior-rules)을 참조하세요. |

406

407플러그인 스킬에서 프론트매터 `name`은 명령의 마지막 세그먼트에서 디렉토리 이름을 대체하므로 `my-plugin/skills/review/SKILL.md`에서 `name: fancy`는 `/my-plugin:fancy`가 됩니다. 다른 명령이 이미 해당 이름을 사용하지 않으면 `/fancy`도 스킬을 호출합니다. 작성한 `name`이 이미 플러그인 자체의 접두사로 시작하면 v2.1.246 이상에서 Claude Code는 접두사를 다시 추가하지 않습니다. 예를 들어 `name: my-plugin:fancy`는 여전히 `/my-plugin:fancy`가 됩니다. v2.1.216부터 v2.1.245까지 Claude Code는 `name`이 이미 접두사를 가지고 있을 때 접두사를 두 배로 했습니다.

408

409[비대화형 세션](/docs/ko/headless)에서 `help` 및 `feedback` 이름은 터미널 전용 기본 제공 명령에 대해 예약되지 않으므로 이러한 이름을 가진 플러그인 스킬은 베어 명령을 유지합니다. `/login`과 같은 다른 모든 터미널 전용 기본 제공은 해당 명령이 이러한 세션에서 실행될 수 없더라도 예약된 상태로 유지됩니다. `help` 또는 `feedback`이라는 이름의 동기화된 스킬은 여전히 건너뛰어집니다. Claude Code가 [동기화된 스킬을 건너뜁니다](#when-a-synced-skill-name-matches-another-command). 해당 이름이 다른 기본 제공 명령과 일치하는 경우 해당 명령이 실행될 수 있는지 여부와 관계없이.

287 410

288plugin 루트 경우는 `name`이 명령어 이름을 설정하는 유일한 경우입니다. skill 디렉토리가 없기 때문입니다. frontmatter에서 `name`이 설정되지 않으면 plugin의 디렉토리 이름이 대신 사용됩니다.411플러그인 루트 `SKILL.md`의 경우 스킬 디렉토리가 없으므로 `name`이 전체 마지막 세그먼트를 제공합니다. `name` 필드가 없으면 Claude Code는 플러그인의 디렉토리 이름으로 폴백합니다.

289 412

290<h4 id="available-string-substitutions">413<h4 id="available-string-substitutions">

291 사용 가능한 문자열 치환414 사용 가능한 문자열 치환

292</h4>415</h4>

293 416

294Skills는 skill 콘텐츠의 동적 값에 대한 문자열 치환을 지원합니다:417스킬은 스킬 콘텐츠의 동적 값에 대한 문자열 치환을 지원합니다.

295 418

296| 변수 | 설명 |419| 변수 | 설명 |

297| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |420| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

298| `$ARGUMENTS` | skill을 호출할 때 전달된 모든 인수. `$ARGUMENTS`가 콘텐츠에 없으면 인수가 `ARGUMENTS: <value>`로 추가됩니다. |421| `$ARGUMENTS` | 스킬을 호출할 때 전달된 모든 인수입니다. 플레이스홀더가 인수를 받지 않으면 Claude Code는 `ARGUMENTS: <value>`를 스킬 콘텐츠 끝에 추가합니다. [스킬에 인수 전달](#pass-arguments-to-skills)을 참조하세요. |

300| `$N` | `$ARGUMENTS[N]`의 약자(예: `$0`은 첫 번째 인수, `$1`은 두 번째 인수). |423| `$N` | `$0`(첫 번째 인수) 또는 `$1`(두 번째 인수)과 같이 `$ARGUMENTS[N]`의 약자입니다. |

301| `$name` | [`arguments`](#frontmatter-reference) frontmatter 목록에서 선언된 명명된 인수. 이름은 순서대로 위치에 매핑되므로, `arguments: [issue, branch]`를 사용하면 플레이스홀더 `$issue`는 첫 번째 인수로 확장되고 `$branch`는 두 번째 인수로 확장됩니다. |424| `$name` | [`arguments`](#frontmatter-reference) 프론트매터 목록에 선언된 명명된 인수입니다. 이름은 순서대로 위치에 매핑되므로 `arguments: [issue, branch]`를 사용하면 플레이스홀더 `$issue`는 첫 번째 인수로 확장되고 `$branch`는 두 번째 인수로 확장됩니다. |

302| `${CLAUDE_SESSION_ID}` | 현재 세션 ID. 로깅, 세션별 파일 생성 또는 skill 출력을 세션과 연관시키는 데 유용합니다. |425| `${CLAUDE_SESSION_ID}` | 현재 세션 ID입니다. 로깅, 세션별 파일 생성 또는 스킬 출력을 세션과 연관시키는 데 유용합니다. |

303| `${CLAUDE_EFFORT}` | 현재 노력 수준: `low`, `medium`, `high`, `xhigh`, 또는 `max`. Ultracode는 별개의 수준이 아니며 `xhigh`로 보고됩니다. 이를 사용하여 활성 노력 설정에 맞게 skill 지침을 조정합니다. |426| `${CLAUDE_EFFORT}` | 현재 노력 수준: `low`, `medium`, `high`, `xhigh`, 또는 `max`. Ultracode는 별개의 수준이 아니며 `xhigh`로 보고됩니다. 이를 사용하여 활성 노력 설정에 스킬 지침을 조정합니다. |

304| `${CLAUDE_SKILL_DIR}` | skill의 `SKILL.md` 파일을 포함하는 디렉토리. plugin skills의 경우, 이는 plugin 루트가 아닌 plugin 내의 skill 하위 디렉토리입니다. bash 주입 명령어에서 현재 작업 디렉토리와 관계없이 skill과 함께 번들된 스크립트 또는 파일을 참조하는 데 사용합니다. |427| `${CLAUDE_SKILL_DIR}` | 스킬의 `SKILL.md` 파일을 포함하는 디렉토리입니다. 플러그인 스킬의 경우 플러그인 루트가 아닌 플러그인 내 스킬의 서브디렉토리입니다. 현재 작업 디렉토리와 관계없이 스킬과 함께 번들된 스크립트 또는 파일을 참조하려면 bash 주입 명령에서 사용합니다. |

305| `${CLAUDE_PROJECT_DIR}` | 프로젝트 루트 디렉토리. 이는 [hooks](/docs/ko/hooks#reference-scripts-by-path)와 MCP 서버가 `CLAUDE_PROJECT_DIR`로 받는 것과 동일한 경로입니다. 프로젝트 로컬 스크립트 또는 파일(예: `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`)을 참조하는 데 사용하여 skill이 설치된 위치와 관계없이 사용합니다. |428| `${CLAUDE_PROJECT_DIR}` | 프로젝트 루트 디렉토리입니다. 이는 [훅](/docs/ko/hooks#reference-scripts-by-path) 및 MCP 서버가 `CLAUDE_PROJECT_DIR`로 받는 동일한 경로입니다. 스킬이 설치된 위치와 관계없이 프로젝트 로컬 스크립트 또는 파일(예: `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`)을 참조하려면 사용합니다. |

429| `${CLAUDE_PLUGIN_ROOT}` | 플러그인의 설치 디렉토리입니다. 플러그인 스킬에서만 치환됩니다. 플러그인의 스킬 간에 공유되는 리소스를 포함하여 플러그인의 어디에나 번들된 스크립트 또는 파일을 참조하려면 사용합니다. [플러그인 환경 변수](/docs/ko/plugins-reference#environment-variables)를 참조하세요. |

430| `${CLAUDE_PLUGIN_DATA}` | 플러그인의 [지속적인 데이터 디렉토리](/docs/ko/plugins-reference#persistent-data-directory)로, 플러그인 업데이트를 통해 유지됩니다. 플러그인 스킬에서만 치환됩니다. 설치된 종속성, 생성된 파일 또는 업데이트를 초과해야 하는 캐시를 참조하려면 사용합니다. |

431

432Claude Code는 `${CLAUDE_SKILL_DIR}` 및 `${CLAUDE_PROJECT_DIR}`을 두 위치에서 치환합니다. 스킬의 마크다운 콘텐츠 및 [`allowed-tools`](#frontmatter-reference) 프론트매터의 Bash 규칙입니다. 플러그인 스킬에서 Claude Code는 `${CLAUDE_PLUGIN_ROOT}` 및 `${CLAUDE_PLUGIN_DATA}`를 동일한 두 위치에서 치환합니다. 두 위치에서 동일한 변수를 사용하면 스킬이 권한 프롬프트 없이 번들된 스크립트를 실행할 수 있습니다. 다음 스킬은 패턴을 보여줍니다.

433

434```yaml theme={null}

435---

436name: render-chart

437description: Render a chart from a CSV file

438allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)

439---

440

441Run `${CLAUDE_SKILL_DIR}/scripts/render.sh <csv-file>` to render the chart.

442```

443

444이 스킬이 `~/.claude/skills/render-chart/`에 설치되면 `${CLAUDE_SKILL_DIR}`의 두 발생 모두 해당 디렉토리로 확장됩니다. `allowed-tools` 규칙은 스킬 본문이 Claude에게 실행하도록 지시하는 정확한 명령과 일치하므로 스크립트는 프롬프트 없이 실행됩니다.

306 445

307`${CLAUDE_PROJECT_DIR}` 치환은 Claude Code v2.1.196 이상이 필요합니다. skill 본문과 [`allowed-tools`](#frontmatter-reference) frontmatter 모두에 적용되므로, `Bash(${CLAUDE_PROJECT_DIR}/scripts/lint.sh *)` 같은 권한 규칙은 skill 본문이 사용하는 것과 동일한 경로로 확인됩니다.446`${CLAUDE_PROJECT_DIR}` 치환에는 Claude Code v2.1.196 이상이 필요합니다.

308 447

309인덱싱된 인수는 shell 스타일 인용을 사용하므로 다중 단어 값을 따옴표로 감싸서 단일 인수로 전달합니다. 예를 들어, `/my-skill "hello world" second`는 `$0`을 `hello world`로, `$1`을 `second`로 확장합니다. `$ARGUMENTS` 플레이스홀더는 항상 입력한 전체 인수 문자열로 확장됩니다.448인덱싱된 인수는 셸 스타일 인용을 사용하므로 다중 단어 값을 따옴표로 감싸서 단일 인수로 전달합니다. 예를 들어 `/my-skill "hello world" second`는 `$0`을 `hello world`로 확장하고 `$1`을 `second`로 확장합니다. `$ARGUMENTS` 플레이스홀더는 항상 입력한 대로 전체 인수 문자열로 확장됩니다.

310 449

311리터럴 `$`를 숫자, `ARGUMENTS` 또는 선언된 인수 이름 앞에 포함하려면(예: 산문에서 `$1.00`), 백슬래시로 이스케이프합니다: `\$1.00`. 다른 `$` 앞의 백슬래시는 변경되지 않습니다. 토큰 바로 앞의 단일 백슬래시만 이스케이프합니다. `\\$1`과 같은 이중 백슬래시는 두 백슬래시를 제자리에 두고, `$1`은 여전히 인수 값으로 확장됩니다.450해당 인수가 없는 인덱싱된 플레이스홀더(예: 하나의 인수만 전달되었을 때 `$2`)는 콘텐츠에서 변경되지 않은 상태로 유지됩니다. [`arguments`](#frontmatter-reference) 프론트매터의 일치하는 인수가 없는 명명된 플레이스홀더는 빈 문자열로 확장됩니다.

451

452`$1` 또는 `$ARGUMENTS`와 같은 텍스트를 포함하는 인수 값을 전달하면 Claude Code는 이를 리터럴 텍스트로 삽입하고 확장하지 않습니다. 예를 들어 스킬의 본문에 `Summarize $0`이 포함되어 있고 `/summarize "$ARGUMENTS from yesterday"`를 실행하면 Claude는 `Summarize $ARGUMENTS from yesterday`를 받습니다. Claude Code는 여전히 인수를 삽입한 후 `${CLAUDE_SKILL_DIR}`과 같은 `${CLAUDE_*}` 변수를 대체합니다.

453

454산문에서 `$1.00`과 같이 숫자, `ARGUMENTS` 또는 선언된 인수 이름 앞에 리터럴 `$`를 포함하려면 백슬래시로 이스케이프합니다. `\$1.00`. 다른 `$` 앞의 백슬래시는 변경되지 않은 상태로 유지됩니다. 토큰 바로 앞의 단일 백슬래시만 이스케이프합니다. `\\$1`과 같은 이중 백슬래시는 두 백슬래시를 제자리에 두고 `$1`은 여전히 인수 값으로 확장됩니다. 백슬래시 이스케이프는 이러한 인수 플레이스홀더만 다룹니다. 백슬래시는 변수가 적용되는 `${CLAUDE_*}` 변수의 치환을 방지하지 않습니다.

312 455

313**치환을 사용한 예제:**456**치환을 사용한 예제:**

314 457

327 지원 파일 추가470 지원 파일 추가

328</h3>471</h3>

329 472

330Skills는 디렉토리에 여러 파일을 포함할 수 있습니다. 이는 `SKILL.md`를 필수 항목에 집중하게 하면서 Claude가 필요할 때만 상세한 참조 자료에 액세스할 수 있게 합니다. 큰 참조 문서, API 사양 또는 예제 컬렉션은 skill이 실행될 때마다 컨텍스트에 로드될 필요가 없습니다.473스킬은 디렉토리에 여러 파일을 포함할 수 있습니다. 이렇게 하면 `SKILL.md`가 필수 사항에 집중하면서 Claude가 필요할 때만 상세 참고 자료에 액세스할 수 있습니다. 큰 참고 문서, API 사양 또는 예제 컬렉션은 스킬이 실행될 때마다 컨텍스트에 로드될 필요가 없습니다.

331 474

332```text theme={null}475```text theme={null}

333my-skill/476my-skill/

338 └── helper.py (utility script - executed, not loaded)481 └── helper.py (utility script - executed, not loaded)

339```482```

340 483

341`SKILL.md`에서 지원 파일을 참조하여 Claude가 각 파일의 내용과 로드 시기를 알 수 있도록 합니다:484`SKILL.md`에서 지원 파일을 참조하여 Claude가 각 파일의 내용과 로드 시기를 알 수 있도록 합니다.

342 485

343```markdown theme={null}486```markdown theme={null}

344## Additional resources487## Additional resources

347- For usage examples, see [examples.md](examples.md)490- For usage examples, see [examples.md](examples.md)

348```491```

349 492

350<Tip>`SKILL.md`를 500줄 이하로 유지합니다. 상세한 참조 자료를 별도 파일로 이동합니다.</Tip>493<Tip>`SKILL.md`를 500줄 이하로 유지합니다. 상세 참고 자료를 별도 파일로 이동합니다.</Tip>

351 494

352<h3 id="control-who-invokes-a-skill">495<h3 id="control-who-invokes-a-skill">

353 Skill을 호출하는 사람 제어496 스킬을 호출할 수 있는 사람 제어

354</h3>497</h3>

355 498

356기본적으로 사용자와 Claude 모두 모든 skill을 호출할 수 있습니다. `/skill-name`을 입력하여 직접 호출할 수 있고, Claude는 대화와 관련이 있을 때 자동으로 로드할 수 있습니다. 두 frontmatter 필드를 사용하여 이를 제한할 수 있습니다:499기본적으로 사용자와 Claude 모두 모든 스킬을 호출할 수 있습니다. `/skill-name`을 입력하여 직접 호출할 수 있고 Claude는 대화와 관련이 있을 때 자동으로 로드할 수 있습니다. 두 개의 프론트매터 필드를 사용하여 이를 제한할 수 있습니다.

357 500

358* **`disable-model-invocation: true`**: 사용자만 skill을 호출할 수 있습니다. 부작용이 있거나 타이밍을 제어하려는 워크플로우(예: `/commit`, `/deploy` 또는 `/send-slack-message`)에 사용합니다. Claude가 코드가 준비된 것처럼 보인다고 해서 배포하기로 결정하지 않기를 원합니다.501* **`disable-model-invocation: true`**: 사용자만 스킬을 호출할 수 있습니다. `/commit`, `/deploy` 또는 `/send-slack-message`와 같이 부작용이 있거나 타이밍을 제어하려는 워크플로우에 사용합니다. Claude가 코드가 준비된 것처럼 보이기 때문에 배포하기로 결정하지 않기를 원합니다.

359 502

360* **`user-invocable: false`**: Claude만 skill을 호출할 수 있습니다. 명령어로 실행할 수 없는 배경 지식에 사용합니다. `legacy-system-context` skill은 오래된 시스템이 어떻게 작동하는지 설명합니다. Claude는 관련이 있을 때 이를 알아야 하지만, `/legacy-system-context`는 사용자가 취할 의미 있는 작업이 아닙니다.503* **`user-invocable: false`**: Claude만 스킬을 호출할 수 있습니다. 명령으로 실행할 수 없는 배경 지식에 사용합니다. `legacy-system-context` 스킬은 이전 시스템이 어떻게 작동하는지 설명합니다. Claude는 관련이 있을 때 이를 알아야 하지만 `/legacy-system-context`는 사용자가 취할 의미 있는 작업이 아닙니다.

361 504

362이 예제는 사용자만 트리거할 수 있는 배포 skill을 생성합니다. `disable-model-invocation: true` 필드는 Claude가 자동으로 실행하는 것을 방지합니다:505이 예제는 사용자만 트리거할 수 있는 배포 스킬을 만듭니다. `disable-model-invocation: true`를 설정하면 Claude는 스킬을 자동으로 실행할 수 없습니다.

363 506

364```yaml theme={null}507```yaml theme={null}

365---508---

3764. Verify the deployment succeeded5194. Verify the deployment succeeded

377```520```

378 521

379두 필드가 호출 및 컨텍스트 로딩에 미치는 영향은 다음과 같습니다:522Claude가 어쨌든 시도하면 Claude Code는 호출을 차단하고 배포 단계를 다른 방식으로 재현하지 않도록 지시하므로 Claude가 `/deploy`를 직접 실행하도록 제안할 것으로 예상합니다.

380 523

382| :------------------------------- | :--------- | :------------ | :------------------------------------- |525

383| (기본값) | 예 | 예 | 설명은 항상 컨텍스트에 있고, 호출될 때 전체 skill이 로드됨 |526| 프론트매터 | 사용자가 호출할 수 있음 | Claude가 호출할 수 있음 | 컨텍스트에 로드되는 시기 |

384| `disable-model-invocation: true` | 예 | 아니오 | 설명은 컨텍스트에 없고, 사용자가 호출할 때 전체 skill이 로드됨 |527| :------------------------------- | :------------ | :--------------- | :---------------------------------- |

385| `user-invocable: false` | 아니오 | 예 | 설명은 항상 컨텍스트에 있고, 호출될 때 전체 skill이 로드됨 |528| (기본값) | 예 | 예 | 설명은 항상 컨텍스트에 있고, 호출될 때 전체 스킬이 로드됨 |

529| `disable-model-invocation: true` | 예 | 아니요 | 설명은 컨텍스트에 없고, 사용자가 호출할 때 전체 스킬이 로드됨 |

530| `user-invocable: false` | 아니요 | 예 | 설명은 항상 컨텍스트에 있고, 호출될 때 전체 스킬이 로드됨 |

386 531

387<Note>532<Note>

388 일반 세션에서 skill 설명은 Claude가 사용 가능한 항목을 알 수 있도록 컨텍스트에 로드되지만, 전체 skill 콘텐츠는 호출될 때만 로드됩니다. [미리 로드된 skills가 있는 Subagents](/docs/ko/sub-agents#preload-skills-into-subagents)는 다르게 작동합니다: 전체 skill 콘텐츠는 시작 시 주입됩니다.533 일반 세션에서 스킬 설명은 Claude가 사용 가능한 것을 알 수 있도록 컨텍스트에 로드되지만 전체 스킬 콘텐츠는 호출될 때만 로드됩니다. [사전 로드된 스킬이 있는 서브에이전트](/docs/ko/sub-agents#preload-skills-into-subagents)는 다르게 작동합니다. 전체 스킬 콘텐츠는 시작 시 주입됩니다.

389</Note>534</Note>

390 535

391<h3 id="skill-content-lifecycle">536<h3 id="skill-content-lifecycle">

392 Skill 콘텐츠 라이프사이클537 스킬 콘텐츠 수명 주기

393</h3>538</h3>

394 539

395사용자 또는 Claude가 skill을 호출하면, 렌더링된 `SKILL.md` 콘텐츠는 대화에 단일 메시지로 들어가고 세션의 나머지 부분 동안 그대로 유지됩니다. Claude Code는 나중의 턴에서 skill 파일을 다시 읽지 않으므로, 작업 전체에 적용되어야 하는 지침을 일회성 단계가 아닌 상시 지침으로 작성합니다.540사용자 또는 Claude가 스킬을 호출하면 렌더링된 `SKILL.md` 콘텐츠가 대화에 단일 메시지로 들어가고 이후 턴에 걸쳐 유지됩니다. 이 지속성은 스킬의 지침에 적용되며 권한에는 적용되지 않습니다. [`allowed-tools`](#pre-approve-tools-for-a-skill) 권한은 다음 메시지를 보낼 때 해제됩니다. Claude Code는 이후 턴에서 스킬 파일을 다시 읽지 않으므로 작업 전체에 적용되어야 하는 지침을 일회성 단계가 아닌 상시 지침으로 작성합니다.

396 541

397렌더링된 콘텐츠가 이미 컨텍스트에 있는 복사본과 동일한 skill을 Claude가 다시 호출할 때, Claude Code는 콘텐츠의 두 번째 복사본 대신 skill이 이미 로드되었다는 짧은 메모를 추가합니다. 렌더링된 콘텐츠가 다를 때(인수가 변경되었거나 [동적 컨텍스트](#inject-dynamic-context) 명령어가 새로운 출력을 생성했기 때문에), Claude Code는 전체 콘텐츠를 다시 추가합니다. v2.1.202 이전에는 모든 재호출이 skill의 지침의 또 다른 전체 복사본을 추가했습니다.542Claude가 렌더링된 콘텐츠가 이미 컨텍스트에 있는 복사본과 동일한 스킬을 다시 호출할 때 Claude Code는 스킬이 이미 로드되었다는 짧은 메모를 추가합니다. 인수가 변경되었거나 [동적 컨텍스트](#inject-dynamic-context) 명령이 새 출력을 생성했기 때문에 렌더링된 콘텐츠가 다를 때 Claude Code는 전체 콘텐츠를 다시 추가합니다.

398 543

399[자동 압축](/docs/ko/how-claude-code-works#when-context-fills-up)은 토큰 예산 내에서 호출된 skills를 전달합니다. 대화가 요약되어 컨텍스트를 확보하면, Claude Code는 요약 후 각 skill의 가장 최근 호출을 다시 첨부하여 처음 5,000토큰을 유지합니다. 다시 첨부된 skills는 25,000토큰의 결합 예산을 공유합니다. Claude Code는 가장 최근에 호출된 skill부터 시작하여 이 예산을 채우므로, 한 세션에서 많은 skills를 호출한 경우 압축 후 이전 skills가 완전히 삭제될 수 있습니다.544[자동 압축](/docs/ko/how-claude-code-works#when-context-fills-up)은 토큰 예산 내에서 호출된 스킬을 전달합니다. 대화가 컨텍스트를 확보하기 위해 요약될 때 Claude Code는 각 스킬의 처음 5,000토큰을 유지하면서 가장 최근의 각 스킬 호출을 다시 첨부합니다. 다시 첨부된 스킬은 25,000토큰의 결합 예산을 공유합니다. Claude Code는 가장 최근에 호출된 스킬부터 시작하여 이 예산을 채우므로 한 세션에서 많은 스킬을 호출한 경우 압축 후 이전 스킬이 완전히 삭제될 수 있습니다.

400 545

401skill이 첫 번째 응답 후 동작에 영향을 미치지 않는 것처럼 보이면, 콘텐츠는 일반적으로 여전히 존재하며 모델이 다른 도구나 접근 방식을 선택하고 있습니다. skill의 `description` 및 지침을 강화하여 모델이 계속 선호하도록 하거나, [hooks](/docs/ko/hooks)를 사용하여 동작을 결정론적으로 적용합니다. skill이 크거나 그 후에 다른 여러 skills를 호출한 경우, 압축 후 전체 콘텐츠를 복원하려면 다시 호출합니다.546스킬이 첫 번째 응답 후 동작에 영향을 미치지 않는 것처럼 보이면 콘텐츠는 일반적으로 여전히 존재하며 모델이 다른 도구나 접근 방식을 선택하고 있습니다. 스킬의 `description` 및 지침을 강화하여 모델이 계속 선호하도록 하거나 [훅](/docs/ko/hooks)을 사용하여 동작을 결정론적으로 적용합니다. 스킬이 크거나 그 후에 다른 스킬을 많이 호출한 경우 압축 후 다시 호출하여 전체 콘텐츠를 복원합니다.

402 547

403<h3 id="pre-approve-tools-for-a-skill">548<h3 id="pre-approve-tools-for-a-skill">

404 Skill에 대한 도구 사전 승인549 스킬에 대한 도구 사전 승인

405</h3>550</h3>

406 551

407`allowed-tools` 필드는 skill이 활성화되었을 때 나열된 도구에 대한 권한을 부여하므로 Claude는 승인을 요청하지 않고 사용할 수 있습니다. 사용 가능한 도구를 제한하지 않습니다: 모든 도구는 호출 가능하게 유지되며, [권한 설정](/docs/ko/permissions)은 나열되지 않은 도구에 대한 도구를 계속 관리합니다.552`allowed-tools` 필드는 스킬을 호출하는 턴 중에 나열된 도구에 대한 권한을 부여하므로 Claude는 승인을 요청하지 않고 사용할 수 있습니다. 다음 메시지를 보낼 때 권한이 해제되지만 스킬 콘텐츠는 [컨텍스트에 유지됩니다](#skill-content-lifecycle). 스킬을 다시 호출하면 해당 턴에 대해 다시 적용됩니다. 이는 사용 가능한 도구를 제한하지 않습니다. 모든 도구는 호출 가능하며 [권한 설정](/docs/ko/permissions)은 나열되지 않은 도구를 계속 관리합니다. 단일 턴이 아닌 전체 세션에 대해 도구를 사전 승인하려면 대신 해당 권한 설정에 허용 규칙을 추가합니다.

408 553

409프로젝트의 `.claude/skills/` 디렉토리에 체크인된 skills의 경우, `allowed-tools`는 해당 폴더에 대한 작업 공간 신뢰 대화를 수락한 후 적용되며, `.claude/settings.json`의 권한 규칙과 동일합니다. 프로젝트 skills를 신뢰하기 전에 검토하세요. skill은 자신에게 광범위한 도구 액세스 권한을 부여할 수 있습니다.554작업 공간 신뢰는 이 필드를 제어하지 않습니다. Claude Code는 프로젝트 스킬의 `allowed-tools`를 사용자 또는 Claude가 스킬을 호출할 때마다 적용합니다. 이는 신뢰한 적이 없는 폴더에서 `-p` 실행을 포함합니다. 스킬은 자신에게 광범위한 도구 액세스를 부여할 수 있으므로 리포지토리에 체크인된 스킬의 `allowed-tools`를 Claude Code를 실행하기 전에 검토합니다.

410 555

411이 skill은 skill을 호출할 때마다 Claude가 승인을 요청하지 않고 git 명령어를 실행할 수 있게 합니다:556이 스킬을 호출할 때마다 Claude가 승인을 요청하지 않고 git 명령을 실행할 수 있습니다.

412 557

413```yaml theme={null}558```yaml theme={null}

414---559---

419---564---

420```565```

421 566

422skill이 활성화되었을 때 Claude의 사용 가능한 풀에서 도구를 제거하려면, skill의 frontmatter에서 `disallowed-tools`에 나열합니다. 다음 메시지를 보낼 때 제한이 해제됩니다. 모든 skills 및 프롬프트에서 도구를 차단하려면, [권한 설정](/docs/ko/permissions)에 거부 규칙을 추가합니다.567스킬이 활성화되는 동안 Claude의 사용 가능한 도구 풀에서 도구를 제거하려면 스킬의 프론트매터에서 `disallowed-tools`에 나열합니다. 다음 메시지를 보낼 때 제한이 해제됩니다. 거부 규칙과 마찬가지로 다른 도구가 남아 있는 동안 이 필드는 [`EndConversation`](/docs/ko/tools-reference#endconversation-tool-behavior)을 제거할 수 없습니다. 모든 스킬 및 프롬프트에서 도구를 차단하려면 [권한 설정](/docs/ko/permissions)에 거부 규칙을 추가합니다.

423 568

424<h3 id="pass-arguments-to-skills">569<h3 id="pass-arguments-to-skills">

425 Skills에 인수 전달570 스킬에 인수 전달

426</h3>571</h3>

427 572

428사용자와 Claude 모두 skill을 호출할 때 인수를 전달할 수 있습니다. 인수는 `$ARGUMENTS` 플레이스홀더를 통해 사용 가능합니다.573사용자와 Claude 모두 스킬을 호출할 때 인수를 전달할 수 있습니다. 인수는 `$ARGUMENTS` 플레이스홀더를 통해 사용 가능합니다.

429 574

430이 skill은 GitHub 이슈를 번호로 수정합니다. `$ARGUMENTS` 플레이스홀더는 skill 이름 뒤에 오는 모든 것으로 대체됩니다:575이 스킬은 번호로 GitHub 문제를 수정합니다. `$ARGUMENTS` 플레이스홀더는 스킬 이름 뒤에 오는 모든 것으로 대체됩니다.

431 576

432```yaml theme={null}577```yaml theme={null}

433---578---

447 592

448`/fix-issue 123`을 실행하면 Claude는 "Fix GitHub issue 123 following our coding standards..."를 받습니다.593`/fix-issue 123`을 실행하면 Claude는 "Fix GitHub issue 123 following our coding standards..."를 받습니다.

449 594

450인수를 사용하여 skill을 호출하지만 skill에 `$ARGUMENTS`가 포함되지 않으면, Claude Code는 `ARGUMENTS: <your input>`을 skill 콘텐츠의 끝에 추가하므로 Claude는 여전히 입력한 내용을 봅니다.595스킬의 콘텐츠에서 플레이스홀더가 인수를 받지 않으면 Claude Code는 `ARGUMENTS: <your input>`을 스킬 콘텐츠 끝에 추가하므로 Claude는 여전히 입력한 내용을 봅니다. 플레이스홀더는 `$ARGUMENTS`, `$1`과 같은 인덱싱된 형식 또는 명명된 인수입니다. 위치에 인수가 없는 인덱싱된 플레이스홀더는 리터럴 텍스트로 유지되며 하나를 받는 것으로 계산되지 않습니다. 명명된 플레이스홀더는 위치에 인수가 없어도 계산됩니다. 빈 문자열로 확장되기 때문입니다.

451 596

452한 메시지의 시작 부분에 여러 skills를 스택할 수도 있습니다. v2.1.199부터는 `/code-review /fix-issue 123`을 입력하면 두 skill이 모두 로드되고 뒤따르는 텍스트 `123`이 각각에 `$ARGUMENTS`로 전달됩니다. 이전 버전에서는 첫 번째 skill만 로드되고 `/fix-issue 123`을 리터럴 인수 텍스트로 받았습니다.597한 메시지의 시작 부분에 여러 스킬을 스택할 수도 있습니다. ` /write-tests /fix-issue 123`을 입력하면 두 스킬이 모두 로드되고 후행 텍스트 `123`이 각각에 `$ARGUMENTS`로 전달됩니다. v2.1.199 이전에는 첫 번째 스킬만 로드되고 `/fix-issue 123`을 리터럴 인수 텍스트로 받았습니다.

453 598

454Claude Code는 첫 번째 skill과 그 뒤에 스택된 최대 5개의 skill을 확장합니다. 확장은 인라인 사용자 호출 가능 skill이 아닌 첫 번째 토큰에서 중지되므로, [forked subagent](#run-skills-in-a-subagent)로 실행되는 skill이나 인수 자체가 `/loop`와 같은 slash 명령어로 시작할 수 있는 skill도 거기서 끝나고, 그 토큰과 그 뒤의 모든 것이 모든 확장된 skill에 대한 인수 텍스트가 됩니다.599Claude Code는 첫 번째 스킬과 그 뒤에 스택된 최대 5개를 확장합니다. 확장은 인라인 사용자 호출 가능 스킬이 아닌 첫 번째 토큰에서 중지되므로 [포크된 서브에이전트](#run-skills-in-a-subagent)로 실행되는 스킬(예: [`/code-review`](/docs/ko/code-review#review-a-diff-locally)) 또는 인수 자체가 슬래시 명령으로 시작할 수 있는 스킬(예: `/loop`)도 거기서 끝납니다. 해당 토큰 및 그 뒤의 모든 것이 확장된 모든 스킬의 인수 텍스트가 됩니다. v2.1.218부터 `/code-review`는 포크된 서브에이전트로 실행됩니다. 이전 버전에서는 인라인으로 실행되고 스택되었습니다.

455 600

456위치별로 개별 인수에 액세스하려면 `$ARGUMENTS[N]` 또는 더 짧은 `$N`을 사용합니다:601위치별로 개별 인수에 액세스하려면 `$ARGUMENTS[N]` 또는 더 짧은 `$N`을 사용합니다.

457 602

458```yaml theme={null}603```yaml theme={null}

459---604---

460name: migrate-component605name: migrate-component

461description: Migrate a component from one framework to another606description: Migrate a component from one language to another

462---607---

463 608

464Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].609Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].

465Preserve all existing behavior and tests.610Preserve all existing behavior and tests.

466```611```

467 612

468`/migrate-component SearchBar React Vue`를 실행하면 `$ARGUMENTS[0]`을 `SearchBar`로, `$ARGUMENTS[1]`을 `React`로, `$ARGUMENTS[2]`를 `Vue`로 대체합니다. `$N` 약자를 사용하는 동일한 skill:613`/migrate-component SearchBar JavaScript TypeScript`를 실행하면 `$ARGUMENTS[0]`을 `SearchBar`로, `$ARGUMENTS[1]`을 `JavaScript`로, `$ARGUMENTS[2]`를 `TypeScript`로 대체합니다. `$N` 약자를 사용하는 동일한 스킬:

469 614

470```yaml theme={null}615```yaml theme={null}

471---616---

472name: migrate-component617name: migrate-component

473description: Migrate a component from one framework to another618description: Migrate a component from one language to another

474---619---

475 620

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

485 동적 컨텍스트 주입630 동적 컨텍스트 주입

486</h3>631</h3>

487 632

488`` !`<command>` `` 구문은 skill 콘텐츠가 Claude로 전송되기 전에 shell 명령어를 실행합니다. 명령어 출력이 플레이스홀더를 대체하므로 Claude는 명령어 자체가 아닌 실제 데이터를 받습니다.633`` !`<command>` `` 구문은 스킬 콘텐츠가 Claude에 전송되기 전에 셸 명령을 실행합니다. 명령 출력이 플레이스홀더를 대체하므로 Claude는 명령 자체가 아닌 실제 데이터를 받습니다. Claude Code는 스킬이 [claude.ai 계정에서 동기화될 때](#how-claude-code-handles-the-body-of-a-synced-skill) 이러한 명령을 머신에서 실행하지 않습니다.

489 634

490이 skill은 GitHub CLI를 사용하여 라이브 PR 데이터를 가져와 pull request를 요약합니다. `` !`gh pr diff` `` 및 기타 명령어가 먼저 실행되고, 출력이 프롬프트에 삽입됩니다:635이 스킬은 GitHub CLI를 사용하여 라이브 PR 데이터를 가져와 풀 요청을 요약합니다. `` !`gh pr diff` `` 및 기타 명령이 먼저 실행되고 해당 출력이 프롬프트에 삽입됩니다:

491 636

492```yaml theme={null}637```yaml theme={null}

493---638---

507Summarize this pull request...652Summarize this pull request...

508```653```

509 654

510이 skill이 실행될 때:655치환은 원본 파일에 대해 한 번만 실행됩니다. 명령 출력은 일반 텍스트로 삽입되며 추가 `` !`<command>` `` 플레이스홀더에 대해 다시 스캔되지 않으므로 명령은 나중의 패스를 위해 플레이스홀더를 내보낼 수 없습니다.

~~511~~

5121. 각 `` !`<command>` ``가 즉시 실행됩니다(Claude가 보기 전에).

5132. 출력이 skill 콘텐츠의 플레이스홀더를 대체합니다.

5143. Claude는 실제 PR 데이터가 있는 완전히 렌더링된 프롬프트를 받습니다.

515 656

516이는 전처리이며, Claude가 실행하는 것이 아닙니다. Claude는 최종 결과만 봅니다.657인라인 형식은 `!`이 줄의 시작 또는 공백 직후에 나타날 때만 인식됩니다. `!`이 `` KEY=!`cmd` ``처럼 다른 문자 뒤에 오면 플레이스홀더는 리터럴 텍스트로 남고 명령은 실행되지 않습니다.

517 658

518대체는 원본 파일에 대해 한 번 실행됩니다. 명령어 출력은 일반 텍스트로 삽입되며 추가 `` !`<command>` `` 플레이스홀더에 대해 다시 스캔되지 않으므로, 명령어는 나중의 패스에서 확장할 플레이스홀더를 내보낼 수 없습니다.659여러 줄 명령의 경우 인라인 형식 대신 ` ```! `로 열린 펜스 코드 블록을 사용합니다:

~~519~~

520인라인 형식은 `!`이 줄의 시작 또는 공백 직후에 나타날 때만 인식됩니다. `!`이 `` KEY=!`cmd` ``처럼 다른 문자 뒤에 오면, 플레이스홀더는 리터럴 텍스트로 남겨지고 명령어는 실행되지 않습니다.

~~521~~

522다중 라인 명령어의 경우, 인라인 형식 대신 ` ```! `로 열린 펜스 코드 블록을 사용합니다:

523 660

524````markdown theme={null}661````markdown theme={null}

525## Environment662## Environment

526```!663```!

527node --version664node --version

528npm --version

529git status --short665git status --short

530```666```

531````667````

532 668

533사용자, 프로젝트, 플러그인 또는 [추가 디렉토리](#skills-from-additional-directories) 소스의 skills 및 사용자 정의 명령어에 대해 이 동작을 비활성화하려면, [설정](/docs/ko/settings)에서 `"disableSkillShellExecution": true`를 설정합니다. 각 명령어는 실행되는 대신 `[shell command execution disabled by policy]`로 대체됩니다. 번들 및 관리 skills는 영향을 받지 않습니다. 이 설정은 사용자가 재정의할 수 없는 [관리 설정](/docs/ko/permissions#managed-settings)에서 가장 유용합니다.669사용자, 프로젝트, 플러그인 또는 [additional-directory](#skills-from-additional-directories) 소스의 스킬 및 사용자 정의 명령에 대해 이 동작을 비활성화하려면 [settings](/docs/ko/settings)에서 `"disableSkillShellExecution": true`를 설정합니다. 각 명령은 실행되는 대신 `[shell command execution disabled by policy]`로 대체됩니다. 번들된 스킬과 관리되는 스킬은 영향을 받지 않습니다. 이 설정은 사용자가 재정의할 수 없는 [managed settings](/docs/ko/managed-settings)에서 가장 유용합니다.

670

671Claude Code는 [claude.ai 계정에서 동기화된](#how-synced-skills-behave) 스킬에 나타나는 이러한 명령을 머신에서 절대 실행하지 않습니다. 이 설정과 관계없이 [Claude Code가 동기화된 스킬의 본문을 처리하는 방법](#how-claude-code-handles-the-body-of-a-synced-skill)은 각 종류의 세션에서 Claude가 명령 대신 받는 것을 설명합니다.

534 672

535<Tip>673<Tip>

536 skill에서 더 깊은 추론을 요청하려면 skill 콘텐츠의 어디든 `ultrathink`를 포함합니다. [일회성 깊은 추론을 위해 ultrathink 사용](/docs/ko/model-config#use-ultrathink-for-one-off-deep-reasoning)을 참조하세요.674 스킬이 실행될 때 더 깊은 추론을 요청하려면 스킬 콘텐츠의 어디든지 `ultrathink`를 포함합니다. [일회성 깊은 추론을 위해 ultrathink 사용](/docs/ko/model-config#use-ultrathink-for-one-off-deep-reasoning)을 참조합니다.

537</Tip>675</Tip>

538 676

677<h4 id="how-injected-commands-run">

678 주입된 명령이 실행되는 방식

679</h4>

680

681Claude Code는 스킬의 프론트매터에 있는 `shell` 키와 사용자 환경에서 스킬의 주입된 명령을 실행할 도구를 선택합니다. 모든 조합은 Bash 도구 또는 PowerShell 도구를 통해 명령을 실행하며, 호출을 완전히 실패하게 하는 하나의 조합을 제외합니다:

682

683* `shell: powershell`, [PowerShell 도구](/docs/ko/tools-reference#powershell-tool)가 활성화된 경우: 명령은 PowerShell 도구를 통해 실행됩니다.

684* `shell: bash` (bash를 사용할 수 없는 경우): 명령이 실행되기 전에 호출이 실패합니다. 이는 Git Bash가 없는 Windows에서 발생합니다. Claude Code는 ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``를 표시합니다.

685* 기타 모든 조합: bash를 사용할 수 있을 때 명령은 Bash 도구를 통해 실행됩니다. 사용할 수 없을 때는 PowerShell 도구를 통해 실행됩니다.

686

687두 도구 모두 Claude의 자체 셸 명령을 실행하는 것과 동일한 방식으로 명령을 실행합니다. 이들은 작업 디렉토리, 타임아웃 및 출력 처리를 공유합니다:

688

689* **작업 디렉토리**: Claude Code는 각 명령을 세션 셸의 현재 작업 디렉토리에서 실행합니다. Claude가 `cd`를 실행할 때 해당 디렉토리가 이동합니다. 매번 동일하게 확인되어야 하는 경로에서 [`${CLAUDE_SKILL_DIR}` 또는 `${CLAUDE_PROJECT_DIR}`](#available-string-substitutions)을 사용합니다.

690* **stderr**: 기본 `bash` 셸을 사용하면 Claude Code는 stderr를 stdout으로 병합합니다. 명령이 stderr에 쓰는 모든 것이 주입된 텍스트에 나타납니다.

691* **타임아웃**: 각 명령은 Bash 도구의 기본 2분 [타임아웃](/docs/ko/tools-reference#timeout-and-output-limits) 아래에서 실행됩니다. Bash 도구가 [시간 초과된 명령을 백그라운드로 이동](/docs/ko/tools-reference#background-commands)할 때 스킬은 여전히 렌더링됩니다. 주입된 텍스트는 이동을 보고하고 백그라운드 작업과 명령의 출력을 수집하는 파일의 이름을 지정합니다. 명령이 Bash 도구가 절대 자동으로 백그라운드하지 않는 명령인 경우 Claude Code는 타임아웃에서 이를 종료합니다. 이 실패는 [호출을 중단합니다](#when-an-injected-command-fails).

692* **출력 크기**: Bash 도구의 인라인 상한을 초과하는 출력은 잘린 텍스트가 아닌 파일 경로와 짧은 미리보기로 도착합니다. [출력 제한](/docs/ko/tools-reference#output-limits)은 상한과 각 경계를 조정하는 방법을 다룹니다.

693

694PowerShell 도구는 실행하는 명령에 동일한 타임아웃, 백그라운드 처리 및 출력 상한 동작을 적용합니다. 해당 세부 사항은 [PowerShell 도구](/docs/ko/tools-reference#powershell-tool) 섹션을 참조합니다.

695

696<h4 id="when-an-injected-command-fails">

697 주입된 명령이 실패할 때

698</h4>

699

700실패한 명령은 자신의 플레이스홀더뿐만 아니라 전체 스킬 호출을 중단합니다. Claude는 해당 호출에 대한 스킬 콘텐츠를 절대 보지 않습니다. 중단은 `Shell command failed for pattern "..."`를 표시합니다. 오류 메시지는 `[stderr]` 아래의 명령 출력을 포함합니다.

701

702기본 `bash` 셸을 사용하면 0이 아닌 종료 코드는 실패로 계산됩니다. 하나의 예외가 적용됩니다: Claude Code는 [검색 및 비교 명령](/docs/ko/tools-reference#output-limits)에서 종료 코드 1을 정상 결과로 취급하고 해당 출력을 주입합니다. 종료 코드 2 이상은 이러한 명령에 대해서도 실패합니다.

703

704어떤 명령이 예외를 받는지는 셸에 따라 다릅니다:

705

706* 기본 `bash` 셸: [출력 제한](/docs/ko/tools-reference#output-limits) 아래에 나열된 명령

707* `shell: powershell`, PowerShell 도구가 활성화된 경우: `grep` 및 `git diff`를 포함하지만 `find` 또는 `diff`는 포함하지 않는 [다른 집합](/docs/ko/tools-reference#shell-selection-in-settings-hooks-and-skills)

708

709기본 `bash` 셸을 사용하면 0이 아닌 종료를 예상하는 다른 명령에 `|| true`를 추가합니다. 문제를 찾을 때 1을 종료하는 검사 스크립트가 한 예입니다.

710

711주입된 명령은 절대 권한을 요청하지 않습니다. 명령의 권한 확인이 허용 이외의 것을 반환하면 Claude Code는 호출을 중단합니다. 여기에는 일반적으로 요청할 규칙이 포함됩니다. 중단은 `Shell command permission check failed for pattern "..."`를 표시합니다.

712

713일치하지 않는 명령이 여기서 중단되지 않도록 하려면 [`allowed-tools`](#pre-approve-tools-for-a-skill)로 미리 승인합니다. 일치하는 요청 또는 거부 규칙은 `allowed-tools`와 관계없이 호출을 중단합니다. [권한 관리](/docs/ko/permissions#manage-permissions)를 참조합니다.

714

539<h3 id="run-skills-in-a-subagent">715<h3 id="run-skills-in-a-subagent">

540 Subagent에서 Skills 실행716 서브에이전트에서 스킬 실행

541</h3>717</h3>

542 718

543skill을 격리 상태에서 실행하려면 frontmatter에 `context: fork`를 추가합니다. skill 콘텐츠는 subagent를 구동하는 프롬프트가 됩니다. 대화 기록에 액세스할 수 없습니다.719스킬을 격리된 상태에서 실행하려면 프론트매터에 `context: fork`를 추가합니다. 스킬 콘텐츠는 서브에이전트를 구동하는 프롬프트가 됩니다. 대화 기록에 액세스할 수 없습니다.

720

721포크된 서브에이전트는 [백그라운드](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에서 실행됩니다: 실행되는 동안 계속 작업하고 완료되면 결과가 대화에 도착합니다. 프론트매터에서 `background: false`를 설정하여 대신 스킬을 호출한 턴에서 결과를 기다립니다. v2.1.218 이전에는 포크된 스킬이 항상 완료될 때까지 턴을 차단했습니다.

722

723Claude Code는 다음과 같은 경우에도 스킬이 `background: false`를 설정하지 않더라도 결과를 기다립니다:

724

725* `-p` 플래그 또는 Agent SDK를 사용한 비대화형 모드

726* [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/ko/env-vars)를 `1`로 설정할 때 (모든 다른 백그라운드 작업 기능도 끕니다)

727* 동일한 스킬의 이전 호출이 여전히 실행 중인 동안 포크된 스킬을 호출할 때

728* [예약된 작업](/docs/ko/scheduled-tasks)이 스킬을 프롬프트로 하여 실행될 때

729

730백그라운드에서 실행되는 포크는 [백그라운드 서브에이전트에 적용되는 더 좁은 도구 집합](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)으로도 실행됩니다: 스킬의 서브에이전트는 일반 에이전트 유형이므로 대화를 포크하는 서브에이전트에 대한 예외는 적용되지 않습니다. 스킬의 단계가 해당 집합 외부의 도구에 따라 다르면 `background: false`를 설정하여 전체 도구 집합을 유지합니다.

731

732백그라운드에서 실행되는 포크된 스킬은 세션의 [체크포인트](/docs/ko/checkpointing) 외부에서 편집을 적용하므로 `/rewind`는 이를 실행 취소하지 않습니다. git을 사용하여 되돌립니다.

544 733

545<Warning>734<Warning>

546 `context: fork`는 명시적 지침이 있는 skills에만 의미가 있습니다. skill에 작업 없이 "이 API 규칙을 사용하세요"와 같은 지침이 포함되어 있으면, subagent는 지침을 받지만 실행 가능한 프롬프트가 없으므로 의미 있는 출력 없이 반환됩니다.735 `context: fork`는 명시적 지침이 있는 스킬에만 의미가 있습니다. 스킬에 작업 없이 "이러한 API 규칙을 사용합니다"와 같은 지침이 포함되어 있으면 서브에이전트는 지침을 받지만 실행 가능한 프롬프트가 없으므로 의미 있는 출력 없이 반환됩니다.

547</Warning>736</Warning>

548 737

549Skills와 [subagents](/docs/ko/sub-agents)는 두 방향으로 함께 작동합니다:738스킬과 [서브에이전트](/docs/ko/sub-agents)는 두 방향으로 함께 작동합니다:

550 739

551| 접근 방식 | 시스템 프롬프트 | 작업 | 또한 로드 |740| 접근 방식 | 시스템 프롬프트 | 작업 | 또한 로드 |

552| :------------------------ | :-------------------- | :------------- | :-------------------------------------- |741| :--------------------- | :-------------- | :------------- | :--------------------------------------- |

555 744

556`context: fork`를 사용하면 skill에 작업을 작성하고 실행할 에이전트 유형을 선택합니다. 기본 제공 Explore 및 Plan 에이전트는 [컨텍스트를 작게 유지하기 위해 CLAUDE.md 및 git status를 건너뜁니다](/docs/ko/sub-agents#what-loads-at-startup). 따라서 `agent: Explore`를 사용하는 forked skill은 SKILL.md 콘텐츠와 에이전트 자체의 시스템 프롬프트만 봅니다. 역방향(skills를 참조 자료로 사용하는 사용자 정의 subagent 정의)은 [Subagents](/docs/ko/sub-agents#preload-skills-into-subagents)를 참조하세요.745`context: fork`를 사용하면 스킬에 작업을 작성하고 에이전트 유형을 선택하여 실행합니다. 기본 제공 Explore 및 Plan 에이전트는 [CLAUDE.md 및 git 상태를 건너뜁니다](/docs/ko/sub-agents#what-loads-at-startup) 컨텍스트를 작게 유지하므로 `agent: Explore`를 사용하는 포크된 스킬은 SKILL.md 콘텐츠와 에이전트의 자체 시스템 프롬프트만 봅니다. 역으로 스킬을 참조 자료로 사용하는 사용자 정의 서브에이전트를 정의하려면 [서브에이전트](/docs/ko/sub-agents#preload-skills-into-subagents)를 참조합니다.

557 746

558<h4 id="example-research-skill-using-explore-agent">747<h4 id="example-research-skill-using-explore-agent">

559 예제: Explore 에이전트를 사용하는 Research Skill748 예: Explore 에이전트를 사용하는 연구 스킬

560</h4>749</h4>

561 750

562이 skill은 forked Explore 에이전트에서 연구를 실행합니다. skill 콘텐츠는 작업이 되고, 에이전트는 코드베이스 탐색에 최적화된 읽기 전용 도구를 제공합니다:751이 스킬은 포크된 Explore 에이전트에서 연구를 실행합니다. 스킬 콘텐츠는 작업이 되고 에이전트는 코드베이스 탐색에 최적화된 읽기 전용 도구를 제공합니다:

563 752

564```yaml theme={null}753```yaml theme={null}

565---754---

5763. Summarize findings with specific file references7653. Summarize findings with specific file references

577```766```

578 767

579이 skill이 실행될 때:768이 스킬이 실행될 때:

580 769

5811. 새로운 격리된 컨텍스트가 생성됩니다.7701. 새로운 격리된 컨텍스트가 생성됩니다

5822. subagent는 skill 콘텐츠를 프롬프트로 받습니다("Research \$ARGUMENTS thoroughly...").7712. 서브에이전트는 스킬 콘텐츠를 프롬프트로 받습니다 ("Research \$ARGUMENTS thoroughly...")

5833. `agent` 필드는 실행 환경(모델, 도구 및 권한)을 결정합니다.7723. `agent` 필드는 실행 환경 (모델, 도구 및 권한)을 결정합니다

5844. 결과는 요약되어 주 대화로 반환됩니다.7734. 서브에이전트는 결과를 요약하고 완료되면 주 대화에 반환합니다

585 774

586`agent` 필드는 사용할 subagent 구성을 지정합니다. 옵션에는 기본 제공 에이전트(`Explore`, `Plan`, `general-purpose`) 또는 `.claude/agents/`의 모든 사용자 정의 subagent가 포함됩니다. 생략하면 `general-purpose`를 사용합니다.775`agent` 필드는 사용할 서브에이전트 구성을 지정합니다. 옵션에는 기본 제공 에이전트 (`Explore`, `Plan`, `general-purpose`) 또는 `.claude/agents/`의 모든 사용자 정의 서브에이전트가 포함됩니다. 생략하면 `general-purpose`를 사용합니다.

587 776

588<h3 id="restrict-claude’s-skill-access">777<h3 id="restrict-claude’s-skill-access">

589 Claude의 Skill 액세스 제한778 Claude의 스킬 액세스 제한

590</h3>779</h3>

591 780

592기본적으로 Claude는 `disable-model-invocation: true`가 설정되지 않은 모든 skill을 호출할 수 있습니다. `allowed-tools`를 정의하는 Skills는 skill이 활성화되었을 때 사용자별 승인 없이 Claude에게 이러한 도구에 대한 액세스를 부여합니다. [권한 설정](/docs/ko/permissions)은 여전히 다른 모든 도구에 대한 기본 승인 동작을 관리합니다. `/init`, `/review`, `/security-review`를 포함한 몇 가지 기본 제공 명령어도 Skill 도구를 통해 사용 가능합니다. `/compact`와 같은 다른 기본 제공 명령어는 그렇지 않습니다.781기본적으로 Claude는 `disable-model-invocation: true`가 설정되지 않은 모든 스킬을 호출할 수 있습니다. `allowed-tools`를 정의하는 스킬은 스킬을 호출하는 턴 동안 Claude에게 사용자별 승인 없이 해당 도구에 대한 액세스를 부여합니다. 승인은 다음 메시지를 보낼 때 지워집니다. [권한 설정](/docs/ko/permissions)은 여전히 다른 모든 도구에 대한 기본 승인 동작을 관리합니다. `/init` 및 `/security-review`를 포함한 몇 가지 기본 제공 명령도 스킬 도구를 통해 사용할 수 있습니다. `/compact`와 같은 다른 기본 제공 명령은 그렇지 않습니다.

593 782

594Claude가 호출할 수 있는 skills를 제어하는 세 가지 방법:783Claude가 호출할 수 있는 스킬을 제어하는 세 가지 방법:

595 784

~~596**`/permissions`에서 Skill 도구를 거부하여 모든 skills를 비활성화합니다:**~~785**스킬 도구를 `/permissions`에서 거부하여 모든 스킬 비활성화**:

597 786

598```text theme={null}787```text theme={null}

599# Add to deny rules:788# Add to deny rules:

600Skill789Skill

601```790```

602 791

603**[권한 규칙](/docs/ko/permissions)을 사용하여 특정 skills를 허용하거나 거부합니다:**792**[권한 규칙](/docs/ko/permissions)을 사용하여 특정 스킬 허용 또는 거부**:

604 793

605```text theme={null}794```text theme={null}

606# Allow only specific skills795# Allow only specific skills

611Skill(deploy *)800Skill(deploy *)

612```801```

613 802

614권한 구문: 정확한 일치는 `Skill(name)`, 모든 인수를 사용한 접두사 일치는 `Skill(name *)`.803권한 구문: 정확한 일치의 경우 `Skill(name)`, 모든 인수를 사용한 접두사 일치의 경우 `Skill(name *)`.

804

805`deny` 규칙이 스킬의 자체 이름이 아닌 별칭 또는 정규화되지 않은 이름을 지정하면 Claude Code는 여전히 스킬을 차단합니다: `Skill(review)`를 사용하면 번들된 `/code-review`를 `/review` 별칭을 통해 차단하고, `Skill(deploy)`를 사용하면 [중첩된 스킬](#where-skills-live)을 `apps/web:deploy`로 나열된 정규화되지 않은 이름을 통해 차단합니다. v2.1.260 이전에는 Claude Code가 deny 규칙이 정규화되지 않은 이름만 지정할 때 정규화된 이름 아래에 나열된 중첩된 스킬을 차단하지 않았습니다.

806

807Claude Code는 `allow` 규칙을 스킬의 자체 이름과 Claude의 호출에서의 이름에 대해서만 일치시킵니다.

615 808

616**개별 skills를 숨기기** - frontmatter에 `disable-model-invocation: true`를 추가합니다. 이는 Claude의 컨텍스트에서 skill을 완전히 제거합니다.809**프론트매터에 `disable-model-invocation: true`를 추가하여 개별 스킬 숨기기**. 이는 Claude의 컨텍스트에서 스킬을 제거합니다.

617 810

618<Note>811<Note>

619 `user-invocable` 필드는 메뉴 가시성만 제어하고 Skill 도구 액세스는 제어하지 않습니다. 프로그래밍 방식 호출을 차단하려면 `disable-model-invocation: true`를 사용합니다.812 `user-invocable: false`를 사용하면 스킬을 호출할 수 없지만 Claude는 여전히 할 수 있습니다. Claude가 스킬 도구를 통해 호출하지 못하도록 하려면 `disable-model-invocation: true`를 설정합니다.

620</Note>813</Note>

621 814

622<h3 id="override-skill-visibility-from-settings">815<h3 id="override-skill-visibility-from-settings">

623 설정에서 Skill 가시성 재정의816 설정에서 스킬 가시성 재정의

624</h3>817</h3>

625 818

626`skillOverrides` 설정은 skill의 자체 frontmatter 대신 [설정](/docs/ko/settings)에서 skill 가시성을 제어합니다. 공유 프로젝트 리포지토리에 체크인되거나 MCP 서버에서 제공하는 것처럼 SKILL.md를 편집하고 싶지 않은 skills에 사용합니다. `/skills` 메뉴가 이를 작성합니다: skill을 강조하고 `Space`를 눌러 상태를 순환한 다음 `Enter`를 눌러 `.claude/settings.local.json`에 저장합니다.819`skillOverrides` 설정은 스킬의 자체 프론트매터 대신 [설정](/docs/ko/settings)에서 스킬 가시성을 제어합니다. SKILL.md를 편집하고 싶지 않은 스킬 (예: 공유 프로젝트 리포지토리에 체크인된 스킬)에 사용합니다. `/skills` 메뉴는 사용자를 위해 작성합니다: 스킬을 강조하고 `Space`를 눌러 상태를 순환한 다음 `Esc`를 눌러 `.claude/settings.local.json`에 저장합니다.

627 820

628각 키는 skill 이름이고 각 값은 다음 네 가지 상태 중 하나입니다:821각 키는 스킬 이름이고 각 값은 다음 네 가지 상태 중 하나입니다:

629 822

630| 값 | Claude에 나열됨 | `/` 메뉴에서 |823| 값 | Claude에 나열됨 | `/` 메뉴에서 |

631| :---------------------- | :---------- | :------- |824| :---------------------- | :---------- | :------- |

634| `"user-invocable-only"` | 숨김 | 예 |827| `"user-invocable-only"` | 숨김 | 예 |

635| `"off"` | 숨김 | 숨김 |828| `"off"` | 숨김 | 숨김 |

636 829

637`skillOverrides`에 없는 skill은 `"on"`으로 처리됩니다. 아래 예제는 한 skill을 이름으로 축소하고 다른 skill을 완전히 끕니다:830`/skills` 메뉴는 `"user-invocable-only"` 상태를 `user-only`로 레이블합니다.

831

832v2.1.199부터 `"off"`는 터미널 `/` 메뉴 외에도 [Remote Control](/docs/ko/remote-control) 클라이언트 및 [Agent SDK](/docs/ko/agent-sdk/skills#discover-available-commands) 호출자에게 광고되는 명령 목록에서 스킬을 숨깁니다. 전체 이름으로 숨겨진 스킬을 호출하면 여전히 실행하는 대신 `skillOverrides` 오류를 반환합니다.

833

834`skillOverrides`에 없는 스킬은 `"on"`으로 취급됩니다. 아래 예제는 한 스킬을 이름으로 축소하고 다른 스킬을 완전히 끕니다:

638 835

639```json theme={null}836```json theme={null}

640{837{

645}842}

646```843```

647 844

648플러그인 skills은 `skillOverrides`의 영향을 받지 않습니다. `/plugin`을 통해 이를 관리합니다.845일부 번들된 스킬에는 `/doctor`에 대한 `checkup`과 같은 별칭이 있습니다. [managed settings](/docs/ko/managed-settings)에서 또는 `--settings` 플래그로 전달하는 파일에서 별칭 아래에 `skillOverrides` 항목을 설정하면 Claude Code는 이를 별칭 뒤의 스킬에 적용합니다. 별칭을 통해 스킬을 더 제한할 수만 있으며 더 가시적으로 만들 수는 없으며, managed settings에서 스킬의 자체 이름 아래에도 항목을 설정하면 해당 항목이 우선합니다. v2.1.260 이전에는 Claude Code가 모든 설정 소스의 스킬에 별칭 아래의 항목을 적용하지 않았습니다.

846

847사용자, 프로젝트 및 로컬 설정에서 Claude Code는 스킬 이름에 대해서만 항목을 일치시킵니다. 거기서 `review`에 대한 항목을 설정하면 `/review` 별칭을 통해 번들된 `/code-review`가 아닌 `review`라는 스킬에 적용됩니다.

848

849플러그인 스킬은 `skillOverrides`의 영향을 받지 않습니다. `/plugin`을 통해 이를 관리합니다.

850

851<h3 id="find-unused-skills">

852 사용하지 않는 스킬 찾기

853</h3>

854

855[스킬 목록](#skill-descriptions-are-cut-short)의 모든 스킬은 Claude가 절대 사용하지 않더라도 모든 턴에서 컨텍스트에 추가됩니다. `/skill-doctor`를 실행하여 각 스킬의 비용과 사용 빈도를 확인하고 어떤 스킬을 끌지 결정합니다. 대화형 세션에서 보고서는 `/plugin` 관리자의 **Stats** 탭에서 열립니다. `-p`를 사용한 [비대화형 모드](/docs/ko/headless)에서 Claude Code는 이를 텍스트로 인쇄합니다.

856

857보고서는 번들된 스킬 및 엔터프라이즈 스킬을 제외한 세션의 스킬을 다룹니다. 목록에서 절대 호출되지 않은 스킬에 플래그를 지정하고 끌 위치를 알려줍니다. 끌 위치를 알려주는 스킬 중에서 가장 높은 컨텍스트 비용을 가진 스킬부터 시작합니다. 보고서는 또한 최근에 사용하지 않은 플러그인을 나열합니다.

858

859`/skill-doctor`는 Claude Code v2.1.252 이상이 필요하며 [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)를 건너뛰는 세션에서는 사용할 수 없습니다. [Remote Control](/docs/ko/remote-control)에서 휴대폰 또는 브라우저를 통해 `/skill-doctor`를 실행하면 Claude Code는 [`Skill usage reports are not available on this connection.`](/docs/ko/errors#skill-usage-reports-are-not-available-on-this-connection) 대신 회신합니다. 세션이 실행 중인 머신의 터미널에서 `/skill-doctor`를 실행합니다.

649 860

650<h2 id="evaluate-and-iterate-on-a-skill">861<h2 id="evaluate-and-iterate-on-a-skill">

651 Skills 평가 및 반복862 스킬 평가 및 반복

652</h2>863</h2>

653 864

654skill이 트리거되는 것을 보는 것은 Claude가 이를 찾았다는 뜻이지, 의도한 대로 작동했다는 뜻이 아닙니다. skill이 작동하는지 알기 위해 두 가지를 별도로 측정합니다: Claude가 호출해야 하는 프롬프트에서 호출하는지 여부, 그리고 호출할 때 출력이 예상과 일치하는지 여부입니다.865스킬이 트리거되는 것을 보는 것은 Claude가 스킬을 찾았다는 의미이지, 의도한 대로 작동했다는 의미는 아닙니다. 스킬이 제대로 작동하는지 알기 위해서는 두 가지를 별도로 측정해야 합니다. Claude가 해야 할 프롬프트에서 스킬을 호출하는지 여부와 호출할 때 출력이 예상과 일치하는지 여부입니다.

655 866

656둘 다에 대한 확인은 기준선 비교입니다. 몇 가지 현실적인 프롬프트를 수집하고, skill을 사용 가능하게 한 새로운 세션에서 각각을 실행한 다음 [비활성화된](#override-skill-visibility-from-settings) 상태에서 다시 실행하고, 결과를 비교합니다. 새로운 세션이 중요합니다. skill 작성의 남은 컨텍스트가 작성된 지침의 간격을 숨기기 때문입니다.867두 가지 모두에 대한 확인은 기준선 비교입니다. 현실적인 프롬프트 몇 개를 수집하고, 스킬을 사용할 수 있는 새로운 세션에서 각각을 실행한 후 [비활성화](#override-skill-visibility-from-settings)된 상태에서 다시 실행하고 결과를 비교합니다. 새로운 세션이 중요한 이유는 스킬 작성 시 남겨진 컨텍스트가 작성된 지침의 간격을 숨길 수 있기 때문입니다.

657 868

658<h3 id="run-evals-with-skill-creator">869<h3 id="run-evals-with-skill-creator">

659 skill-creator로 evals 실행870 skill-creator로 평가 실행

660</h3>871</h3>

661 872

662[`skill-creator` 플러그인](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/skill-creator)은 Claude Code 내에서 비교 루프를 자동화합니다. 공식 마켓플레이스에서 설치합니다:873[`skill-creator` 플러그인](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/skill-creator)은 Claude Code 내에서 비교 루프를 자동화합니다. 공식 마켓플레이스에서 설치합니다:

665/plugin install skill-creator@claude-plugins-official876/plugin install skill-creator@claude-plugins-official

666```877```

667 878

668Claude Code가 플러그인을 마켓플레이스에서 찾을 수 없다고 보고하면, 마켓플레이스가 누락되었거나 오래되었습니다. `/plugin marketplace update claude-plugins-official`를 실행하여 새로 고치거나, 아직 추가하지 않았다면 `/plugin marketplace add anthropics/claude-plugins-official`를 실행합니다. 그 다음 설치를 다시 시도합니다.879설치가 실패하면 Claude Code가 보고한 메시지와 일치시킵니다:

880

881* `Marketplace "claude-plugins-official" not found`: `/plugin marketplace add anthropics/claude-plugins-official`로 마켓플레이스를 추가한 후 설치를 다시 시도합니다.

882* 플러그인이 [마켓플레이스에서 찾을 수 없음](/docs/ko/discover-plugins#install-plugins): 플러그인 이름을 확인합니다.

669 883

670설치 후 `/reload-plugins`를 실행하여 현재 세션에서 플러그인의 skills를 사용 가능하게 합니다. 그 다음 Claude에게 기존 skill을 평가하도록 요청합니다. 예를 들어 `evaluate my summarize-changes skill with skill-creator`. 플러그인은 테스트 케이스를 작성하고 루프를 실행하도록 안내합니다:884설치 요약에서 `Run /reload-plugins to activate.`를 보고하면 해당 명령을 실행하여 현재 세션에서 플러그인의 스킬을 사용할 수 있게 합니다. 그런 다음 Claude에게 기존 스킬을 평가하도록 요청합니다. 예를 들어 `evaluate my summarize-changes skill with skill-creator`입니다. 플러그인은 테스트 케이스 작성을 안내하고 루프를 실행합니다:

671 885

672* **테스트 케이스**: skill 디렉토리 내의 `evals/evals.json`에 프롬프트, 입력 파일 및 예상 동작을 저장합니다.886* **테스트 케이스**: 프롬프트, 입력 파일 및 예상 동작을 스킬 디렉토리 내 `evals/evals.json`에 저장합니다

673* **격리된 실행**: 각 테스트 케이스당 [subagent](/docs/ko/sub-agents)를 생성하므로 각 실행이 깨끗한 컨텍스트로 시작되고, 토큰 수와 기간을 기록합니다.887* **격리된 실행**: 각 테스트 케이스마다 [서브에이전트](/docs/ko/sub-agents)를 생성하여 각 실행이 깨끗한 컨텍스트로 시작되도록 하고, 토큰 수와 지속 시간을 기록합니다

674* **채점**: 각 어설션을 출력에 대해 확인하고 `grading.json`에 증거와 함께 통과 또는 실패를 작성합니다.888* **채점**: 각 어설션을 출력과 비교하고 `grading.json`에 증거와 함께 통과 또는 실패를 작성합니다

675* **벤치마크**: skill 있음 대 skill 없음에 대한 통과율, 시간 및 토큰을 `benchmark.json`에 집계하므로 토큰 및 시간 오버헤드에 대한 통과율 개선을 비교할 수 있습니다.889* **벤치마크**: 스킬 사용 여부에 따른 통과율, 시간 및 토큰을 `benchmark.json`에 집계하여 토큰 및 시간 오버헤드에 대한 통과율 개선을 비교할 수 있습니다

676* **버전 비교**: skill의 두 버전 간에 블라인드 A/B를 실행하므로 커밋하기 전에 편집이 개선인지 확인할 수 있습니다.890* **버전 비교**: 스킬의 두 버전 간에 블라인드 A/B를 실행하여 편집이 커밋하기 전에 개선 사항인지 확인할 수 있습니다

677* **설명 튜닝**: 트리거해야 하고 트리거하지 않아야 하는 프롬프트를 생성하고, 히트율을 측정하고, skill이 잘못된 요청에서 활성화될 때 설명 편집을 제안합니다.891* **설명 튜닝**: 트리거해야 하는 프롬프트와 트리거하지 않아야 하는 프롬프트를 생성하고, 히트율을 측정하고, 스킬이 잘못된 요청에서 활성화될 때 설명 편집을 제안합니다

678* **리뷰 뷰어**: 각 출력을 검사하고 다음 반복이 읽을 정성적 피드백을 기록할 수 있는 HTML 보고서를 엽니다.892* **검토 뷰어**: 각 출력을 검사하고 다음 반복이 읽을 정성적 피드백을 기록할 수 있는 HTML 보고서를 엽니다

679 893

680eval 파일 형식 및 전체 반복 워크플로우는 agentskills.io의 [Evaluating skill output quality](https://agentskills.io/skill-creation/evaluating-skills)를 참조하세요. 벤치마크 및 비교 모드의 배경은 [skill-creator 공지](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills)를 참조하세요.894평가 파일 형식 및 전체 반복 워크플로우는 agentskills.io의 [스킬 출력 품질 평가](https://agentskills.io/skill-creation/evaluating-skills)를 참조합니다. 벤치마크 및 비교 모드의 배경은 [skill-creator 공지](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills)를 참조합니다.

681 895

682<h2 id="share-skills">896<h2 id="share-skills">

683 Skills 공유897 스킬 공유

684</h2>898</h2>

685 899

686Skills는 대상에 따라 다양한 범위에서 배포할 수 있습니다:900스킬은 대상에 따라 다양한 범위에서 배포할 수 있습니다:

687 901

688* **프로젝트 skills**: `.claude/skills/`를 버전 제어에 커밋합니다.902* **프로젝트 스킬**: `.claude/skills/`를 버전 관리에 커밋합니다

689* **플러그인**: [플러그인](/docs/ko/plugins)에서 `skills/` 디렉토리를 생성합니다.903* **플러그인**: [플러그인](/docs/ko/plugins)에서 `skills/` 디렉토리를 생성합니다

690* **관리**: [관리 설정](/docs/ko/settings#settings-files)을 통해 조직 전체에 배포합니다.904* **관리형**: [관리형 설정](/docs/ko/managed-settings)을 통해 조직 전체에 배포합니다

691 905

692<h3 id="generate-visual-output">906<h3 id="generate-visual-output">

693 시각적 출력 생성907 시각적 출력 생성

694</h3>908</h3>

695 909

696Skills는 모든 언어의 스크립트를 번들하고 실행할 수 있으므로 Claude에게 단일 프롬프트로 가능한 것 이상의 기능을 제공합니다. 강력한 패턴 중 하나는 시각적 출력을 생성하는 것입니다: 브라우저에서 열리는 대화형 HTML 파일로 데이터 탐색, 디버깅 또는 보고서 생성에 사용됩니다.910스킬은 모든 언어의 스크립트를 번들로 제공하고 실행할 수 있으므로 Claude에 단일 프롬프트로는 불가능한 기능을 제공합니다. 한 가지 패턴은 시각적 출력을 생성하는 것입니다: 브라우저에서 열리는 대화형 HTML 파일로 데이터 탐색, 디버깅 또는 보고서 작성에 사용할 수 있습니다.

697 911

698이 예제는 코드베이스 탐색기를 생성합니다: 디렉토리를 확장 및 축소할 수 있는 대화형 트리 보기로, 한눈에 파일 크기를 보고, 색상으로 파일 유형을 식별할 수 있습니다.912이 예제는 코드베이스 탐색기를 생성합니다: 디렉토리를 확장 및 축소할 수 있는 대화형 트리 뷰로, 파일 크기를 한눈에 볼 수 있고 색상으로 파일 유형을 식별할 수 있습니다.

699 913

700Skill 디렉토리 생성:914스킬 디렉토리를 생성합니다:

701 915

702```bash theme={null}916```bash theme={null}

703mkdir -p ~/.claude/skills/codebase-visualizer/scripts917mkdir -p ~/.claude/skills/codebase-visualizer/scripts

704```918```

705 919

706`~/.claude/skills/codebase-visualizer/SKILL.md`에 저장합니다. 설명은 Claude에게 이 Skill을 언제 활성화할지 알려주고, 지침은 Claude에게 번들 스크립트를 실행하도록 알려줍니다. 스크립트 경로는 [`${CLAUDE_SKILL_DIR}`](#available-string-substitutions)를 사용하므로 skill이 개인, 프로젝트 또는 플러그인 수준에서 설치되었는지 여부에 관계없이 올바르게 해석됩니다:920이를 `~/.claude/skills/codebase-visualizer/SKILL.md`에 저장합니다. 설명은 Claude에게 이 스킬을 언제 활성화할지 알려주고, 지침은 Claude에게 번들된 스크립트를 실행하도록 지시합니다. 스크립트 경로는 [`${CLAUDE_SKILL_DIR}`](#available-string-substitutions)를 사용하므로 스킬이 개인, 프로젝트 또는 플러그인 수준에서 설치되었는지 여부에 관계없이 올바르게 해석됩니다:

707 921

708````yaml theme={null}922````yaml theme={null}

709---923---

734- **Directory totals**: Shows aggregate size of each folder948- **Directory totals**: Shows aggregate size of each folder

735````949````

736 950

737`~/.claude/skills/codebase-visualizer/scripts/visualize.py`에 저장합니다. 이 스크립트는 디렉토리 트리를 스캔하고 다음을 포함하는 자체 포함 HTML 파일을 생성합니다:951이를 `~/.claude/skills/codebase-visualizer/scripts/visualize.py`에 저장합니다. 이 스크립트는 디렉토리 트리를 스캔하고 다음을 포함하는 자체 포함된 HTML 파일을 생성합니다:

738 952

739* 파일 수, 디렉토리 수, 총 크기 및 파일 유형 수를 보여주는 **요약 사이드바**953* 파일 개수, 디렉토리 개수, 총 크기 및 파일 유형 수를 표시하는 **요약 사이드바**

740* 파일 유형별로 코드베이스를 분석하는 **막대 차트**(크기 기준 상위 8개)954* 파일 유형별로 코드베이스를 분석하는 **막대 차트** (크기 기준 상위 8개)

741* 디렉토리를 확장 및 축소할 수 있는 **축소 가능한 트리**로, 색상으로 코딩된 파일 유형 표시기 포함955* 디렉토리를 확장 및 축소할 수 있는 **축소 가능한 트리**로, 색상으로 구분된 파일 유형 표시기가 있습니다

742 956

743스크립트는 Python 3이 필요하지만 기본 제공 라이브러리만 사용하므로 설치할 패키지가 없습니다:957스크립트는 Python 3이 필요하지만 기본 제공 라이브러리만 사용하므로 설치할 패키지가 없습니다:

744 958

878 webbrowser.open(f'file://{out.absolute()}')1092 webbrowser.open(f'file://{out.absolute()}')

879```1093```

880 1094

881테스트하려면 모든 프로젝트에서 Claude Code를 열고 "Visualize this codebase"를 요청합니다. Claude는 스크립트를 실행하고, `codebase-map.html`을 생성하고, 브라우저에서 엽니다.1095테스트하려면 Claude Code를 모든 프로젝트에서 열고 "Visualize this codebase."라고 요청합니다. Claude가 스크립트를 실행하면 생성된 파일의 경로(예: `Generated /path/to/codebase-map.html`)를 출력하고 브라우저에서 엽니다. 브라우저가 열리지 않는 헤드리스 환경에서 작업하는 경우 출력된 경로는 스크립트가 성공했음을 확인합니다.

882 1096

883이 패턴은 모든 시각적 출력에 작동합니다: 종속성 그래프, 테스트 커버리지 보고서, API 문서 또는 데이터베이스 스키마 시각화. 번들 스크립트가 무거운 작업을 수행하는 동안 Claude는 조율을 처리합니다.1097이 패턴은 모든 시각적 출력에 적용됩니다: 종속성 그래프, 테스트 커버리지 보고서, API 문서 또는 데이터베이스 스키마 시각화입니다. 번들된 스크립트가 작업을 수행하는 동안 Claude는 오케스트레이션을 처리합니다.

884 1098

885<h2 id="troubleshooting">1099<h2 id="troubleshooting">

886 문제 해결1100 문제 해결

887</h2>1101</h2>

888 1102

889<h3 id="skill-not-triggering">1103<h3 id="skill-not-triggering">

890 Skill이 트리거되지 않음1104 스킬이 트리거되지 않음

891</h3>1105</h3>

892 1106

893Claude가 예상대로 skill을 사용하지 않는 경우:1107Claude가 예상대로 스킬을 사용하지 않는 경우:

1108

11091. 설명에 사용자가 자연스럽게 말할 만한 키워드가 포함되어 있는지 확인하세요

11102. 스킬이 `What skills are available?`에 나타나는지 확인하세요

11113. 설명과 더 가깝게 일치하도록 요청을 다시 표현해 보세요

11124. 스킬이 사용자 호출 가능한 경우 `/skill-name`으로 직접 호출하세요

894 1113

8951. 설명에 사용자가 자연스럽게 말할 키워드가 포함되어 있는지 확인합니다.1114frontmatter YAML이 잘못된 형식이면 Claude Code는 스킬 본문을 빈 메타데이터로 로드하므로 `/skill-name`은 여전히 작동하지만 Claude는 일치시킬 `description`이 없습니다. `--debug`로 실행하여 파싱 오류를 확인하세요.

8962. skill이 `What skills are available?`에 나타나는지 확인합니다.

8973. 설명과 더 가깝게 일치하도록 요청을 다시 표현해봅니다.

8984. skill이 사용자 호출 가능하면 `/skill-name`으로 직접 호출합니다.

899 1115

900frontmatter YAML이 잘못된 형식이면, Claude Code는 skill 본문을 빈 메타데이터로 로드하므로 `/skill-name`은 여전히 작동하지만 Claude는 일치시킬 `description`이 없습니다. `--debug`로 실행하여 구문 분석 오류를 확인합니다.1116frontmatter가 파싱되지 않는 `SKILL.md` 파일을 찾으려면 스킬 디렉토리에서 [`claude plugin validate`](/docs/ko/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)를 실행하세요. 예를 들어 프로젝트 스킬의 경우 `claude plugin validate .claude/skills` 또는 개인 스킬의 경우 `claude plugin validate ~/.claude/skills`입니다. Claude Code v2.1.233 이상이 필요합니다.

901 1117

902<h3 id="skill-triggers-too-often">1118<h3 id="skill-triggers-too-often">

903 Skill이 너무 자주 트리거됨1119 스킬이 너무 자주 트리거됨

904</h3>1120</h3>

905 1121

906Claude가 원하지 않을 때 skill을 사용하는 경우:1122Claude가 원하지 않을 때 스킬을 사용하는 경우:

907 1123

9081. 설명을 더 구체적으로 만듭니다.11241. 설명을 더 구체적으로 만드세요

9092. 수동 호출만 원하면 `disable-model-invocation: true`를 추가합니다.11252. 수동 호출만 원하는 경우 `disable-model-invocation: true`를 추가하세요

910 1126

911<h3 id="skill-descriptions-are-cut-short">1127<h3 id="skill-descriptions-are-cut-short">

912 Skill 설명이 잘림1128 스킬 설명이 잘려 있음

913</h3>1129</h3>

914 1130

915Claude Code는 skill 이름과 설명 목록을 컨텍스트에 로드하여 Claude가 사용 가능한 항목을 알 수 있도록 합니다. 목록에는 항상 모든 skill 이름이 포함되지만, skill이 많으면 Claude Code는 설명을 단축하여 목록의 문자 예산에 맞추며, 이는 Claude가 요청과 일치하는 데 필요한 키워드를 제거할 수 있습니다. 예산은 모델의 컨텍스트 윈도우의 1%에서 확장됩니다. 목록이 예산을 초과하면, Claude Code는 가장 적게 호출하는 skill부터 설명을 삭제하므로 가장 자주 사용하는 skill은 전체 텍스트를 유지합니다.1131Claude Code는 스킬 이름과 설명 목록을 컨텍스트에 로드하여 Claude가 사용 가능한 항목을 알 수 있도록 합니다. 목록에는 항상 모든 스킬 이름이 포함되지만 스킬이 많으면 Claude Code는 목록의 문자 예산에 맞추기 위해 설명을 단축하므로 Claude가 요청과 일치시키는 데 필요한 키워드가 제거될 수 있습니다. 예산은 모델의 컨텍스트 윈도우의 1%로 조정됩니다. 목록이 초과되면 Claude Code는 가장 적게 호출하는 스킬부터 설명을 삭제하므로 가장 자주 사용하는 스킬이 전체 텍스트를 유지합니다.

916 1132

917`/doctor`를 실행하여 목록의 컨텍스트 비용 추정치와 가장 큰 기여자를 확인합니다. 목록이 예산을 초과하면, Claude Code는 [`--debug`](/docs/ko/cli-reference#cli-flags)로 볼 수 있는 디버그 로그에 경고를 작성합니다.1133목록의 컨텍스트 비용 추정치와 가장 큰 기여자를 보려면 `/doctor`를 실행하세요. 사용하지 않는 스킬을 찾으려면 [`/skill-doctor`](#find-unused-skills)를 실행하세요. 목록이 예산을 초과하면 Claude Code는 [`--debug`](/docs/ko/cli-reference#cli-flags)로 볼 수 있는 디버그 로그에 경고를 작성합니다.

918 1134

919`/context`의 Skills 행은 예산이 적용된 후의 목록 크기를 보고하므로 모델이 수신하는 것과 일치합니다. v2.1.196 이전에는 행이 모든 설명의 전체 텍스트를 계산했으므로 구성된 예산보다 몇 배 더 큰 값을 표시할 수 있었습니다.1135`/context`의 Skills 행은 예산이 적용된 후 목록의 크기를 보고하므로 모델이 수신하는 것과 일치합니다. v2.1.196 이전에는 행이 모든 설명의 전체 텍스트를 계산했으며 구성된 예산보다 몇 배 더 큰 값을 표시할 수 있었습니다.

920 1136

921예산을 높이려면 [`skillListingBudgetFraction`](/docs/ko/settings#available-settings) 설정(예: `0.02` = 2%)을 설정하거나 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 환경 변수를 고정 문자 수로 설정합니다. 다른 skill을 위해 예산을 확보하려면 [`skillOverrides`](#override-skill-visibility-from-settings)에서 낮은 우선순위 항목을 `"name-only"`로 설정하여 설명 없이 나열되도록 합니다. 또한 소스에서 `description` 및 `when_to_use` 텍스트를 자를 수 있습니다: 주요 사용 사례를 먼저 배치합니다. 각 항목의 결합된 텍스트는 예산과 관계없이 1,536자로 제한되기 때문입니다. 이 제한은 [`skillListingMaxDescChars`](/docs/ko/settings#available-settings)로 구성할 수 있습니다.1137예산을 높이려면 [`skillListingBudgetFraction`](/docs/ko/settings-reference#skilllistingbudgetfraction) 설정(예: `0.02` = 2%) 또는 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 환경 변수를 고정 문자 수로 설정하세요. 다른 스킬을 위해 예산을 확보하려면 [`skillOverrides`](#override-skill-visibility-from-settings)에서 낮은 우선순위 항목을 `"name-only"`로 설정하여 설명 없이 나열되도록 하세요. 또한 소스에서 `description` 및 `when_to_use` 텍스트를 자르세요. 각 항목의 결합된 텍스트는 예산에 관계없이 1,536자로 제한되므로 주요 사용 사례를 먼저 배치하세요. 상한은 [`skillListingMaxDescChars`](/docs/ko/settings-reference#skilllistingmaxdescchars)로 구성할 수 있습니다.

922 1138

923<h2 id="related-resources">1139<h2 id="related-resources">

924 관련 리소스1140 관련 리소스

skills.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

Claude를 skills로 확장하기

번들된 스킬

앱 실행 및 확인

시작하기

첫 번째 skill 만들기

skill 디렉토리 만들기

SKILL.md 작성

skill 테스트

스킬이 로드되는 위치 선택

모노레포 및 하위 디렉토리에서 스킬 로드

프로젝트 외부의 디렉토리에서 스킬 로드

이름을 공유하는 스킬 해결

Cowork 및 클라우드 세션에서 스킬 사용

claude.ai에서 동기화된 스킬

동기화된 스킬이 로드되는 위치

claude.ai 계정에 대해 스킬 활성화

동기화가 켜진 비대화형 모드에서 Claude Code 실행

로컬 세션에서 스킬이 로드되는지 확인

동기화된 스킬 이름이 다른 명령과 일치할 때

Claude Code가 동기화된 스킬의 frontmatter를 처리하는 방법

Claude Code가 동기화된 스킬의 본문을 처리하는 방법

세션 중 스킬 편집

스킬 제거

스킬 구성

스킬 콘텐츠의 유형

프론트매터 참고

Claude Code 외부에서 스킬 프론트매터 사용

스킬이 명령 이름을 얻는 방법

사용 가능한 문자열 치환

지원 파일 추가

스킬을 호출할 수 있는 사람 제어

스킬 콘텐츠 수명 주기

스킬에 대한 도구 사전 승인

스킬에 인수 전달

고급 패턴

동적 컨텍스트 주입

주입된 명령이 실행되는 방식

주입된 명령이 실패할 때

서브에이전트에서 스킬 실행

예: Explore 에이전트를 사용하는 연구 스킬

Claude의 스킬 액세스 제한

설정에서 스킬 가시성 재정의

사용하지 않는 스킬 찾기

스킬 평가 및 반복

skill-creator로 평가 실행

스킬 공유

시각적 출력 생성

문제 해결

스킬이 트리거되지 않음

스킬이 너무 자주 트리거됨

스킬 설명이 잘려 있음

관련 리소스