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

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



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



Обзор

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



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

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

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

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



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

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

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

Навыки общедоступны в Claude API и не требуют заголовка anthropic-beta — ни для Skills API, ни для container.skills в запросах Messages. Примеры в этом руководстве по-прежнему отправляют бета-заголовок skills-2025-10-02 (плюс code-execution-2025-08-25 в запросах Messages) и используют пространство имён beta в SDK. Оба заголовка остаются допустимыми способами явного включения функций, поэтому примеры работают как написано, и вы можете опустить их в собственных запросах.

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



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



Параметр container

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

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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 и сошлитесь на них в вашем запросе с помощью блока загрузки в контейнер.

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

client = anthropic.Anthropic()

# Шаг 1: используйте Skill для создания файла
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.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.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

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

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



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

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

client = anthropic.Anthropic()

# Первый запрос создаёт контейнер
response1 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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.beta.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        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.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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-фронтматтером name и description, а также любые вспомогательные скрипты или ресурсы. См. Начало работы с Agent Skills в API, чтобы создать такой пакет, и список Требования после примеров для полного перечня ограничений.

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

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

zip -r financial_skill.zip financial_skill/
ant beta:skills create \
  --file financial_skill.zip \
  --beta skills-2025-10-02

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

print("financial analysis helper")

Требования:

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

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



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

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

# Вывести список всех навыков
ant beta:skills list

# Вывести список только пользовательских навыков
ant beta:skills list --source custom

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



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

Получите подробную информацию о конкретном навыке:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv



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

Удаление навыка также удаляет все его версии. Каскадное удаление — это поведение, доступное только в GA, поэтому, в отличие от других примеров в этом руководстве, эти примеры обращаются напрямую к GA-интерфейсу, а не к пространству имён beta.

ant skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null



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

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

Навыки Anthropic:

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

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

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

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

# Создать новую версию
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file financial_skill.zip \
  --transform version \
  --raw-output)

# Использовать конкретную версию
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: "$VERSION_NUMBER"
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Использовать последнюю версию
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-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
YAML

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



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

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

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

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



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

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



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

Объедините навыки Excel и пользовательского DCF-анализа:

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Создайте пользовательский Skill для DCF-анализа

dcf_skill = client.beta.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# Используйте вместе с Excel для создания финансовой модели
response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    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-фронтматтеру:
  • name: максимум 64 символа, только строчные буквы/цифры/дефисы, без XML-тегов, без зарезервированных слов («anthropic», «claude»)
  • description: максимум 1024 символа, непустое, без XML-тегов



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

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

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

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



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



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

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

Подходящие сценарии:

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

Избегайте:

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



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

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

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

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

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

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



Соображения по кэшированию подсказок

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

client = anthropic.Anthropic()

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

# Изменение списка навыков ([xlsx] вместо [xlsx, pptx]) меняет префикс — промах кэша; идентичный список — попадание в кэш
response2 = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
    ],
    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.beta.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        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



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

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

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



Журналирование аудита

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



Дальнейшие шаги