Расширьте агентов с помощью skills
Управляйте тем, какие skills может вызывать Claude в сеансах Claude Agent SDK, отправляйте команды по имени и создавайте skills, которые обнаруживают ваши сеансы
Agent Skills расширяют Claude специализированными возможностями, которые Claude вызывает при необходимости. Skills упаковываются в виде файлов 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
В отличие от subagents, которые вы можете определить в опции agents, вы создаёте skills как файлы на диске. SDK не предоставляет программный API для их регистрации.
Использование skills с Agent SDK
Установите опцию skills на query() для управления тем, какие skills может вызывать Claude в сеансе. Если опция опущена, обнаруженные skills включены и инструмент Skill доступен, что соответствует поведению CLI. Передайте "all" для того, чтобы Claude мог вызывать каждый обнаруженный skill, список имён skills для разрешения только тех или [] для того, чтобы Claude не мог вызывать ни один.
Например, чтобы позволить Claude вызывать только два именованных skill:
options = ClaudeAgentOptions(skills=["pdf", "docx"])
const options = { skills: ["pdf", "docx"] };
Настройка skills в сеансе
Когда вы устанавливаете skills, SDK автоматически добавляет инструмент Skill в allowedTools. Если вы также передаёте явный список tools, включите "Skill" в этот список, чтобы Claude мог вызывать skills.
После настройки Claude автоматически обнаруживает skills из файловой системы и вызывает их при необходимости для запроса пользователя.
Следующий пример включает каждый обнаруженный skill в сеансе и предварительно одобряет инструменты, которые skills обычно требуют. Пример устанавливает cwd на текущий рабочий каталог процесса, поэтому запустите его из проекта, который имеет каталог .claude/skills/ в текущем каталоге или в любом родительском каталоге вплоть до корня репозитория:
import asyncio
import os
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
cwd=os.getcwd(), # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"], # Load skills from filesystem
skills="all", # Let Claude invoke 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())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Help me process this PDF document",
options: {
cwd: process.cwd(), // .claude/skills/ here or in a parent directory
settingSources: ["user", "project"], // Load skills from filesystem
skills: "all", // Let Claude invoke every discovered skill
allowedTools: ["Read", "Write", "Bash"]
}
})) {
console.log(message);
}
Подтверждение загрузки 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 — их рекомендуемый преемник
По умолчанию как вы, так и Claude можете вызывать любой skill. Вы можете ограничить любой путь через frontmatter skill. Для определений команды и skill см. записи глоссария Команда и Skill. См. Команды в Claude Code для каждой встроенной и Расширьте Claude с помощью skills для полного руководства по обеим формам артефактов.
Обнаружение доступных команд
Вы можете отправлять команды, которые работают без интерактивного терминала, через SDK. Сообщение system/init содержит доступные в вашем сеансе в его поле slash_commands. Команды, которые требуют интерактивного терминала, такие как /theme и /terminal-setup, не появляются в списке. Получите доступ к полю при запуске вашего сеанса:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Hello Claude",
options: { maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "init") {
console.log("Available commands:", message.slash_commands);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage
async def main():
async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):
if isinstance(message, SystemMessage) and message.subtype == "init":
print("Available commands:", message.data["slash_commands"])
asyncio.run(main())
Выведенный список смешивает встроенные команды, встроенные skills, ваши skills, которые можно вызывать пользователем, и файлы .claude/commands/:
Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]
Skill с user-invocable: false в его frontmatter не появляется в этом списке или в массиве skills из Подтверждение загрузки skills. Сеансы, которые настраивают MCP серверы, также могут предоставлять MCP подсказки как команды.
Отправка команд по имени
Отправьте команду, включив её в строку подсказки, так же как вы отправляете обычный текст. Отправка не зависит от опции skills. Отправка /<name> запускает skill, который можно вызывать пользователем, даже когда ваш список skills его опускает. Команды, которые действуют на историю разговора, такие как /compact, требуют предыдущих сообщений для работы.
/<name>, который не совпадает ни с командой в сеансе, ни со встроенной командой Claude Code, не приводит к сбою запроса. Claude Code отправляет подсказку Claude как обычное сообщение с примечанием о том, что команда не была выполнена, поэтому запрос использует ход модели и возвращает ответ Claude. До версии 2.1.274 /<name>, который ничему не соответствовал, возвращал Unknown command: /<name> как результат без хода модели.
/<name>, который совпадает со встроенной командой Claude Code, которая недоступна в сеансе, такой как /theme, возвращает /theme isn't available in this environment. как результат без хода модели.
Сжатие истории с помощью `/compact`
Команда /compact уменьшает размер истории вашего разговора путём суммирования старых сообщений при сохранении важного контекста. Сжатие требует существующего разговора с достаточным количеством предыдущих сообщений для суммирования. Этот пример сначала имеет разговор, затем сжимает его и читает системное сообщение compact_boundary, которое сообщает результат:
import { query } from "@anthropic-ai/claude-agent-sdk";
// Compaction needs existing history, so have a conversation first
try {
for await (const message of query({
prompt: "Explain what this project does",
options: { maxTurns: 2 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result,
// so the follow-up query below still runs.
console.error(`Session ended with an error: ${error}`);
}
// Compact the same conversation
for await (const message of query({
prompt: "/compact",
options: { continue: true, maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "compact_boundary") {
console.log("Compaction completed");
console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
console.log("Trigger:", message.compact_metadata.trigger);
// Example output:
// Compaction completed
// Pre-compaction tokens: 1842
// Trigger: manual
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage
async def main():
# Compaction needs existing history, so have a conversation first
try:
async for message in query(
prompt="Explain what this project does",
options=ClaudeAgentOptions(max_turns=2),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
except Exception as error:
# A single-shot query() raises after yielding an error result,
# so the follow-up query below still runs.
print(f"Session ended with an error: {error}")
# Compact the same conversation
async for message in query(
prompt="/compact",
options=ClaudeAgentOptions(continue_conversation=True, max_turns=1),
):
if isinstance(message, SystemMessage) and message.subtype == "compact_boundary":
print("Compaction completed")
print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"])
print("Trigger:", message.data["compact_metadata"]["trigger"])
# Example output:
# Compaction completed
# Pre-compaction tokens: 1842
# Trigger: manual
asyncio.run(main())
Сброс контекста с помощью `/clear`
Команда /clear сбрасывает разговор в пустой контекст, поэтому последующие подсказки начинаются без предыдущей истории разговора. Предыдущий разговор остаётся на диске. Вы можете вернуться к этому разговору, передав его ID сеанса в опцию resume.
/clear полезна в режиме потокового ввода, где вы отправляете несколько подсказок через одно соединение. Для одноразовых вызовов query() каждый вызов уже начинается с пустого контекста, поэтому отправка /clear не имеет практического эффекта. Вместо этого запустите новый query().
Создание skills
Создайте каждый skill как каталог, содержащий файл SKILL.md с YAML frontmatter и содержимым Markdown. Поле description определяет, когда Claude вызывает ваш skill.
Пример структуры каталога:
.claude/skills/security-check/
└── SKILL.md
Выберите уровень обнаружения
Сохраняйте 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:
---
name: security-check
description: Run a security vulnerability scan
---
Analyze the codebase for security vulnerabilities including:
- SQL injection risks
- XSS vulnerabilities
- Exposed credentials
- Insecure configurations
После создания файла skill доступен через SDK. Claude вызывает его, когда запрос соответствует его описанию, и вы можете отправить его напрямую:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "/security-check",
options: { maxTurns: 10 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def main():
async for message in query(
prompt="/security-check", options=ClaudeAgentOptions(max_turns=10)
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)
asyncio.run(main())
Успешный запуск заканчивается результатом success, текст которого содержит результаты сканирования. Для небольшого приложения Express с внедрёнными проблемами текст результата начинается:
**Security scan of `app.js` — 4 findings (most severe first):**
1. **SQL Injection** (line 8) — `req.query.name` is concatenated directly into the SQL string. Trivially exploitable (`' OR '1'='1`, `'; DROP TABLE users;--`). **Fix:** use parameterized queries, e.g. `db.query("SELECT * FROM users WHERE name = ?", [req.query.name], cb)`.
...
Имя skill также появляется в массиве slash_commands сообщения init.
Предварительное одобрение инструментов для skills
Skills запускаются с инструментами сеанса. Пример ниже предварительно одобряет Read, Grep и Glob с allowedTools (allowed_tools в Python), поэтому Claude может проверять файлы при запуске skill security-check без остановки для одобрения:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(
setting_sources=["user", "project"], # Load skills from filesystem
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
)
async def main():
async for message in query(prompt="Check this project for security issues", options=options):
print(message)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Check this project for security issues",
options: {
settingSources: ["user", "project"], // Load skills from filesystem
skills: "all",
allowedTools: ["Read", "Grep", "Glob"]
}
})) {
console.log(message);
}
В потоке вызов skill появляется как использование инструмента Skill, за которым следуют вызовы Read на файлы проекта. Запуск заканчивается результатом success, текст которого содержит результаты.
Список предварительно одобряет названные инструменты, а не ограничивает остальные. Для полного потока разрешений, включая режимы разрешений и обратный вызов canUseTool, см. Разрешения.
Troubleshooting
Skills не найдены
Проверьте конфигурацию settingSources: SDK обнаруживает skills через источники параметров user и project. Если вы явно установите settingSources/setting_sources и опустите эти источники, SDK не загружает 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",
)
// Skills not loaded: settingSources excludes user and project
const optionsWithoutSkills = {
settingSources: [],
skills: "all"
};
// Skills loaded: user and project sources included
const optionsWithSkills = {
settingSources: ["user", "project"],
skills: "all"
};
Для того, какие каталоги skills загружает каждый источник, см. таблицу источников файловой системы. Для получения дополнительной информации о 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",
)
// Ensure your cwd points to the directory containing .claude/skills/
const options = {
cwd: "/path/to/project", // .claude/skills/ here or in a parent directory
settingSources: ["user", "project"], // Loads skills from these sources
skills: "all"
};
Полный паттерн см. в разделе Использование skills с Agent SDK.
Проверьте расположение файловой системы:
# Check project skills
ls .claude/skills/*/SKILL.md
# Check personal skills
ls ~/.claude/skills/*/SKILL.md
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. Имена, которые вызывают отклонение, включают:
- Пустое имя
- Имя, содержащее скобки, запятые или управляющие символы
- Имя, дополненное пробелом
- Форма подстановочного знака, такая как голый
*или суффикс:*
Каждый SDK выводит отклонение по-разному:
TypeScript SDK выдаёт Error, указывающую правило, которое нарушила запись. Например, skills: ["docs:*"] выдаёт:
Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.
Пустое имя сообщает Skill names must be non-empty strings.
До TypeScript Agent SDK 0.3.221 SDK не выполнял эту проверку.
Python SDK выдаёт ValueError, указывающую правило, которое нарушила запись. Например, skills=["docs:*"] выдаёт:
ValueError: Invalid skill name 'docs:*': wildcard-suffix names are not allowed; list each skill by its exact name.
Пустое имя сообщает Skill names must be non-empty strings.
До Python Agent SDK 0.2.129 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