SpyBara
Go Premium

agent-sdk/skills.md 2026-09-09 22:58 UTC to 2026-09-10 23:00 UTC

This page contains 369 additions and 142 deletions.

2026
Thu 10 23:00 Mon 14 22:58 Fri 18 23:58

Расширьте агентов с помощью 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"])

Настройка 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())

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

В начале потока SDK выдаёт системное сообщение с подтипом init. Проверьте его массив skills, чтобы подтвердить, что ваши skills загружены, прежде чем Claude начнёт работу. Массив включает skills, которые можно вызывать пользователем, которые вы определили, а также встроенные 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. См. Команды в 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);
}
}

Выведенный список смешивает встроенные команды, встроенные skills, ваши skills, которые можно вызывать пользователем, и файлы .claude/commands/:

Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]

Ваши skills, которые можно вызывать пользователем, появляются как в этом списке, так и в массиве skills из Подтверждение загрузки skills. Список slash_commands добавляет остальные команды, доступные в вашем сеансе. Skill с user-invocable: false в его frontmatter не появляется ни в одном из них. Сеансы, которые настраивают MCP серверы, также могут предоставлять MCP подсказки как команды.

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

Отправьте команду, включив её в строку подсказки, так же как вы отправляете обычный текст. Отправка не зависит от опции skills. Отправка /<name> запускает skill, который можно вызывать пользователем, даже когда ваш список skills его опускает. Команды, которые действуют на историю разговора, такие как /compact, требуют предыдущих сообщений для работы.

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

Сброс контекста с помощью `/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);
}
}

Успешный запуск заканчивается результатом 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())

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

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

Для общего troubleshooting skills, такого как ошибки синтаксиса YAML и отладка, см. раздел troubleshooting Claude Code skills.

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

Руководство Claude Code skills охватывает разработку в глубину. Его рекомендации применяются к сеансам SDK. Начните с этих разделов: