Agent Skills в SDK

Обзор

Agent Skills расширяют Claude специализированными возможностями, которые Claude автономно вызывает при необходимости. Skills упакованы как файлы SKILL.md, содержащие инструкции, описания и дополнительные ресурсы.

Для получения полной информации о Skills, включая преимущества, архитектуру и рекомендации по созданию, см. обзор Agent Skills.

Как Skills работают с SDK

При использовании Claude Agent SDK Skills:

1. Определяются как артефакты файловой системы: Создаются как файлы SKILL.md в определённых каталогах (.claude/skills/)
2. Загружаются из файловой системы: Skills загружаются из настроенных расположений файловой системы. Вы должны указать settingSources (TypeScript) или setting_sources (Python) для загрузки Skills из файловой системы
3. Автоматически обнаруживаются: После загрузки параметров файловой системы метаданные Skill обнаруживаются при запуске из пользовательских и проектных каталогов; полное содержимое загружается при срабатывании
4. Вызываются моделью: Claude автономно выбирает, когда их использовать, на основе контекста
5. Включаются через allowed_tools: Добавьте "Skill" в ваш allowed_tools для включения Skills

В отличие от подагентов (которые можно определить программно), Skills должны быть созданы как артефакты файловой системы. SDK не предоставляет программный API для регистрации Skills.

Использование Skills с SDK

Для использования Skills с SDK вам необходимо:

1. Включить "Skill" в конфигурацию allowed_tools
2. Настроить settingSources/setting_sources для загрузки Skills из файловой системы

После настройки Claude автоматически обнаруживает Skills из указанных каталогов и вызывает их при необходимости для запроса пользователя.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        cwd="/path/to/project",  # Project with .claude/skills/
        setting_sources=["user", "project"],  # Load Skills from filesystem
        allowed_tools=["Skill", "Read", "Write", "Bash"]  # Enable Skill tool
    )

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

asyncio.run(main())

Расположение Skills

Skills загружаются из каталогов файловой системы на основе конфигурации settingSources/setting_sources:

• Project Skills (.claude/skills/): Общие с вашей командой через git - загружаются, когда setting_sources включает "project"
• User Skills (~/.claude/skills/): Личные Skills для всех проектов - загружаются, когда setting_sources включает "user"
• Plugin Skills: Поставляются с установленными плагинами Claude Code

Создание Skills

Skills определяются как каталоги, содержащие файл SKILL.md с YAML frontmatter и содержимым Markdown. Поле description определяет, когда Claude вызывает ваш Skill.

Пример структуры каталога:

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

Для полного руководства по созданию Skills, включая структуру SKILL.md, многофайловые Skills и примеры, см.:

• Agent Skills в Claude Code: Полное руководство с примерами
• Agent Skills Best Practices: Рекомендации по созданию и соглашения об именовании
• Agent Skills Cookbook: Примеры Skills и шаблоны

Ограничения инструментов

Для ограничения инструментов для Skills в приложениях SDK используйте параметр allowedTools:

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill", "Read", "Grep", "Glob"]  # Restricted toolset
)

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

Обнаружение доступных Skills

Чтобы увидеть, какие Skills доступны в вашем приложении SDK, просто спросите Claude:

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill"]
)

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

Claude выведет список доступных Skills на основе вашего текущего рабочего каталога и установленных плагинов.

Тестирование Skills

Протестируйте Skills, задав вопросы, которые соответствуют их описаниям:

options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # Load Skills from filesystem
    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"],  # Required to load Skills
    allowed_tools=["Skill"]
)

Для получения дополнительной информации о settingSources/setting_sources см. справочник TypeScript SDK или справочник Python SDK.

Проверьте рабочий каталог: SDK загружает Skills относительно параметра cwd. Убедитесь, что он указывает на каталог, содержащий .claude/skills/:

# Убедитесь, что ваш cwd указывает на каталог, содержащий .claude/skills/
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # Must contain .claude/skills/
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

Полный шаблон см. в разделе "Использование Skills с SDK" выше.

Проверьте расположение файловой системы:

# Check project Skills
ls .claude/skills/*/SKILL.md

# Check personal Skills
ls ~/.claude/skills/*/SKILL.md

Skill не используется

Проверьте, что инструмент Skill включён: Убедитесь, что "Skill" находится в вашем allowedTools.

Проверьте описание: Убедитесь, что оно конкретно и включает соответствующие ключевые слова. Рекомендации по написанию эффективных описаний см. в Agent Skills Best Practices.

Дополнительное устранение неполадок

Для общего устранения неполадок Skills (синтаксис YAML, отладка и т. д.) см. раздел устранения неполадок Claude Code Skills.

Связанная документация

Руководства по Skills

• Agent Skills в Claude Code: Полное руководство по Skills с созданием, примерами и устранением неполадок
• Agent Skills Overview: Концептуальный обзор, преимущества и архитектура
• Agent Skills Best Practices: Рекомендации по созданию эффективных Skills
• Agent Skills Cookbook: Примеры Skills и шаблоны

Ресурсы SDK

• Subagents в SDK: Аналогичные агенты на основе файловой системы с программными параметрами
• Slash Commands в SDK: Команды, вызываемые пользователем
• SDK Overview: Общие концепции SDK
• TypeScript SDK Reference: Полная документация API
• Python SDK Reference: Полная документация API