SKILL.md, содержащих инструкции, описания и дополнительные вспомогательные ресурсы. На этой странице также рассматриваются команды в сеансах Agent SDK.
Для получения полной информации о skills, включая преимущества, архитектуру и рекомендации по разработке, см. обзор Agent Skills.
Как skills работают с Agent SDK
При использовании Claude Agent SDK skills:- Определяются как артефакты файловой системы: вы создаёте каждый skill как файл
SKILL.mdв его собственном каталоге, например.claude/skills/<name>/SKILL.md - Загружаются из файловой системы: SDK загружает skills из расположений файловой системы, управляемых
settingSources(TypeScript) илиsetting_sources(Python) - Автоматически обнаруживаются: после загрузки параметров файловой системы SDK обнаруживает метаданные skill при запуске из пользовательских и проектных каталогов и загружает полное содержимое, когда Claude вызывает skill
- Вызываются моделью: Claude автономно выбирает, когда их использовать, на основе контекста
- Вызываются пользователем: вы отправляете skill напрямую, отправляя
/<name>в подсказку. См. Команды в сеансах Agent SDK - Ограничиваются через опцию
skills: обнаруженные skills включены по умолчанию. Передайте список имён skills,"all"или[]для управления тем, какие skills может вызывать Claude
agents, вы создаёте skills как файлы на диске. SDK не предоставляет программный API для их регистрации.
Skills обнаруживаются через источники параметров файловой системы. С параметрами
query() по умолчанию SDK загружает пользовательские и проектные источники, поэтому skills в ~/.claude/skills/, <cwd>/.claude/skills/ и .claude/skills/ в любом родительском каталоге <cwd> вплоть до корня репозитория доступны. Проектный источник также охватывает <dir>/.claude/skills/ в каждом каталоге, который вы передаёте через additionalDirectories (TypeScript) или add_dirs (Python), потому что SDK передаёт эти каталоги в Claude Code как --add-dir. Если вы явно установите settingSources, включите 'project' для сохранения skills проекта и добавленного каталога и 'user' для сохранения ваших личных skills, или используйте опцию plugins для загрузки skills из определённого пути.Использование skills с Agent SDK
Установите опциюskills на query() для управления тем, какие skills может вызывать Claude в сеансе. Если опция опущена, обнаруженные skills включены и инструмент Skill доступен, что соответствует поведению CLI. Передайте "all" для того, чтобы Claude мог вызывать каждый обнаруженный skill, список имён skills для разрешения только тех или [] для того, чтобы Claude не мог вызывать ни один.
Например, чтобы позволить Claude вызывать только два именованных skill:
Настройка skills в сеансе
Когда вы устанавливаетеskills, SDK автоматически добавляет инструмент Skill в allowedTools. Если вы также передаёте явный список tools, включите "Skill" в этот список, чтобы Claude мог вызывать skills.
После настройки Claude автоматически обнаруживает skills из файловой системы и вызывает их при необходимости для запроса пользователя.
Следующий пример включает каждый обнаруженный skill в сеансе и предварительно одобряет инструменты, которые skills обычно требуют. Пример устанавливает cwd на текущий рабочий каталог процесса, поэтому запустите его из проекта, который имеет каталог .claude/skills/ в текущем каталоге или в любом родительском каталоге вплоть до корня репозитория:
Подтверждение загрузки skills
В начале потока SDK выдаёт системное сообщение с подтипомinit. Проверьте его массив skills, чтобы подтвердить, что ваши skills загружены, прежде чем Claude начнёт работу. Массив включает skills, которые можно вызывать пользователем, которые вы определили с полем frontmatter description или when_to_use, а также встроенные skills, включённые в Claude Code.
Массив содержит только skills, которые можно вызывать пользователем. Skill с user-invocable: false в его frontmatter загружается и остаётся доступным для Claude, но не появляется в массиве. Массив отражает то, что обнаружил сеанс, и содержит одни и те же skills независимо от того, находятся ли они в вашем списке skills.
Разрешить только определённые skills
Чтобы позволить Claude вызывать только определённые skills, передайте их имена в спискеskills. Имена соответствуют полю name в SKILL.md или имени каталога skill. Используйте plugin:skill для skills, предоставляемых плагинами.
Список принимает только точные имена skills. Если запись не может работать как точное имя, query() отклоняет список перед началом сеанса. См. Ошибка неверного имени skill для правил имён и ошибки, которую выдаёт каждый SDK.
Модель не видит неуказанные skills и инструмент Skill их отклоняет, в то время как их файлы остаются на диске и остаются доступными через Read и Bash. Ограничение списка не ограничивает отправку по имени.
Чтобы позволить Claude вызывать каждый обнаруженный skill, передайте skills: "all" вместо подстановочного знака.
Команды в сеансах Agent SDK
Этот раздел — документация команд SDK. Команда — это всё, что вы запускаете, отправляя/<name> в подсказку. Записи на поверхности команд отличаются тем, что их поддерживает:
- Встроенные команды: выполняют логику, закодированную в процесс Claude Code, который запускает SDK, например
/compact - Встроенные skills: артефакты подсказок, включённые в Claude Code, например
/code-review - Ваши skills: артефакты подсказок, которые вы создаёте, каждый — каталог, содержащий файл
SKILL.md. Имя skill, который можно вызывать пользователем, автоматически присоединяется к поверхности, поэтому отправка вашего собственного/security-checkи запуск встроенного работают одинаково - Файлы пользовательских команд: более старая форма артефакта с тем же поведением, плоские файлы Markdown в
.claude/commands/, имена файлов которых становятся именами команд. Skills — их рекомендуемый преемник
Обнаружение доступных команд
Вы можете отправлять команды, которые работают без интерактивного терминала, через SDK. Сообщениеsystem/init содержит доступные в вашем сеансе в его поле slash_commands. Команды, которые требуют интерактивного терминала, такие как /theme и /terminal-setup, не появляются в списке. Получите доступ к полю при запуске вашего сеанса:
.claude/commands/:
user-invocable: false в его frontmatter не появляется в этом списке или в массиве skills из Подтверждение загрузки skills. Сеансы, которые настраивают MCP серверы, также могут предоставлять MCP подсказки как команды.
Отправка команд по имени
Отправьте команду, включив её в строку подсказки, так же как вы отправляете обычный текст. Отправка не зависит от опцииskills. Отправка /<name> запускает skill, который можно вызывать пользователем, даже когда ваш список skills его опускает. Команды, которые действуют на историю разговора, такие как /compact, требуют предыдущих сообщений для работы.
Команда может достичь лимита
maxTurns / max_turns как любая другая подсказка, завершив запрос с результатом ошибки вместо success. Для контракта результата ошибки см. Обработка результата. Если ваша команда может достичь лимита, оберните цикл в try/catch в TypeScript или try/except в Python, как показано в Ввод одного сообщения, или установите maxTurns достаточно высоко для завершения работы.Сжатие истории с помощью /compact
Команда /compact уменьшает размер истории вашего разговора путём суммирования старых сообщений при сохранении важного контекста. Сжатие требует существующего разговора с достаточным количеством предыдущих сообщений для суммирования. Этот пример сначала имеет разговор, затем сжимает его и читает системное сообщение compact_boundary, которое сообщает результат:
Сообщение
compact_boundary поступает только при выполнении сжатия. Если нечего суммировать, /compact сообщает причину вместо выдачи ошибки. Запуск всё ещё заканчивается результатом success и без сообщения compact_boundary, и текст результата содержит причину, например Not enough messages to compact. после одного короткого обмена. Свежий одноразовый вызов query() начинается с пустого контекста, поэтому используйте этот паттерн в сеансе с предыдущими ходами, например в режиме потокового ввода или при возобновлении сеанса.Сброс контекста с помощью /clear
Команда /clear сбрасывает разговор в пустой контекст, поэтому последующие подсказки начинаются без предыдущей истории разговора. Предыдущий разговор остаётся на диске. Вы можете вернуться к этому разговору, передав его ID сеанса в опцию resume.
/clear полезна в режиме потокового ввода, где вы отправляете несколько подсказок через одно соединение. Для одноразовых вызовов query() каждый вызов уже начинается с пустого контекста, поэтому отправка /clear не имеет практического эффекта. Вместо этого запустите новый query().
Создание skills
Создайте каждый skill как каталог, содержащий файлSKILL.md с YAML frontmatter и содержимым Markdown. Поле description определяет, когда Claude вызывает ваш skill.
Пример структуры каталога:
Выберите уровень обнаружения
Сохраняйте skills на одном из двух наиболее распространённых уровней обнаружения:- Project skills:
.claude/skills/, доступны только в текущем проекте - Personal skills:
~/.claude/skills/, доступны во всех ваших проектах
.claude/commands/, они продолжают работать. Файл команды в .claude/commands/deploy.md создаёт /deploy и работает так же, как skill в .claude/skills/deploy/SKILL.md. Если файл команды и skill имеют одно имя, см. Разрешение skills, которые имеют одно имя для того, какой из них запускается. SDK загружает файлы .claude/commands/ и ~/.claude/commands/ из тех же двух областей, что и skills. См. Расширьте Claude с помощью skills для полного руководства по обеим формам артефактов.
Создайте и отправьте ваш первый skill
Чтобы увидеть полный поток, создайте.claude/skills/security-check/SKILL.md:
success, текст которого содержит результаты сканирования. Для небольшого приложения Express с внедрёнными проблемами текст результата начинается:
slash_commands сообщения init.
Claude Code включает встроенные skills
code-review и verify. Если вы назовёте файл .claude/commands/ в честь одного из них, например .claude/commands/code-review.md, файл команды затеняет встроенный skill и slash_commands содержит имя один раз.Предварительное одобрение инструментов для skills
Для project и personal skills Claude Code применяет поле frontmatter
allowed-tools в сеансах SDK. Вы также можете предварительно одобрить инструменты для этих skills через опцию allowedTools (allowed_tools в Python) в конфигурации вашего запроса. Skills синхронизированные из claude.ai следуют своим собственным правилам frontmatter.Read, Grep и Glob с allowedTools (allowed_tools в Python), поэтому Claude может проверять файлы при запуске skill security-check без остановки для одобрения:
success, текст которого содержит результаты.
Список предварительно одобряет названные инструменты, а не ограничивает остальные. Для полного потока разрешений, включая режимы разрешений и обратный вызов canUseTool, см. Разрешения.
Troubleshooting
Skills не найдены
Проверьте конфигурацию settingSources: SDK обнаруживает skills через источники параметровuser и project. Если вы явно установите settingSources/setting_sources и опустите эти источники, SDK не загружает skills:
settingSources/setting_sources см. справочник TypeScript SDK или справочник Python SDK.
Проверьте рабочий каталог: SDK загружает skills из .claude/skills/ в опции cwd и в каждом родительском каталоге вплоть до корня репозитория. Убедитесь, что cwd указывает на каталог, содержащий .claude/skills/, или ниже него в пределах одного репозитория:
Skill не используется
Проверьте опциюskills: если вы передали список skills, подтвердите, что имя skill включено. Когда Claude пытается вызвать неуказанный skill, инструмент Skill возвращает Skill <name> is not in this session's skills allowlist. Добавьте имя в ваш список или отправьте skill напрямую, отправив /<name> в подсказку, что работает без указания.
Проверьте описание: убедитесь, что оно конкретно и включает соответствующие ключевые слова. См. Agent Skills best practices для рекомендаций по написанию эффективных описаний.
Ошибка неверного имени skill
Когда имя в вашем спискеskills не может работать как точное имя skill, query() отклоняет список перед запуском процесса Claude Code. Имена, которые вызывают отклонение, включают:
- Пустое имя
- Имя, содержащее скобки, запятые или управляющие символы
- Имя, дополненное пробелом
- Форма подстановочного знака, такая как голый
*или суффикс:*
- TypeScript
- Python
TypeScript SDK выдаёт Пустое имя сообщает
Error, указывающую правило, которое нарушила запись. Например, skills: ["docs:*"] выдаёт:Skill names must be non-empty strings.До TypeScript Agent SDK 0.3.221 SDK не выполнял эту проверку.Дополнительное troubleshooting
Для общего troubleshooting skills, такого как ошибки синтаксиса YAML и отладка, см. раздел troubleshooting Claude Code skills.Следующие шаги
Руководство Claude Code skills охватывает разработку в глубину. Его рекомендации применяются к сеансам SDK. Начните с этих разделов:- Справочник Frontmatter: каждое поддерживаемое поле
- Передача аргументов в skills:
$ARGUMENTS,$0,$1и стекирование skills. Полная таблица подстановок добавляет именованные аргументы и переменные${CLAUDE_*} - Внедрение динамического контекста: строки
!`command`, которые запускаются перед тем, как Claude увидит содержимое skill - Выберите, где загружаются skills: каждое расположение skill, пространство имён плагина и какой skill запускается, когда два имеют одно имя
Связанные ресурсы
- Команды в Claude Code: полная поверхность команд, включая каждую встроенную
- Agent Skills overview: концептуальный обзор, преимущества и архитектура
- Agent Skills best practices: рекомендации по разработке для эффективных skills
- Agent Skills cookbook: примеры skills и шаблоны
- Subagents в SDK: похожие агенты на основе файловой системы с программными опциями
- Обзор SDK: общие концепции SDK
- Справочник TypeScript SDK: полная документация API
- Справочник Python SDK: полная документация API