SKILL.md 파일로 패키징됩니다. 이 페이지는 또한 Agent SDK 세션의 명령을 다룹니다.
Skills에 대한 이점, 아키텍처 및 작성 지침을 포함한 포괄적인 정보는 Agent Skills 개요를 참조하십시오.
Agent SDK와 Skills의 작동 방식
Claude Agent SDK를 사용할 때 Skills는 다음과 같이 작동합니다:- 파일 시스템 아티팩트로 정의됨: 각 Skill을
.claude/skills/<name>/SKILL.md와 같은 자신의 디렉토리에SKILL.md파일로 생성합니다 - 파일 시스템에서 로드됨: SDK는
settingSources(TypeScript) 또는setting_sources(Python)에 의해 관리되는 파일 시스템 위치에서 Skills를 로드합니다 - 자동으로 발견됨: 파일 시스템 설정이 로드되면 SDK는 시작 시 사용자 및 프로젝트 디렉토리에서 Skill 메타데이터를 발견하고, Claude가 Skill을 호출할 때 전체 콘텐츠를 로드합니다
- 모델에 의해 호출됨: Claude는 컨텍스트를 기반으로 자율적으로 사용할 시기를 선택합니다
- 사용자에 의해 호출됨: 프롬프트에서
/<name>을 전송하여 Skill을 직접 전달합니다. Agent SDK 세션의 명령을 참조하십시오 skills옵션을 통해 범위 지정됨: 발견된 Skills는 기본적으로 활성화됩니다. Skill 이름 목록,"all"또는[]를 전달하여 Claude가 호출할 수 있는 Skills를 제어합니다
agents 옵션에서 정의할 수 있으며, Skills는 디스크에 파일로 생성합니다. SDK는 Skills를 등록하기 위한 프로그래밍 API를 제공하지 않습니다.
Skills는 파일 시스템 설정 소스를 통해 발견됩니다. 기본
query() 옵션을 사용하면 SDK는 사용자 및 프로젝트 소스를 로드하므로 ~/.claude/skills/, <cwd>/.claude/skills/ 및 <cwd>의 상위 디렉토리부터 저장소 루트까지의 .claude/skills/에 있는 Skills를 사용할 수 있습니다. 프로젝트 소스는 또한 additionalDirectories(TypeScript) 또는 add_dirs(Python)를 통해 전달하는 각 디렉토리의 <dir>/.claude/skills/를 포함합니다. SDK가 해당 디렉토리를 Claude Code에 --add-dir로 전달하기 때문입니다. settingSources를 명시적으로 설정하는 경우 프로젝트 및 추가 디렉토리 Skills를 유지하려면 'project'를 포함하고 개인 Skills를 유지하려면 'user'를 포함하거나, plugins 옵션을 사용하여 특정 경로에서 Skills를 로드하십시오.Agent SDK와 함께 Skills 사용하기
query()의 skills 옵션을 설정하여 세션에서 Claude가 호출할 수 있는 Skills를 제어합니다. 생략하면 발견된 Skills가 활성화되고 Skill 도구를 사용할 수 있으며, 이는 CLI 동작과 일치합니다. "all"을 전달하여 Claude가 모든 발견된 Skill을 호출하도록 하거나, Skill 이름 목록을 전달하여 해당 Skill만 허용하거나, []를 전달하여 Claude가 어떤 Skill도 호출하지 않도록 합니다.
예를 들어 Claude가 두 개의 명명된 Skill만 호출하도록 하려면:
세션에서 Skills 설정하기
skills를 설정하면 SDK가 Skill 도구를 allowedTools에 자동으로 추가합니다. 명시적 tools 목록도 전달하는 경우 Claude가 Skills를 호출할 수 있도록 해당 목록에 "Skill"을 포함하십시오.
구성되면 Claude는 파일 시스템에서 Skills를 자동으로 발견하고 사용자의 요청과 관련이 있을 때 호출합니다.
다음 예제는 모든 발견된 Skill을 활성화하고 Skills가 일반적으로 필요로 하는 도구를 사전 승인합니다. 예제는 cwd를 프로세스의 현재 작업 디렉토리로 설정하므로 현재 디렉토리 또는 저장소 루트까지의 상위 디렉토리에 .claude/skills/ 디렉토리가 있는 프로젝트 내에서 실행하십시오:
Skills 로드 확인하기
스트림의 시작 부분 근처에서 SDK는 서브타입init이 있는 시스템 메시지를 생성합니다. 해당 skills 배열을 확인하여 Claude가 작업을 시작하기 전에 Skills가 로드되었는지 확인하십시오. 배열에는 정의한 사용자 호출 가능 Skills와 Claude Code에 포함된 번들 Skills가 포함됩니다.
배열은 사용자 호출 가능 Skills만 나열합니다. frontmatter에 user-invocable: false가 있는 Skill은 로드되고 Claude에서 사용 가능하지만 배열에 나타나지 않습니다. 배열은 세션이 발견한 것을 반영하고 skills 목록에 있는지 여부와 관계없이 동일한 Skills를 나열합니다.
특정 Skills만 허용하기
Claude가 특정 Skills만 호출하도록 하려면 해당 이름을skills 목록에 전달합니다. 이름은 SKILL.md의 name 필드 또는 Skill의 디렉토리 이름과 일치합니다. 플러그인에서 제공하는 Skills의 경우 plugin:skill을 사용합니다.
목록은 정확한 Skill 이름만 사용합니다. 항목이 정확한 이름으로 작동할 수 없으면 query()는 세션이 시작되기 전에 목록을 거부합니다. Invalid skill name error에서 이름 규칙과 각 SDK가 발생시키는 오류를 참조하십시오.
모델은 나열되지 않은 Skills를 보지 못하고 Skill 도구가 이를 거부하지만, 해당 파일은 디스크에 남아 있으며 Read 및 Bash를 통해 접근할 수 있습니다. 목록을 제한해도 이름으로 전달을 제한하지 않습니다.
모든 발견된 Skill을 호출하도록 하려면 와일드카드 대신 skills: "all"을 전달하십시오.
Agent SDK 세션의 명령
이 섹션은 SDK의 명령 문서입니다. 명령은 프롬프트에서/<name>을 전송하여 실행하는 모든 것입니다. 명령 표면의 항목은 이를 지원하는 것이 다릅니다:
- 기본 제공 명령: SDK가 실행하는 Claude Code 프로세스에 코딩된 로직을 실행합니다. 예를 들어
/compact - 번들 Skills: Claude Code에 포함된 프롬프트 아티팩트입니다. 예를 들어
/code-review - 사용자 Skills: 사용자가 작성하는 프롬프트 아티팩트이며, 각각
SKILL.md파일을 보유하는 디렉토리입니다. 사용자 호출 가능 Skill의 이름이 표면에 자동으로 조인되므로 자신의/security-check를 전달하고 기본 제공을 실행하는 것이 동일한 방식으로 작동합니다 - 사용자 정의 명령 파일: 동일한 동작을 하는 이전 아티팩트 형식이며,
.claude/commands/의 평면 Markdown 파일이며 파일 이름이 명령 이름이 됩니다. Skills는 권장되는 후속입니다
사용 가능한 명령 발견하기
SDK를 통해 대화형 터미널 없이 작동하는 명령을 전달할 수 있습니다.system/init 메시지는 slash_commands 필드의 세션에서 사용 가능한 명령을 나열합니다. /theme 및 /terminal-setup과 같이 대화형 터미널이 필요한 명령은 목록에 나타나지 않습니다. 세션이 시작될 때 필드에 액세스합니다:
.claude/commands/ 파일을 혼합합니다:
user-invocable: false가 있는 Skill은 이 목록이나 Skills 로드 확인하기의 skills 배열에 나타나지 않습니다. MCP 서버를 구성하는 세션은 또한 MCP 프롬프트를 명령으로 노출할 수 있습니다.
이름으로 명령 전달하기
프롬프트 문자열에 명령을 포함하여 일반 텍스트를 전송하는 것과 동일한 방식으로 명령을 전송합니다. 전달은skills 옵션에 따라 달라지지 않습니다. /<name>을 전송하면 skills 목록이 이를 생략할 때도 사용자 호출 가능 Skill을 실행합니다. /compact와 같이 대화 기록에 작용하는 명령은 작업할 이전 메시지가 필요합니다.
/compact로 기록 압축하기
/compact 명령은 이전 메시지를 요약하면서 중요한 컨텍스트를 보존하여 대화 기록의 크기를 줄입니다. 압축은 요약할 충분한 이전 메시지가 있는 기존 대화가 필요합니다. 이 예제는 먼저 대화를 한 다음 압축하고 결과를 보고하는 compact_boundary 시스템 메시지를 읽습니다:
compact_boundary 메시지는 압축이 실행되었을 때만 도착합니다. 요약할 것이 없으면 /compact는 대신 이유를 보고합니다. 실행은 여전히 success 결과로 끝나고 compact_boundary 메시지가 없으며, 결과 텍스트는 이유를 전달합니다. 예를 들어 짧은 교환 후 Not enough messages to compact.입니다. 새로운 원샷 query() 호출은 빈 컨텍스트로 시작하므로 이 패턴을 이전 턴이 있는 세션에서 사용하십시오. 예를 들어 스트리밍 입력 모드에서 또는 세션을 재개할 때입니다./clear로 컨텍스트 재설정하기
/clear 명령은 대화를 빈 컨텍스트로 재설정하므로 후속 프롬프트는 이전 대화 기록 없이 시작합니다. 이전 대화는 디스크에 남아 있습니다. resume 옵션에 세션 ID를 전달하여 해당 대화로 돌아갈 수 있습니다.
/clear는 여러 프롬프트를 단일 연결을 통해 전송하는 스트리밍 입력 모드에서 유용합니다. 원샷 query() 호출의 경우 각 호출은 이미 빈 컨텍스트로 시작하므로 /clear를 전송하는 것은 실질적인 효과가 없습니다. 대신 새로운 query()를 시작하십시오.
Skills 생성하기
각 Skill을 YAML frontmatter 및 Markdown 콘텐츠가 포함된SKILL.md 파일을 포함하는 디렉토리로 생성합니다. description 필드는 Claude가 Skill을 호출하는 시기를 결정합니다.
예제 디렉토리 구조:
발견 수준 선택하기
두 가지 가장 일반적인 발견 수준에서 Skills를 저장합니다:- 프로젝트 Skills:
.claude/skills/, 현재 프로젝트에서만 사용 가능 - 개인 Skills:
~/.claude/skills/, 모든 프로젝트에서 사용 가능
.claude/commands/에 기존 사용자 정의 명령 파일이 있으면 계속 작동합니다. .claude/commands/deploy.md의 명령 파일은 /deploy를 생성하고 .claude/skills/deploy/SKILL.md의 Skill과 동일한 방식으로 작동합니다. 명령 파일과 Skill이 이름을 공유하면 이름을 공유하는 Skills 해결하기를 참조하여 어느 것이 실행되는지 확인하십시오. SDK는 Skills와 동일한 두 범위에서 .claude/commands/ 및 ~/.claude/commands/ 파일을 로드합니다. 두 아티팩트 형식의 완전한 가이드는 Skills로 Claude 확장하기를 참조하십시오.
첫 번째 Skill 생성 및 전달하기
전체 흐름을 보려면.claude/skills/security-check/SKILL.md를 생성합니다:
/<name>을 전송하여 직접 전달할 수 있습니다:
success 결과로 끝납니다. 시드된 문제가 있는 작은 Express 앱에 대해 결과 텍스트는 다음과 같이 시작합니다:
slash_commands 배열에 나타납니다.
Claude Code는 번들
code-review 및 verify Skills를 포함합니다. .claude/commands/ 파일의 이름을 그 중 하나로 지정하면, 예를 들어 .claude/commands/code-review.md, 파일의 명령이 번들 Skill을 섀도우하고 slash_commands는 이름을 한 번 나열합니다.Skills를 위한 도구 사전 승인하기
프로젝트 및 개인 Skills의 경우 Claude Code는 SDK 세션에서
allowed-tools frontmatter 필드를 적용합니다. 쿼리 구성의 allowedTools 옵션(allowed_tools in Python)을 통해 이러한 Skills를 위한 도구를 사전 승인할 수도 있습니다. claude.ai에서 동기화된 Skills는 자신의 frontmatter 규칙을 따릅니다.allowedTools(allowed_tools in Python)를 사용하여 Read, Grep 및 Glob을 사전 승인하므로 Claude는 security-check Skill을 실행하는 동안 승인을 기다리지 않고 파일을 검사할 수 있습니다:
success 결과로 끝납니다.
목록은 다른 것을 제한하기보다는 명명된 도구를 사전 승인합니다. 권한 모드 및 canUseTool 콜백을 포함한 전체 권한 흐름은 권한을 참조하십시오.
문제 해결
Skills를 찾을 수 없음
settingSources 구성 확인: SDK는user 및 project 설정 소스를 통해 Skills를 발견합니다. settingSources/setting_sources를 명시적으로 설정하고 해당 소스를 생략하면 SDK는 Skills를 로드하지 않습니다:
settingSources/setting_sources에 대한 자세한 내용은 TypeScript SDK 참조 또는 Python SDK 참조를 참조하십시오.
작업 디렉토리 확인: SDK는 cwd 옵션의 .claude/skills/ 및 저장소 루트까지의 모든 상위 디렉토리에서 Skills를 로드합니다. cwd가 .claude/skills/를 포함하는 디렉토리를 가리키거나 그 아래에 있으며, 동일한 저장소 내에 있는지 확인하십시오:
Skill이 사용되지 않음
skills 옵션 확인: skills 목록을 전달한 경우 Skill의 이름이 포함되어 있는지 확인하십시오. Claude가 나열되지 않은 Skill을 호출하려고 하면 Skill 도구는 Skill <name> is not in this session's skills allowlist를 반환합니다. 목록에 이름을 추가하거나 프롬프트에서 /<name>을 전송하여 Skill을 직접 전달하십시오. 이는 나열 없이 작동합니다.
설명 확인: 구체적이고 관련 키워드를 포함하는지 확인하십시오. 효과적인 설명 작성에 대한 지침은 Agent Skills 모범 사례를 참조하십시오.
Invalid skill name error
skills 목록의 이름이 정확한 Skill 이름으로 작동할 수 없으면 query()는 Claude Code 프로세스를 시작하기 전에 목록을 거부합니다. 거부를 트리거하는 이름은 다음을 포함합니다:
- 빈 이름
- 괄호, 쉼표 또는 제어 문자를 포함하는 이름
- 공백으로 채워진 이름
- 맨
*또는:*접미사와 같은 와일드카드 형식
- TypeScript
- Python
TypeScript SDK는 항목이 위반한 규칙을 명시하는 빈 이름은
Error를 발생시킵니다. 예를 들어 skills: ["docs:*"]는 다음을 발생시킵니다:Skill names must be non-empty strings.를 보고합니다.TypeScript Agent SDK 0.3.221 이전에는 SDK가 이 검사를 실행하지 않았습니다.추가 문제 해결
YAML 구문 오류 및 디버깅과 같은 일반적인 Skills 문제 해결은 Claude Code Skills 문제 해결 섹션을 참조하십시오.다음 단계
Claude Code Skills 가이드는 심층적인 작성을 다룹니다. 해당 지침은 SDK 세션에 적용됩니다. 다음 섹션부터 시작하십시오:- Frontmatter 참조: 지원되는 모든 필드
- Skills에 인수 전달하기:
$ARGUMENTS,$0,$1및 Skill 스택. 전체 대체 테이블은 명명된 인수 및${CLAUDE_*}변수를 추가합니다 - 동적 컨텍스트 주입하기: Claude가 Skill 콘텐츠를 보기 전에 실행되는
!`command`라인 - Skills가 로드되는 위치 선택하기: 모든 Skill 위치, 플러그인 네임스페이싱 및 두 개가 이름을 공유할 때 어느 것이 실행되는지
관련 리소스
- Claude Code의 명령: 모든 기본 제공을 포함한 전체 명령 표면
- Agent Skills 개요: 개념적 개요, 이점 및 아키텍처
- Agent Skills 모범 사례: 효과적인 Skills를 위한 작성 지침
- Agent Skills 쿡북: 예제 Skills 및 템플릿
- SDK의 Subagents: 프로그래밍 옵션이 있는 유사한 파일 시스템 기반 에이전트
- SDK 개요: 일반 SDK 개념
- TypeScript SDK 참조: 완전한 API 문서
- Python SDK 참조: 완전한 API 문서