Agent SDK Agent Skills
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
Agent Skills는 관련 시 Claude가 자율적으로 호출하는 전문 역량 패키지입니다. SKILL.md에 지침·설명·선택 리소스를 담습니다. 서브에이전트와 달리 프로그램 등록 API가 없고 파일시스템 아티팩트만 지원합니다.
SDK에서 Skills는:
.claude/skills/등에SKILL.md로 정의settingSources/setting_sources가 허용하는 경로에서 로드- 시작 시 메타데이터 발견, 트리거 시 본문 로드
- 모델이 컨텍스트 기반으로 호출
skills옵션으로 필터 ("all"| 이름 목록 |[])
기본 query()는 user/project를 로드하므로 ~/.claude/skills/, <cwd>/.claude/skills/, 저장소 루트까지 상위 .claude/skills/가 후보입니다. settingSources를 명시하면 user/project를 포함하거나 plugins로 경로 로드하세요.
핵심 개념
| 위치 | 조건 | 용도 |
|---|---|---|
Project .claude/skills/ |
project 소스 |
git 공유 팀 스킬 |
User ~/.claude/skills/ |
user 소스 |
개인 전역 스킬 |
| Plugin skills | plugins 옵션 | plugin:skill 이름 |
skills는 컨텍스트 필터이지 샌드박스가 아닙니다. 목록 밖 스킬은 모델에 숨기고 Skill 도구가 거부하지만, 파일은 디스크에 남아 Read/Bash로 접근 가능합니다.
상세
사용
skills 생략 시 발견된 스킬 활성 + Skill 도구 사용(CLI 동일). 설정 시 SDK가 allowedTools에 Skill을 자동 추가. 명시 tools 리스트를 쓰면 "Skill"을 포함해야 합니다.
from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio
async def main():
options = ClaudeAgentOptions(
cwd="/path/to/project",
setting_sources=["user", "project"],
skills="all",
allowed_tools=["Read", "Write", "Bash"],
)
async for message in query(
prompt="Help me process this PDF document", options=options
):
print(message)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Help me process this PDF document",
options: {
cwd: "/path/to/project",
settingSources: ["user", "project"],
skills: "all",
allowedTools: ["Read", "Write", "Bash"]
}
})) {
console.log(message);
}
특정 스킬만:
options = ClaudeAgentOptions(skills=["pdf", "docx"])
const options = { skills: ["pdf", "docx"] };
이름은 SKILL.md의 name 또는 디렉터리명. 플러그인은 plugin:skill.
작성
.claude/skills/processing-pdfs/
└── SKILL.md
YAML frontmatter + Markdown. description이 호출 시점을 결정합니다. 구조·멀티파일·네이밍은 CLI Skills 및 Agent Skills Best Practices를 따릅니다.
도구 제한
SKILL.md의 allowed-tools frontmatter는 CLI 전용이며 SDK에서는 적용되지 않습니다. SDK는 쿼리의 allowedTools/canUseTool로 제어합니다. 목록에 없고 콜백도 없으면 deny됩니다.
options: {
settingSources: ["user", "project"],
skills: "all",
allowedTools: ["Read", "Grep", "Glob"],
permissionMode: "dontAsk"
}
발견·테스트
프롬프트로 What Skills are available?를 물어 목록을 확인합니다. description과 맞는 요청(예: Extract text from invoice.pdf)으로 자동 호출을 테스트합니다.
문제 해결
| 증상 | 조치 |
|---|---|
| Skills not found | settingSources에 user/project 포함 |
| 호출 안 됨 | description 매칭, Skill 도구 허용, skills 필터 |
| 도구 거부 | allowedTools에 필요 도구 추가 |
| 플러그인 스킬 없음 | plugins path·init skills 목록 |
체크리스트
- SKILL.md가 발견 경로에 있다
-
settingSources에 project/user 포함 -
skills와 tools에 Skill 권한 반영 - SDK에서 skill frontmatter allowed-tools를 신뢰하지 않는다
- 필터가 샌드박스가 아님을 인지했다