Навыки агента в SDK

Обзор

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

Для получения полной информации о Skills, включая преимущества, архитектуру и рекомендации по созданию, см. обзор Agent Skills.

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

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

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

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

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

Для использования Skills с SDK вам необходимо:

1. Включить "Skill" в конфигурацию allowed_tools
2. Настроить settingSources/setting_sources для загрузки 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
        allowed_tools=["Skill", "Read", "Write", "Bash"]  # Enable Skill tool
    )

    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
    allowedTools: ["Skill", "Read", "Write", "Bash"]  // Enable Skill tool
  }
})) {
  console.log(message);
}

Расположение 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:

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill", "Read", "Grep", "Glob"]  # Restricted toolset
)

async for message in query(
    prompt="Analyze the codebase structure",
    options=options
):
    print(message)

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

Чтобы узнать, какие Skills доступны в вашем приложении SDK, просто спросите Claude:

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill"]
)

async for message in query(
    prompt="What Skills are available?",
    options=options
):
    print(message)

Claude выведет список доступных Skills на основе вашего текущего рабочего каталога и установленных плагинов.

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

Протестируйте Skills, задав вопросы, соответствующие их описаниям:

options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill", "Read", "Bash"]
)

async for message in query(
    prompt="Extract text from invoice.pdf",
    options=options
):
    print(message)

Claude автоматически вызывает соответствующий Skill, если описание совпадает с вашим запросом.

Устранение неполадок

Skills не найдены

Проверьте конфигурацию settingSources: Skills загружаются только при явной настройке settingSources/setting_sources. Это наиболее распространённая проблема:

# Wrong - Skills won't be loaded
options = ClaudeAgentOptions(
    allowed_tools=["Skill"]
)

# Correct - Skills will be loaded
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

Для получения дополнительной информации о settingSources/setting_sources см. справочник TypeScript SDK или справочник Python SDK.

Проверьте рабочий каталог: SDK загружает Skills относительно параметра cwd. Убедитесь, что он указывает на каталог, содержащий .claude/skills/:

# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # Must contain .claude/skills/
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

Полный шаблон см. в разделе "Использование Skills с SDK" выше.

Проверьте расположение файловой системы:

# Check project Skills
ls .claude/skills/*/SKILL.md

# Check personal Skills
ls ~/.claude/skills/*/SKILL.md

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

Проверьте, что инструмент Skill включен: Убедитесь, что "Skill" находится в вашем allowedTools.

Проверьте описание: Убедитесь, что оно конкретно и включает соответствующие ключевые слова. См. Agent Skills Best Practices для руководства по написанию эффективных описаний.

Дополнительное устранение неполадок

Для общего устранения неполадок Skills (синтаксис YAML, отладка и т.д.) см. раздел устранения неполадок Claude Code Skills.

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

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

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

Ресурсы SDK

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