Agent Skills в SDK

Расширьте Claude специализированными возможностями, используя Agent Skills в Claude Agent SDK

Обзор

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 с SDK

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

После настройки 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())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Help me process this PDF document",
options: {
cwd: "/path/to/project", // Project with .claude/skills/
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all", // Enable every discovered Skill
allowedTools: ["Read", "Write", "Bash"]
}
})) {
console.log(message);
}

Для включения только определённых Skills передайте их имена. Имена соответствуют полю name в SKILL.md или имени каталога Skill. Используйте plugin:skill для Skills, предоставляемых плагинами.

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

const options = { 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 и примеры, см.:

• Agent Skills в Claude Code: Полное руководство с примерами
• Agent Skills Best Practices: Рекомендации по разработке и соглашения об именовании

Ограничения инструментов

Для управления доступом к инструментам для 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)

for await (const message of query({
prompt: "Analyze the codebase structure",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Grep", "Glob"],
permissionMode: "dontAsk" // Deny anything not in allowedTools
}
})) {
console.log(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)

for await (const message of query({
prompt: "What Skills are available?",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all"
}
})) {
console.log(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)

for await (const message of query({
prompt: "Extract text from invoice.pdf",
options: {
cwd: "/path/to/project",
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Bash"]
}
})) {
console.log(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",
)

// Skills not loaded: settingSources excludes user and project
const options = {
settingSources: [],
skills: "all"
};

// Skills loaded: user and project sources included
const options = {
settingSources: ["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",
)

// 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 с 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

• Agent Skills в Claude Code: Полное руководство Skills с созданием, примерами и Troubleshooting
• Agent Skills Overview: Концептуальный обзор, преимущества и архитектура
• Agent Skills Best Practices: Рекомендации по разработке эффективных Skills
• Agent Skills Cookbook: Примеры Skills и шаблоны

Ресурсы SDK

• Subagents в SDK: Похожие агенты на основе файловой системы с программными опциями
• Slash Commands в SDK: Команды, вызываемые пользователем
• Обзор SDK: Общие концепции SDK
• Справочник TypeScript SDK: Полная документация API
• Справочник Python SDK: Полная документация API