СообщенияНавыки

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

Узнайте, как использовать Agent Skills для расширения возможностей Claude через API.

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

Полную справку по API, включая схемы запросов/ответов и все параметры, см. в разделах:

Справочник по Skill Management API — CRUD-операции для навыков
Справочник по Skill Versions API — управление версиями

Эта функция не подпадает под действие политики Zero Data Retention (ZDR). Данные хранятся в соответствии со стандартной политикой хранения данных для этой функции.

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

Начало работы с Agent Skills

Создайте свой первый навык

Создание пользовательских навыков

Лучшие практики по созданию навыков

Обзор

Для глубокого погружения в архитектуру и практическое применение Agent Skills прочитайте инженерную статью в блоге: Equipping agents for the real world with Agent Skills.

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

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

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

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

Аспект	Навыки Anthropic	Пользовательские навыки
Значение type	`anthropic`	`custom`
Идентификаторы навыков	Короткие имена: `pptx`, `xlsx`, `docx`, `pdf`	Сгенерированные: `skill_01AbCdEfGhIjKlMnOpQrStUv`
Формат версии	На основе даты: `20251013` или `latest`	Временная метка эпохи: `1759178010641129` или `latest`
Управление	Готовые, поддерживаются Anthropic	Загружаются и управляются через Skills API
Доступность	Доступны всем пользователям	Приватны для вашего рабочего пространства

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

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

Для использования навыков вам нужны:

Ключ API Claude из Console
Бета-заголовки:
- code-execution-2025-08-25 — включает выполнение кода (требуется для навыков)
- skills-2025-10-02 — включает Skills API
- files-api-2025-04-14 — для загрузки/скачивания файлов в контейнер и из него
Инструмент выполнения кода, включённый в ваших запросах

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

Параметр container

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

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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.

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

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

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

client = anthropic.Anthropic()

# Шаг 1: используйте Skill для создания файла
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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":
                # список с конкретным типом: List[BashCodeExecutionOutputBlock]
                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_abc123"
# Получить метаданные файла
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

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

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

Полные сведения о Files API см. в документации по Files API.

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

Повторно используйте один и тот же контейнер в нескольких сообщениях, указав идентификатор контейнера:

# Первый запрос создаёт контейнер
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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 this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Продолжаем диалог с тем же контейнером
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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:

messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 i 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-4-8",
        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"}],
    )

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

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

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

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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, которая принимает путь к каталогу.

# Вариант 1: загрузка отдельных файлов (один флаг --file на каждый файл)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Вариант 2: загрузка zip-архива
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

Требования:

Должен включать файл SKILL.md на верхнем уровне
Все файлы должны указывать общий корневой каталог в своих путях
Общий размер загрузки должен быть менее 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

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

Чтобы удалить навык, сначала необходимо удалить все его версии:

# Шаг 1: выведите список версий, затем удалите каждую из них
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output

# Повторите для каждого идентификатора версии, возвращённого списком
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 20260115.120000 >/dev/null

# Шаг 2: удалите навык
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

Попытка удалить навык с существующими версиями возвращает ошибку 400.

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

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

Навыки Anthropic:

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

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

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

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

# Использовать конкретную версию
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-8
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 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-8
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 для полных сведений.

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

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

Обнаружение метаданных: Claude видит метаданные для каждого навыка (имя, описание) в системной подсказке
Загрузка файлов: файлы навыка копируются в контейнер по пути /skills/{directory}/
Автоматическое использование: Claude автоматически загружает и использует навыки, когда они релевантны вашему запросу
Композиция: несколько навыков комбинируются для сложных рабочих процессов

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

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

Организационные навыки

Бренд и коммуникации

Применение корпоративного форматирования (цвета, шрифты, макеты) к документам
Генерация коммуникаций по организационным шаблонам
Обеспечение единых брендовых гайдлайнов во всех результатах

Управление проектами

Структурирование заметок в корпоративных форматах (OKR, журналы решений)
Генерация задач в соответствии с командными соглашениями
Создание стандартизированных резюме встреч и отчётов о статусе

Бизнес-операции

Создание корпоративных стандартных отчётов, предложений и анализов
Выполнение корпоративных аналитических процедур
Генерация финансовых моделей по организационным шаблонам

Персональные навыки

Создание контента

Пользовательские шаблоны документов
Специализированное форматирование и стилизация
Генерация контента для конкретной предметной области

Анализ данных

Пользовательские конвейеры обработки данных
Специализированные шаблоны визуализации
Отраслевые аналитические методы

Разработка и автоматизация

Шаблоны генерации кода
Фреймворки тестирования
Рабочие процессы развёртывания

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

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

# Создайте пользовательский навык (Skill) для DCF-анализа
from anthropic.lib import files_from_dir

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

# Используйте вместе с Excel для создания финансовой модели
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 with the attached financials",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

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

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

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

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

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

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

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

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

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

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

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

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

Избегайте:

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

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

Для продакшена:

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

Для разработки:

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

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

При использовании кэширования подсказок учтите, что изменение списка навыков в вашем контейнере сбрасывает кэш:

# Первый запрос создаёт кэш
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "prompt-caching-2024-07-31",
    ],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Добавление или удаление навыков сбрасывает кэш
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "prompt-caching-2024-07-31",
    ],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest",
            },  # Cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Для наилучшей производительности кэширования сохраняйте список навыков неизменным между запросами.

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

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

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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 и хранение данных.

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

Справочник по API

Полный справочник по API со всеми эндпоинтами

Руководство по созданию

Лучшие практики по написанию эффективных навыков

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

Узнайте о среде выполнения кода

Was this page helpful?

СообщенияНавыки

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

Узнайте, как использовать Agent Skills для расширения возможностей Claude через API.

Полную справку по API, включая схемы запросов/ответов и все параметры, см. в разделах:

Справочник по Skill Management API — CRUD-операции для навыков
Справочник по Skill Versions API — управление версиями

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

Начало работы с Agent Skills

Создайте свой первый навык

Создание пользовательских навыков

Лучшие практики по созданию навыков

Обзор

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

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

Аспект	Навыки Anthropic	Пользовательские навыки
Значение type	`anthropic`	`custom`
Идентификаторы навыков	Короткие имена: `pptx`, `xlsx`, `docx`, `pdf`	Сгенерированные: `skill_01AbCdEfGhIjKlMnOpQrStUv`
Формат версии	На основе даты: `20251013` или `latest`	Временная метка эпохи: `1759178010641129` или `latest`
Управление	Готовые, поддерживаются Anthropic	Загружаются и управляются через Skills API
Доступность	Доступны всем пользователям	Приватны для вашего рабочего пространства

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

Для использования навыков вам нужны:

Ключ API Claude из Console
Бета-заголовки:
- code-execution-2025-08-25 — включает выполнение кода (требуется для навыков)
- skills-2025-10-02 — включает Skills API
- files-api-2025-04-14 — для загрузки/скачивания файлов в контейнер и из него
Инструмент выполнения кода, включённый в ваших запросах

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

Параметр container

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

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

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

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

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

client = anthropic.Anthropic()

# Шаг 1: используйте Skill для создания файла
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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":
                # список с конкретным типом: List[BashCodeExecutionOutputBlock]
                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_abc123"
# Получить метаданные файла
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

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

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

Полные сведения о Files API см. в документации по Files API.

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

Повторно используйте один и тот же контейнер в нескольких сообщениях, указав идентификатор контейнера:

# Первый запрос создаёт контейнер
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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 this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Продолжаем диалог с тем же контейнером
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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:

messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 i 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-4-8",
        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"}],
    )

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

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

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

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

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

# Вариант 1: загрузка отдельных файлов (один флаг --file на каждый файл)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Вариант 2: загрузка zip-архива
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

Требования:

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

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

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

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

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

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

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

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

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

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

Чтобы удалить навык, сначала необходимо удалить все его версии:

# Шаг 1: выведите список версий, затем удалите каждую из них
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output

# Повторите для каждого идентификатора версии, возвращённого списком
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 20260115.120000 >/dev/null

# Шаг 2: удалите навык
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

Попытка удалить навык с существующими версиями возвращает ошибку 400.

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

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

Навыки Anthropic:

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

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

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

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

# Использовать конкретную версию
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-8
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 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-8
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 для полных сведений.

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

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

Обнаружение метаданных: Claude видит метаданные для каждого навыка (имя, описание) в системной подсказке
Загрузка файлов: файлы навыка копируются в контейнер по пути /skills/{directory}/
Автоматическое использование: Claude автоматически загружает и использует навыки, когда они релевантны вашему запросу
Композиция: несколько навыков комбинируются для сложных рабочих процессов

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

Организационные навыки

Бренд и коммуникации

Применение корпоративного форматирования (цвета, шрифты, макеты) к документам
Генерация коммуникаций по организационным шаблонам
Обеспечение единых брендовых гайдлайнов во всех результатах

Управление проектами

Структурирование заметок в корпоративных форматах (OKR, журналы решений)
Генерация задач в соответствии с командными соглашениями
Создание стандартизированных резюме встреч и отчётов о статусе

Бизнес-операции

Создание корпоративных стандартных отчётов, предложений и анализов
Выполнение корпоративных аналитических процедур
Генерация финансовых моделей по организационным шаблонам

Персональные навыки

Создание контента

Пользовательские шаблоны документов
Специализированное форматирование и стилизация
Генерация контента для конкретной предметной области

Анализ данных

Пользовательские конвейеры обработки данных
Специализированные шаблоны визуализации
Отраслевые аналитические методы

Разработка и автоматизация

Шаблоны генерации кода
Фреймворки тестирования
Рабочие процессы развёртывания

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

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

# Создайте пользовательский навык (Skill) для DCF-анализа
from anthropic.lib import files_from_dir

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

# Используйте вместе с Excel для создания финансовой модели
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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 with the attached financials",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)

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

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

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

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

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

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

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

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

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

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

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

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

Избегайте:

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

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

Для продакшена:

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

Для разработки:

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

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

# Первый запрос создаёт кэш
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "prompt-caching-2024-07-31",
    ],
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Добавление или удаление навыков сбрасывает кэш
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=[
        "code-execution-2025-08-25",
        "skills-2025-10-02",
        "prompt-caching-2024-07-31",
    ],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest",
            },  # Cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Для наилучшей производительности кэширования сохраняйте список навыков неизменным между запросами.

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

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

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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

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

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

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

Справочник по API

Полный справочник по API со всеми эндпоинтами

Руководство по созданию

Лучшие практики по написанию эффективных навыков

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

Узнайте о среде выполнения кода

Was this page helpful?

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

Обзор

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

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

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

Параметр container

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

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

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

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

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

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

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

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

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

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

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

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

Организационные навыки

Персональные навыки

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

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

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

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

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

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

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

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

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

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

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

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

Обзор

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

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

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

Параметр container

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

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

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

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

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

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

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

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

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

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

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

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

Организационные навыки

Персональные навыки

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

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

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

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

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

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

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

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

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

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

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

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

Обзор

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

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

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

Параметр container

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

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

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

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

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

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

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

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

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

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

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

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

Организационные навыки

Персональные навыки

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

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

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

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

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

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

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

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

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

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

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

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

Обзор

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

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

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

Параметр container

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

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

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

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

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

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

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

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

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

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

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

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

Организационные навыки

Персональные навыки

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

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

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

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

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

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

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

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

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

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

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