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

Agent Skills (навыки агентов) расширяют возможности Claude с помощью организованных папок с инструкциями, скриптами и ресурсами. В этом руководстве показано, как использовать как готовые, так и пользовательские навыки (Skills) с Claude API.

Быстрые ссылки

Обзор

Навыки интегрируются с Messages API через инструмент выполнения кода (code execution tool). Независимо от того, используете ли вы готовые навыки, управляемые Anthropic, или загруженные вами пользовательские навыки, форма интеграции идентична: оба варианта требуют выполнения кода и используют одну и ту же структуру container.

Использование навыков

Навыки интегрируются в Messages API одинаково независимо от источника. Вы указываете навыки в параметре container с помощью skill_id, type и необязательного version, и они выполняются в среде выполнения кода.

Вы можете использовать навыки из двух источников:

Оба источника навыков возвращаются конечной точкой List Skills (используйте параметр source для фильтрации). Форма интеграции и среда выполнения идентичны. Единственное различие — откуда берутся навыки и как ими управляют.

Предварительные требования

Для использования навыков вам потребуется:

1. Ключ API Claude из Claude Console
2. Инструмент выполнения кода, включённый в ваших запросах

Навыки требуют инструмента выполнения кода, поэтому используйте модель из его списка совместимых моделей.

Использование навыков в Messages

Параметр container

Навыки указываются с помощью параметра container в Messages API. Вы можете включить до 20 навыков в каждый запрос.

Структура идентична как для навыков Anthropic, так и для пользовательских навыков. Укажите обязательные type и skill_id и при необходимости добавьте version, чтобы закрепить конкретную версию:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a presentation about renewable energy"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Скачивание сгенерированных файлов

Когда навыки создают документы (Excel, PowerPoint, PDF, Word), они возвращают атрибуты file_id в ответе. Для скачивания этих файлов необходимо использовать Files API.

Как это работает:

1. Навыки создают файлы во время выполнения кода.
2. Ответ включает file_id для каждого созданного файла внутри блоков результатов инструмента выполнения кода (см. Формат ответа).
3. Используйте Files API для скачивания фактического содержимого файла.
4. Сохраните локально или обработайте по необходимости.

Чтобы предоставить входные файлы, с которыми будут работать навыки, загрузите их с помощью Files API и сошлитесь на них в запросе с помощью блока container upload.

Пример: создание и скачивание файла Excel

client = anthropic.Anthropic()

# Шаг 1: создайте файл с помощью Skill
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[
        {
            "role": "user",
            "content": "Create an Excel file with a simple budget spreadsheet",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)


# Шаг 2: извлеките идентификаторы файлов из ответа
def extract_file_ids(response):
    file_ids = []
    for item in response.content:
        if item.type == "bash_code_execution_tool_result":
            content_item = item.content
            if content_item.type == "bash_code_execution_result":
                # каждый элемент content — это блок bash_code_execution_output с file_id
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Шаг 3: скачайте файл через Files API
for file_id in extract_file_ids(response):
    file_metadata = client.files.retrieve_metadata(file_id=file_id)
    file_content = client.files.download(file_id=file_id)

    # Шаг 4: сохраните на диск
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Дополнительные операции Files API:

client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Получить метаданные файла
file_info = client.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Вывести список всех файлов
for file in client.files.list():
    print(f"{file.filename} - {file.created_at}")

# Удалить файл
client.files.delete(file_id=file_id)

Многоходовые диалоги

Объект container в ответе содержит id контейнера и временную метку expires_at (подробности о времени жизни см. в разделе Повторное использование контейнера). Повторно используйте один и тот же контейнер в нескольких сообщениях, указав идентификатор контейнера:

client = anthropic.Anthropic()

# Первый запрос создаёт контейнер
response1 = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[
        {"role": "user", "content": "Create a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Продолжаем диалог с тем же контейнером
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Передаём текст ассистента дальше; container.id хранит состояние выполнения
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "id": response1.container.id,  # Reuse container
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}],
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Длительные операции

Навыки могут выполнять операции, требующие нескольких ходов. Обрабатывайте причины остановки pause_turn:

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Обработка pause_turn для длительных операций
for _ in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=4096,
        container={
            "id": response.container.id,
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ],
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )

Использование нескольких навыков

Объединяйте несколько навыков в одном запросе для обработки сложных рабочих процессов:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"},
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            },
        ]
    },
    messages=[
        {"role": "user", "content": "Analyze sales data and create a presentation"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Управление пользовательскими навыками

Создание навыка

Пакет навыка — это каталог, содержащий на верхнем уровне файл SKILL.md с YAML frontmatter name и description, а также любые вспомогательные скрипты или ресурсы. См. Начало работы с Agent Skills в API, чтобы создать такой пакет, и список Требования после примеров для полного перечня ограничений.

Загрузите свой пользовательский навык, чтобы сделать его доступным в рабочем пространстве. Можно загрузить zip-архив или отдельные файловые объекты. Python SDK также предоставляет вспомогательную функцию files_from_dir, принимающую путь к каталогу, а команда CLI ant apply загружает сам каталог.

Файлы идентифицируются по имени файла, которое вы прикрепляете (суффикс ;filename= в примере cURL и аргументы имени файла в примерах SDK). Для навыка из пошагового руководства создайте zip-архив командой zip -r financial_skill.zip financial_skill/ и подставьте его вместо заполнителя example_skill.zip в вариантах загрузки zip.

ant apply financial_skill

---
name: financial-skill
description: Docs example skill.
---

print("financial analysis helper")

Требования:

• Должен включать файл SKILL.md в корне загрузки (или на верхнем уровне единственной объемлющей папки)
• display_name необязателен: если он опущен, он выводится из name в SKILL.md; явное значение может содержать до 255 символов и не обязано быть уникальным в рабочем пространстве
• Общий размер загрузки должен быть менее 30 МБ (в несжатом виде)
• Требования к YAML frontmatter:
  • name: максимум 64 символа, только строчные буквы/цифры/дефисы, без XML-тегов, без зарезервированных слов ("anthropic", "claude")
  • description: максимум 1024 символа, непустое, без XML-тегов

Полные схемы запросов/ответов см. в справочнике API Create Skill.

Получение списка навыков

Получите все навыки, доступные вашему рабочему пространству, включая как готовые навыки Anthropic, так и ваши пользовательские навыки. Используйте параметр source для фильтрации по типу навыка:

client = anthropic.Anthropic()

# Вывести список всех Skills
for skill in client.skills.list():
    print(f"{skill.id}: {skill.display_name} (source: {skill.source.type})")

# Вывести только пользовательские Skills
custom_skills = client.skills.list(source="custom")

Параметры пагинации и фильтрации см. в справочнике API List Skills.

Получение навыка

Получите сведения о конкретном навыке:

client = anthropic.Anthropic()

skill = client.skills.retrieve(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")

print(f"Skill: {skill.display_name}")
print(f"Latest version: {skill.latest_version_id}")
print(f"Created: {skill.created_at}")

Удаление навыка

Удаление навыка также удаляет все его версии.

client = anthropic.Anthropic()

client.skills.delete(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")

Версионирование

Навыки поддерживают версионирование для безопасного управления обновлениями:

Навыки Anthropic:

• Версии используют формат даты: 20251013
• Новые версии выпускаются по мере внесения обновлений
• Указывайте точные версии для стабильности

Пользовательские навыки:

• Автоматически генерируемые идентификаторы версий: skver_01AbCdEfGhIjKlMnOpQrStUv
• Используйте "latest", чтобы всегда получать самую последнюю версию
• Создавайте новые версии при обновлении файлов навыка

Новая версия — это полный снимок, а не дельта: каждый раз загружайте полный набор файлов навыка. Пропущенные файлы не переносятся, а name в SKILL.md новой версии должен совпадать с существующим именем навыка. В следующих примерах повторно загружается полный пакет financial_skill/ из раздела Создание навыка.

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Создать новую версию

new_version = client.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("financial_skill"),
)

# Использовать конкретную версию
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": new_version.id,
            }
        ]
    },
    messages=[{"role": "user", "content": "Use updated Skill"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Использовать последнюю версию
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=[{"role": "user", "content": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Полную информацию см. в справочнике API Create Skill Version.

Как загружаются навыки

Когда вы указываете навыки в контейнере:

1. Обнаружение метаданных: Claude видит метаданные каждого навыка (имя, описание) в системной подсказке.
2. Загрузка файлов: файлы навыка копируются в контейнер по пути /skills/{skill-name}/. Каталог — это имя навыка (pptx для навыка Anthropic, name из SKILL.md для пользовательского навыка), а не его идентификатор skill_01....
3. Автоматическое использование: Claude автоматически загружает и использует навыки, когда они релевантны вашему запросу.
4. Композиция: несколько навыков объединяются для сложных рабочих процессов.

Claude загружает полные инструкции навыка только при необходимости.

Сценарии использования

Навыки подходят как для организационной, так и для личной работы. Организации используют их для применения фирменного форматирования к документам, структурирования заметок и отчётов по шаблонам компании и выполнения специфичных для компании аналитических процедур. Отдельные пользователи применяют их для пользовательских шаблонов документов, специализированных конвейеров данных, а также соглашений по генерации кода или развёртыванию.

Пример: финансовое моделирование

Объедините навык Excel и пользовательский навык для DCF-анализа. Сначала создайте пользовательский навык для DCF-анализа:

ant apply dcf_skill

Затем используйте его вместе с навыком Excel, чтобы создать финансовую модель. Передайте идентификатор созданного вами навыка в качестве skill_id пользовательского навыка:

client = anthropic.Anthropic()

# Пользовательский Skill для DCF-анализа (ID получен из ответа Skills API на создание)
dcf_skill_id = "skill_01AbCdEfGhIjKlMnOpQrStUv"

# Используйте вместе с Excel для создания финансовой модели
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "custom", "skill_id": dcf_skill_id, "version": "latest"},
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "Build a DCF valuation model for a SaaS company",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

Лимиты и ограничения

Лимиты запросов

• Максимальное количество навыков на запрос: 20
• Максимальный размер загрузки навыка: 30 МБ (все файлы вместе, в несжатом виде)
• Требования к YAML frontmatter:
  • name: максимум 64 символа, только строчные буквы/цифры/дефисы, без XML-тегов, без зарезервированных слов ("anthropic", "claude")
  • description: максимум 1024 символа, непустое, без XML-тегов

Ограничения среды

Навыки выполняются в контейнере выполнения кода со следующими ограничениями:

• Нет доступа к сети: невозможно выполнять внешние вызовы API
• Нет установки пакетов во время выполнения: доступны только предустановленные пакеты
• Изолированная среда: создаётся новый контейнер, если вы не укажете идентификатор существующего контейнера

Доступные пакеты см. в разделе Инструмент выполнения кода.

Лучшие практики

Когда использовать несколько навыков

Объединяйте навыки, когда задачи включают несколько типов документов или предметных областей:

Хорошие сценарии использования:

• Анализ данных (Excel) + создание презентации (PowerPoint)
• Генерация отчёта (Word) + экспорт в PDF
• Пользовательская предметная логика + генерация документов

Избегайте:

• Включения неиспользуемых навыков (влияет на производительность)

Стратегия управления версиями

Вкладки SDK в этом разделе показывают значение container, которое нужно включить в запрос Messages. Вкладки cURL и CLI показывают полный запрос.

Для продакшена: закрепите конкретную версию, чтобы обновления навыка никогда не меняли поведение вашего развёрнутого решения. Если вы опустите version или установите его в "latest", запросы будут использовать самую новую версию навыка, поэтому версия, загруженная кем-либо в рабочем пространстве, немедленно изменит то, что выполняют ваши продакшен-агенты. Идентификатор версии берётся из ответа на создание версии в разделе Версионирование или из API List Skill Versions. Идентификатор всегда является строкой, поэтому заключайте его в кавычки в JSON или YAML, даже если он выглядит как число.

# Закрепите конкретные версии для стабильности
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "skver_01AbCdEfGhIjKlMnOpQrStUv",
        }
    ]
}

Для разработки: используйте latest, чтобы автоматически получать самую новую версию в процессе итераций.

# Используйте latest при активной разработке
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",
        }
    ]
}

Особенности кэширования подсказок

Если вы используете кэширование подсказок (prompt caching), изменение списка навыков в вашем контейнере нарушает кэш. Навыки отображаются в системной подсказке в фиксированном порядке, поэтому один и тот же список даёт один и тот же кэшируемый префикс:

client = anthropic.Anthropic()

# Skills попадают в системную подсказку в фиксированном порядке, удобном для кэширования
response1 = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Изменение списка Skills ([xlsx] vs [xlsx, pptx]) меняет префикс — промах кэша; идентичный список — попадание в кэш
response2 = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest",
            },  # prefix change: cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Для наилучшей производительности кэширования сохраняйте список навыков, включая его порядок, неизменным между запросами. Закрепление версий пользовательских навыков также помогает: при использовании "latest" публикация новой версии может сделать кэшированный префикс недействительным, если она изменяет описание навыка.

Обработка ошибок

Корректно обрабатывайте ошибки, связанные с навыками:

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=4096,
        container={
            "skills": [
                {
                    "type": "custom",
                    "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                    "version": "latest",
                }
            ]
        },
        messages=[{"role": "user", "content": "Process data"}],
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )
except anthropic.BadRequestError as e:
    if "skill" in str(e):
        print(f"Skill error: {e}")
        # Обработка ошибок, специфичных для навыков
    else:
        raise

Миграция с skills-2025-10-02

Skills API вышел из бета-версии и не требует бета-заголовка. Миграция с skills-2025-10-02 необязательна: запросы, которые по-прежнему его отправляют, продолжают работать и продолжают возвращать формы ответов бета-версии, поэтому существующая интеграция продолжает работать, пока вы её не измените. Удаление заголовка переключает эти запросы на формы, описанные на этой странице:

Для миграции:

1. Удалите бета-заголовок. Уберите anthropic-beta: skills-2025-10-02 из ваших запросов. В SDK вызывайте client.skills вместо client.beta.skills; сохранение client.beta.skills работает только в выпусках SDK, которые больше не отправляют заголовок. Более ранние выпуски отправляют его из client.beta.skills даже без аргумента betas.
2. Переименуйте поля в вашем коде: display_title в display_name, latest_version в latest_version_id, и читайте source.type вместо сравнения source со строкой.
3. Используйте идентификаторы версий. Везде, где вы хранили версию в микросекундах эпохи, храните вместо неё id версии или используйте latest. Ссылки на навыки в запросах Messages принимают идентификатор версии, latest или (для навыков Anthropic) версию каталога.
4. Проверьте вызовы удаления. DELETE /v1/skills/{skill_id} теперь удаляет все версии вместе с навыком. Если вы полагались на отказ бета-версии как на защитный механизм, добавьте собственную проверку.

Навык, все версии которого были удалены в бета-версии, не имеет текущей версии для возврата: GET /v1/skills/{skill_id} возвращает ошибку 400, и навык исключается из ответов со списками, пока вы не загрузите в него версию. Вы по-прежнему можете его удалить.

Пространство имён beta в SDK

Начиная с Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, Ruby SDK 1.67.0 и C# SDK 12.44.0, client.beta.skills больше не отправляет skills-2025-10-02 и возвращает те же формы, что и client.skills, с именами типов с префиксом Beta (BetaSkill, BetaSkillVersion, BetaDeletedSkill, BetaDeletedSkillVersion). Он принимает аргумент betas для функций навыков, которые всё ещё находятся в бета-версии. В бета-типах Messages тип ссылки на навык в контейнере переименован из BetaSkill в BetaContainerSkill (те же поля: type, skill_id, version); BetaSkill теперь обозначает ресурс навыка, соответствуя Skill и ContainerSkill в не-бета-типах. Более ранние выпуски SDK типизированы под формы бета-версии; если вы зависите от этих типов, оставайтесь на более раннем выпуске до миграции.

Хранение данных

Agent Skills не подпадают под соглашения ZDR. Определения навыков и данные выполнения хранятся в соответствии со стандартной политикой хранения данных Anthropic.

Сведения о применимости ZDR ко всем функциям см. в разделе API и хранение данных.

Журнал аудита

Если в вашей организации включён Compliance API, его лента активности (Activity Feed) фиксирует создание и удаление навыков и версий навыков, выполненные с помощью ключа API Claude или из Claude Console. Операции, происходящие при выключенном Compliance API, не фиксируются и не могут быть восстановлены позже, поэтому настройте Compliance API, прежде чем полагаться на этот журнал аудита.

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