Расширение агентов с помощью скиллов

Управляйте тем, какие скиллы Claude может вызывать в сессиях Claude Agent SDK, вызывайте команды по имени и создавайте скиллы, которые обнаруживаются вашими сессиями

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

Дополнительную информацию о скиллах, включая преимущества, архитектуру и рекомендации по их созданию, см. в обзоре 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 для их регистрации.

[!NOTE]

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 из определённого пути.

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

Установите опцию skills в query(), чтобы управлять тем, какие скиллы Claude может вызывать в сессии. Если опция опущена, обнаруженные скиллы включены и инструмент Skill доступен, что соответствует поведению CLI. Передайте "all", чтобы Claude мог вызывать каждый обнаруженный скилл, список имён скиллов, чтобы разрешить только их, или [], чтобы Claude не мог вызывать ни один.

Например, чтобы позволить Claude вызывать только два скилла с указанными именами:

options = ClaudeAgentOptions(skills=["pdf", "docx"])

const options = { skills: ["pdf", "docx"] };

Настройка скиллов в сессии

Когда вы устанавливаете skills, SDK автоматически добавляет инструмент Skill в allowedTools. Если вы также передаёте явный список tools, включите "Skill" в этот список, чтобы Claude мог вызывать скиллы.

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

Следующий пример включает каждый обнаруженный скилл в сессии и предварительно одобряет инструменты, которые обычно нужны скиллам. Пример устанавливает 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);
}

Подтверждение загрузки скиллов

В начале потока SDK выдаёт системное сообщение с подтипом init. Проверьте его массив skills, чтобы убедиться, что ваши скиллы загружены, прежде чем Claude начнёт работу. Массив включает скиллы, вызываемые пользователем, которые вы определили с полем frontmatter description или when_to_use, а также встроенные скиллы, входящие в Claude Code.

Массив содержит только скиллы, вызываемые пользователем. Скилл с user-invocable: false в frontmatter загружается и остаётся доступным для Claude, но не появляется в массиве. Массив содержит одни и те же скиллы независимо от того, находятся ли они в вашем списке skills.

Разрешение только определённых скиллов

Чтобы позволить Claude вызывать только определённые скиллы, передайте их имена в списке skills:

Ваши собственные скиллы: имя каталога скилла
Скиллы плагинов: plugin:skill
Конфликты имён в additionalDirectories или add_dirs: скилл в одном из этих каталогов получает имя с префиксом, если его имя конфликтует с корпоративным, личным или проектным скиллом либо со скиллом в каталоге, добавленном ранее. Указывайте его под этим именем. Если скилл verify есть в ../api и ../web, добавленных в таком порядке, и других скиллов verify нет, укажите их как verify и web:verify. Требуется Claude Code v2.1.309 или новее

Список принимает только точные имена скиллов. Если запись не может работать как точное имя, query() отклоняет список до начала сессии. См. Ошибка неверного имени скилла, где описаны правила имён и ошибка, которую выдаёт каждый SDK.

Модель не видит неуказанные скиллы, и инструмент Skill их отклоняет, при этом их файлы остаются на диске и по-прежнему доступны через Read и Bash. Ограничение списка не ограничивает отправку по имени.

Чтобы позволить Claude вызывать каждый обнаруженный скилл, передайте 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. как результат без хода модели.

[!NOTE]

Команда может достичь лимита maxTurns / max_turns как любая другая подсказка, завершив запрос с результатом ошибки вместо success. Для контракта результата ошибки см. Обработка результата. Если ваша команда может достичь лимита, оберните цикл в try/catch в TypeScript или try/except в Python, как показано в Ввод одного сообщения, или установите maxTurns достаточно высоко для завершения работы.

Сжатие истории с помощью `/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())

[!NOTE]

Сообщение 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.

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

.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.

[!NOTE]

Claude Code включает встроенные skills code-review и verify. Если вы назовёте файл .claude/commands/ в честь одного из них, например .claude/commands/code-review.md, файл команды затеняет встроенный skill и slash_commands содержит имя один раз.

Предварительное одобрение инструментов для skills

[!NOTE]

В сессиях SDK вы можете предварительно одобрить инструменты для project или personal skill с помощью поля frontmatter allowed-tools этого skill или с помощью опции allowedTools (allowed_tools в Python) в конфигурации вашего запроса. Если ваша организация задает allowManagedPermissionRulesOnly в управляемых настройках, Claude Code игнорирует оба способа. Skills синхронизированные из claude.ai следуют своим собственным правилам frontmatter.

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 выводит отклонение по-разному:

[tab] TypeScript

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 не выполнял эту проверку.

[tab] Python

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: каждое поддерживаемое поле
Передача аргументов в скиллы: $ARGUMENTS, $0 и $1. Полная таблица подстановок добавляет именованные аргументы и переменные ${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

agent-sdk/skills.md 2026-11-12 23:02 UTC to 2026-11-13 01:02 UTC

Расширение агентов с помощью скиллов

Как skills работают с Agent SDK

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

Настройка скиллов в сессии

Подтверждение загрузки скиллов

Разрешение только определённых скиллов

Команды в сеансах Agent SDK

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

Отправка команд по имени

Сжатие истории с помощью /compact

Сброс контекста с помощью /clear

Создание skills

Выберите уровень обнаружения

Создайте и отправьте ваш первый skill

Предварительное одобрение инструментов для skills

Troubleshooting

Skills не найдены

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

Ошибка неверного имени skill

Дополнительное troubleshooting

Следующие шаги

Связанные ресурсы

Сжатие истории с помощью `/compact`

Сброс контекста с помощью `/clear`