Agent Skills в SDK

Обзор

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

Как Skills работают с SDK

При использовании Claude Agent SDK Skills:

Определяются как артефакты файловой системы: Создаются как файлы SKILL.md в определённых каталогах (.claude/skills/)
Загружаются из файловой системы: Skills загружаются из расположений файловой системы, управляемых settingSources (TypeScript) или setting_sources (Python)
Автоматически обнаруживаются: После загрузки параметров файловой системы метаданные Skill обнаруживаются при запуске из пользовательских и проектных каталогов; полное содержимое загружается при срабатывании
Вызываются моделью: Claude автономно выбирает, когда их использовать, на основе контекста
Фильтруются через опцию skills: Обнаруженные Skills включены по умолчанию. Передайте список имён Skills, "all" или [] для управления доступными в сеансе

В отличие от subagents (которые можно определить программно), Skills должны быть созданы как артефакты файловой системы. SDK не предоставляет программный API для регистрации Skills.

Skills обнаруживаются через источники параметров файловой системы. С параметрами query() по умолчанию SDK загружает пользовательские и проектные источники, поэтому Skills в ~/.claude/skills/, <cwd>/.claude/skills/ и .claude/skills/ в любом родительском каталоге <cwd> вплоть до корня репозитория доступны. Если вы явно установите settingSources, включите 'user' или 'project' для сохранения обнаружения Skills, или используйте опцию plugins для загрузки Skills из определённого пути.

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

Установите опцию skills на query() для управления тем, какие Skills доступны для сеанса. Если опция опущена, обнаруженные Skills включены и инструмент Skill доступен, что соответствует поведению CLI. Передайте "all" для включения каждого обнаруженного Skill, список имён Skill для включения только тех или [] для отключения всех. Когда вы устанавливаете skills, SDK автоматически добавляет инструмент Skill в allowedTools. Если вы также передаёте явный список tools, включите "Skill" в этот список, чтобы Claude мог вызывать skills. После настройки 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: Рекомендации по разработке и соглашения об именовании

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

Поле frontmatter allowed-tools в SKILL.md поддерживается только при прямом использовании Claude Code CLI. Оно не применяется при использовании Skills через SDK.При использовании SDK управляйте доступом к инструментам через основную опцию allowedTools в конфигурации запроса.

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

Agent SDK

Основные концепции

Ввод и вывод

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

Настройка поведения

Управление и наблюдаемость

Развертывание

Справочные материалы SDK

Обзор

Как Skills работают с SDK

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

Расположение Skills

Создание Skills

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

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

Тестирование Skills

Troubleshooting

Skills не найдены

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

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

Руководства Skills

Ресурсы SDK

​Обзор

​Как Skills работают с SDK

​Использование Skills с SDK

​Расположение Skills

​Создание Skills

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

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

​Тестирование Skills

​Troubleshooting

​Skills не найдены

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

​Дополнительное Troubleshooting

​Связанная документация

​Руководства Skills

​Ресурсы SDK

Обзор

Как Skills работают с SDK

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

Расположение Skills

Создание Skills

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

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

Тестирование Skills

Troubleshooting

Skills не найдены

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

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

Связанная документация

Руководства Skills

Ресурсы SDK