​
Обзор

Agent Skills расширяют Claude специализированными возможностями, которые Claude автономно вызывает при необходимости. Навыки упакованы как файлы 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.
Поведение по умолчанию: По умолчанию SDK не загружает никакие параметры файловой системы. Для использования Skills вы должны явно настроить settingSources: ['user', 'project'] (TypeScript) или setting_sources=["user", "project"] (Python) в ваших параметрах.

​
Использование 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 и примеры, см.:

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

Поле frontmatter allowed-tools в SKILL.md поддерживается только при прямом использовании Claude Code CLI. Оно не применяется при использовании Skills через SDK.При использовании SDK контролируйте доступ к инструментам через основной параметр allowedTools в конфигурации вашего запроса.
Для ограничения инструментов для 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. Это наиболее распространённая проблема: 
# Wrong - Skills won't be loaded
options = ClaudeAgentOptions(
    allowed_tools=["Skill"]
)

# Correct - Skills will be loaded
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/: 
# Ensure your cwd points to the directory containing .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

​
Ресурсы SDK