Перейти к основному содержанию

​
Обзор

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)
  3. Автоматически обнаруживаются: После загрузки параметров файловой системы метаданные Skill обнаруживаются при запуске из пользовательских и проектных каталогов; полное содержимое загружается при срабатывании
  4. Вызываются моделью: Claude автономно выбирает, когда их использовать, на основе контекста
  5. Фильтруются через опцию skills: Обнаруженные Skills включены по умолчанию. Передайте список имён Skills, "all" или [] для управления доступными в сеансе
В отличие от subagents (которые можно определить программно), Skills должны быть созданы как артефакты файловой системы. SDK не предоставляет программный API для регистрации Skills.
Skills обнаруживаются через источники параметров файловой системы. С параметрами query() по умолчанию SDK загружает пользовательские и проектные источники, поэтому Skills в ~/.claude/skills/, <cwd>/.claude/skills/ и .claude/skills/ в любом родительском каталоге <cwd> вплоть до корня репозитория доступны. Если вы явно установите settingSources, включите 'user' или 'project' для сохранения обнаружения Skills, или используйте опцию plugins для загрузки Skills из определённого пути.

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

Установите опцию skills на query() для управления тем, какие Skills доступны для сеанса. Если опция опущена, обнаруженные Skills включены и инструмент Skill доступен, что соответствует поведению CLI. Передайте "all" для включения каждого обнаруженного Skill, список имён Skill для включения только тех или [] для отключения всех. Когда вы устанавливаете skills, SDK автоматически добавляет инструмент Skill в allowedTools. Если вы также передаёте явный список tools, включите "Skill" в этот список, чтобы Claude мог вызывать 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
        skills="all",  # Enable every discovered Skill
        allowed_tools=["Read", "Write", "Bash"],
    )

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


asyncio.run(main())
Для включения только определённых Skills передайте их имена. Имена соответствуют полю name в SKILL.md или имени каталога Skill. Используйте plugin:skill для Skills, предоставляемых плагинами. 
options = ClaudeAgentOptions(skills=["pdf", "docx"])
Опция skills является фильтром контекста, а не песочницей. Неуказанные Skills скрыты от модели и отклонены инструментом Skill, но их файлы остаются на диске и доступны через Read и Bash.

​
Расположение 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 для предварительного одобрения определённых инструментов. Без обратного вызова canUseTool всё, что не в списке, отклоняется:
Предполагается, что операторы импорта из первого примера используются в следующих фрагментах кода.
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    skills="all",
    allowed_tools=["Read", "Grep", "Glob"],
)

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
    skills="all",
)

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
    skills="all",
    allowed_tools=["Read", "Bash"],
)

async for message in query(prompt="Extract text from invoice.pdf", options=options):
    print(message)
Claude автоматически вызывает соответствующий Skill, если описание соответствует вашему запросу.

​
Troubleshooting

​
Skills не найдены

Проверьте конфигурацию settingSources: Skills обнаруживаются через источники параметров user и project. Если вы явно установите settingSources/setting_sources и опустите эти источники, Skills не загружаются: 
# Skills not loaded: setting_sources excludes user and project
options = ClaudeAgentOptions(setting_sources=[], skills="all")

# Skills loaded: user and project sources included
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],
    skills="all",
)
Для получения дополнительной информации о settingSources/setting_sources см. справочник TypeScript SDK или справочник Python SDK. Проверьте рабочий каталог: SDK загружает Skills из .claude/skills/ в опции cwd и в каждом родительском каталоге вплоть до корня репозитория. Убедитесь, что cwd указывает на каталог, содержащий .claude/skills/, или ниже него в пределах одного репозитория: 
# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # .claude/skills/ here or in a parent directory
    setting_sources=["user", "project"],  # Loads skills from these sources
    skills="all",
)
Полный паттерн см. в разделе “Использование Skills с SDK” выше. Проверьте расположение файловой системы: 
# Check project Skills
ls .claude/skills/*/SKILL.md

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

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

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

​
Дополнительное Troubleshooting

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

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

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

​
Ресурсы SDK