SDK에서의 Agent Skills

개요

Agent Skills는 Claude가 관련성이 있을 때 자율적으로 호출하는 전문화된 기능으로 Claude를 확장합니다. Skills는 지침, 설명 및 선택적 지원 리소스를 포함하는 SKILL.md 파일로 패키징됩니다.

이점, 아키텍처 및 작성 가이드라인을 포함한 Skills에 대한 포괄적인 정보는 Agent Skills 개요를 참조하세요.

Skills가 SDK와 작동하는 방식

Claude Agent SDK를 사용할 때 Skills는:

1. 파일시스템 아티팩트로 정의됨: 특정 디렉토리(.claude/skills/)에 SKILL.md 파일로 생성됩니다
2. 파일시스템에서 로드됨: Skills는 구성된 파일시스템 위치에서 로드됩니다. 파일시스템에서 Skills를 로드하려면 settingSources(TypeScript) 또는 setting_sources(Python)를 지정해야 합니다
3. 자동으로 검색됨: 파일시스템 설정이 로드되면 Skill 메타데이터가 시작 시 사용자 및 프로젝트 디렉토리에서 검색됩니다. 전체 콘텐츠는 트리거될 때 로드됩니다
4. 모델이 호출함: Claude가 컨텍스트에 따라 자율적으로 사용 시점을 선택합니다
5. allowed_tools를 통해 활성화됨: Skills를 활성화하려면 allowed_tools에 "Skill"을 추가하세요

서브에이전트(프로그래밍 방식으로 정의할 수 있음)와 달리, Skills는 파일시스템 아티팩트로 생성해야 합니다. SDK는 Skills를 등록하기 위한 프로그래밍 API를 제공하지 않습니다.

SDK에서 Skills 사용하기

SDK에서 Skills를 사용하려면 다음이 필요합니다:

1. allowed_tools 구성에 "Skill"을 포함합니다
2. 파일시스템에서 Skills를 로드하도록 settingSources/setting_sources를 구성합니다

구성이 완료되면 Claude가 지정된 디렉토리에서 Skills를 자동으로 검색하고 사용자의 요청과 관련이 있을 때 호출합니다.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        cwd="/path/to/project",  # .claude/skills/가 있는 프로젝트
        setting_sources=["user", "project"],  # 파일시스템에서 Skills 로드
        allowed_tools=["Skill", "Read", "Write", "Bash"]  # Skill 도구 활성화
    )

    async for message in query(
        prompt="Help me process this PDF document",
        options=options
    ):
        print(message)

asyncio.run(main())

Skill 위치

Skills는 settingSources/setting_sources 구성에 따라 파일시스템 디렉토리에서 로드됩니다:

• 프로젝트 Skills (.claude/skills/): git을 통해 팀과 공유 - setting_sources에 "project"가 포함될 때 로드됩니다
• 사용자 Skills (~/.claude/skills/): 모든 프로젝트에서 사용하는 개인 Skills - setting_sources에 "user"가 포함될 때 로드됩니다
• 플러그인 Skills: 설치된 Claude Code 플러그인과 함께 번들됩니다

Skills 생성하기

Skills는 YAML 프론트매터와 Markdown 콘텐츠가 포함된 SKILL.md 파일을 포함하는 디렉토리로 정의됩니다. description 필드는 Claude가 Skill을 호출하는 시점을 결정합니다.

예시 디렉토리 구조:

.claude/skills/processing-pdfs/
└── SKILL.md

SKILL.md 구조, 다중 파일 Skills 및 예시를 포함한 Skills 생성에 대한 완전한 가이드는 다음을 참조하세요:

• Claude Code에서의 Agent Skills: 예시가 포함된 완전한 가이드
• Agent Skills 모범 사례: 작성 가이드라인 및 명명 규칙

도구 제한

SDK 애플리케이션에서 Skills의 도구를 제한하려면 allowedTools 옵션을 사용하세요:

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # 파일시스템에서 Skills 로드
    allowed_tools=["Skill", "Read", "Grep", "Glob"]  # 제한된 도구 세트
)

async for message in query(
    prompt="Analyze the codebase structure",
    options=options
):
    print(message)

사용 가능한 Skills 검색하기

SDK 애플리케이션에서 사용 가능한 Skills를 확인하려면 Claude에게 간단히 물어보세요:

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # 파일시스템에서 Skills 로드
    allowed_tools=["Skill"]
)

async for message in query(
    prompt="What Skills are available?",
    options=options
):
    print(message)

Claude는 현재 작업 디렉토리와 설치된 플러그인을 기반으로 사용 가능한 Skills를 나열합니다.

Skills 테스트하기

Skills의 설명과 일치하는 질문을 하여 Skills를 테스트하세요:

options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # 파일시스템에서 Skills 로드
    allowed_tools=["Skill", "Read", "Bash"]
)

async for message in query(
    prompt="Extract text from invoice.pdf",
    options=options
):
    print(message)

설명이 요청과 일치하면 Claude가 자동으로 관련 Skill을 호출합니다.

문제 해결

Skills를 찾을 수 없음

settingSources 구성 확인: Skills는 settingSources/setting_sources를 명시적으로 구성할 때만 로드됩니다. 이것이 가장 일반적인 문제입니다:

# 잘못됨 - Skills가 로드되지 않습니다
options = ClaudeAgentOptions(
    allowed_tools=["Skill"]
)

# 올바름 - Skills가 로드됩니다
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Skills 로드에 필요
    allowed_tools=["Skill"]
)

settingSources/setting_sources에 대한 자세한 내용은 TypeScript SDK 레퍼런스 또는 Python SDK 레퍼런스를 참조하세요.

작업 디렉토리 확인: SDK는 cwd 옵션을 기준으로 Skills를 로드합니다. .claude/skills/를 포함하는 디렉토리를 가리키는지 확인하세요:

# cwd가 .claude/skills/를 포함하는 디렉토리를 가리키는지 확인하세요
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # .claude/skills/를 포함해야 합니다
    setting_sources=["user", "project"],  # Skills 로드에 필요
    allowed_tools=["Skill"]
)

전체 패턴은 위의 "SDK에서 Skills 사용하기" 섹션을 참조하세요.

파일시스템 위치 확인:

# 프로젝트 Skills 확인
ls .claude/skills/*/SKILL.md

# 개인 Skills 확인
ls ~/.claude/skills/*/SKILL.md

Skill이 사용되지 않음

Skill 도구가 활성화되어 있는지 확인: allowedTools에 "Skill"이 포함되어 있는지 확인하세요.

설명 확인: 설명이 구체적이고 관련 키워드를 포함하는지 확인하세요. 효과적인 설명 작성에 대한 가이드는 Agent Skills 모범 사례를 참조하세요.

추가 문제 해결

일반적인 Skills 문제 해결(YAML 구문, 디버깅 등)에 대해서는 Claude Code Skills 문제 해결 섹션을 참조하세요.

관련 문서

Skills 가이드

• Claude Code에서의 Agent Skills: 생성, 예시 및 문제 해결을 포함한 완전한 Skills 가이드
• Agent Skills 개요: 개념적 개요, 이점 및 아키텍처
• Agent Skills 모범 사례: 효과적인 Skills를 위한 작성 가이드라인
• Agent Skills 쿡북: 예시 Skills 및 템플릿

SDK 리소스

• SDK에서의 서브에이전트: 프로그래밍 옵션이 있는 유사한 파일시스템 기반 에이전트
• SDK에서의 슬래시 명령어: 사용자가 호출하는 명령어
• SDK 개요: 일반적인 SDK 개념
• TypeScript SDK 레퍼런스: 완전한 API 문서
• Python SDK 레퍼런스: 완전한 API 문서