Agent Skills

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

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

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

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

Справка по API управления Skills - операции CRUD для Skills
Справка по API версий Skills - управление версиями

This feature is in beta and is not covered by Zero Data Retention (ZDR) arrangements. Beta features are excluded from ZDR.

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

Начните работу с Agent Skills

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

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

Лучшие практики для создания Skills

Обзор

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

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

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

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

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

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

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

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

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

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

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

Параметр Container

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

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

import anthropic

client = anthropic.Anthropic()

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

Скачивание созданных файлов

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

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

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

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

import anthropic

client = anthropic.Anthropic()

# Step 1: Use a Skill to create a file
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)


# Step 2: Extract file IDs from the response
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":
                for file in content_item.content:
                    if hasattr(file, "file_id"):
                        file_ids.append(file.file_id)
    return file_ids


# Step 3: Download the file using Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(
        file_id=file_id, betas=["files-api-2025-04-14"]
    )
    file_content = client.beta.files.download(
        file_id=file_id, betas=["files-api-2025-04-14"]
    )

    # Step 4: Save to disk
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

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

# Get file metadata
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id, betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# List all files
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Delete a file
client.beta.files.delete(file_id=file_id, betas=["files-api-2025-04-14"])

Для полной информации о Files API см. документацию Files API.

Многооборотные беседы

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

# First request creates container
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)

# Continue conversation with same container
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-6",
    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"}],
)

Долгосрочные операции

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

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

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

# Handle pause_turn for long operations
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-6",
        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 приостановил долгосрочную операцию Skill. Вы можете предоставить ответ как есть в последующем запросе, чтобы позволить Claude продолжить свой ход, или изменить содержимое, если вы хотите прервать беседу и предоставить дополнительное руководство.

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

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

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

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

Создание Skill

Загрузите свой пользовательский Skill, чтобы сделать его доступным в вашем рабочем пространстве. Вы можете загружать, используя либо путь к папке, либо отдельные объекты файлов.

import anthropic

client = anthropic.Anthropic()

# Option 1: Using files_from_dir helper (Python only, recommended)
from anthropic.lib import files_from_dir

skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=files_from_dir("/path/to/financial_analysis_skill"),
    betas=["skills-2025-10-02"],
)

# Option 2: Using a zip file
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"],
)

# Option 3: Using file tuples (filename, file_content, mime_type)
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        (
            "financial_skill/SKILL.md",
            open("financial_skill/SKILL.md", "rb"),
            "text/markdown",
        ),
        (
            "financial_skill/analyze.py",
            open("financial_skill/analyze.py", "rb"),
            "text/x-python",
        ),
    ],
    betas=["skills-2025-10-02"],
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")

Требования:

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

Для полных схем запросов/ответов см. справку по API Create Skill.

Список Skills

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

# List all Skills
skills = client.beta.skills.list(betas=["skills-2025-10-02"])

for skill in skills.data:
    print(f"{skill.id}: {skill.display_title} (source: {skill.source})")

# List only custom Skills
custom_skills = client.beta.skills.list(source="custom", betas=["skills-2025-10-02"])

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

Получение Skill

Получите информацию о конкретном Skill:

skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", betas=["skills-2025-10-02"]
)

print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")
print(f"Created: {skill.created_at}")

Удаление Skill

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

# Step 1: Delete all versions
versions = client.beta.skills.versions.list(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", betas=["skills-2025-10-02"]
)

for version in versions.data:
    client.beta.skills.versions.delete(
        skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
        version=version.version,
        betas=["skills-2025-10-02"],
    )

# Step 2: Delete the Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", betas=["skills-2025-10-02"]
)

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

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

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

Skills, управляемые Anthropic:

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

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

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

# Создать новую версию
from anthropic.lib import files_from_dir

new_version = client.beta.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("/path/to/updated_skill"),
    betas=["skills-2025-10-02"],
)

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

# Использовать последнюю версию
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Полные сведения см. в справочнике API Create Skill Version.

Как загружаются Skills

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

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

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

Варианты использования

Организационные Skills

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

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

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

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

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

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

Личные Skills

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

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

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

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

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

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

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

Объедините Excel и пользовательские Skills анализа 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"),
    betas=["skills-2025-10-02"],
)

# Использовать с Excel для создания финансовой модели
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)

Ограничения и ограничения

Ограничения запроса

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

Ограничения окружения

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

Нет доступа в сеть - Не может выполнять внешние вызовы API
Нет установки пакетов во время выполнения - Доступны только предустановленные пакеты
Изолированная среда - Каждый запрос получает свежий контейнер

Полный список доступных пакетов см. в документации инструмента выполнения кода.

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

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

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

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

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

Избегайте:

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

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

Для производства:

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

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

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

Рассмотрения кэширования подсказок

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

# Первый запрос создает кэш
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)

# Добавление/удаление Skills нарушает кэш
response2 = client.beta.messages.create(
    model="claude-opus-4-6",
    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",
            },  # Промах кэша
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

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

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

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

try:
    response = client.beta.messages.create(
        model="claude-opus-4-6",
        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}")
        # Обработайте ошибки, специфичные для Skill
    else:
        raise

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

Справочник API

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

Руководство по авторству

Лучшие практики для написания эффективных Skills

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

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

Was this page helpful?

Agent Skills

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

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

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

Справка по API управления Skills - операции CRUD для Skills
Справка по API версий Skills - управление версиями

This feature is in beta and is not covered by Zero Data Retention (ZDR) arrangements. Beta features are excluded from ZDR.

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

Начните работу с Agent Skills

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

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

Лучшие практики для создания Skills

Обзор

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

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

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

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

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

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

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

Параметр Container

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

import anthropic

client = anthropic.Anthropic()

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

Скачивание созданных файлов

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

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

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

import anthropic

client = anthropic.Anthropic()

# Step 1: Use a Skill to create a file
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)


# Step 2: Extract file IDs from the response
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":
                for file in content_item.content:
                    if hasattr(file, "file_id"):
                        file_ids.append(file.file_id)
    return file_ids


# Step 3: Download the file using Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(
        file_id=file_id, betas=["files-api-2025-04-14"]
    )
    file_content = client.beta.files.download(
        file_id=file_id, betas=["files-api-2025-04-14"]
    )

    # Step 4: Save to disk
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

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

# Get file metadata
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id, betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# List all files
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Delete a file
client.beta.files.delete(file_id=file_id, betas=["files-api-2025-04-14"])

Для полной информации о Files API см. документацию Files API.

Многооборотные беседы

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

# First request creates container
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)

# Continue conversation with same container
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-6",
    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"}],
)

Долгосрочные операции

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

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

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

# Handle pause_turn for long operations
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-6",
        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"}],
    )

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

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

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

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

Создание Skill

import anthropic

client = anthropic.Anthropic()

# Option 1: Using files_from_dir helper (Python only, recommended)
from anthropic.lib import files_from_dir

skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=files_from_dir("/path/to/financial_analysis_skill"),
    betas=["skills-2025-10-02"],
)

# Option 2: Using a zip file
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"],
)

# Option 3: Using file tuples (filename, file_content, mime_type)
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        (
            "financial_skill/SKILL.md",
            open("financial_skill/SKILL.md", "rb"),
            "text/markdown",
        ),
        (
            "financial_skill/analyze.py",
            open("financial_skill/analyze.py", "rb"),
            "text/x-python",
        ),
    ],
    betas=["skills-2025-10-02"],
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")

Требования:

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

Для полных схем запросов/ответов см. справку по API Create Skill.

Список Skills

# List all Skills
skills = client.beta.skills.list(betas=["skills-2025-10-02"])

for skill in skills.data:
    print(f"{skill.id}: {skill.display_title} (source: {skill.source})")

# List only custom Skills
custom_skills = client.beta.skills.list(source="custom", betas=["skills-2025-10-02"])

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

Получение Skill

Получите информацию о конкретном Skill:

skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", betas=["skills-2025-10-02"]
)

print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")
print(f"Created: {skill.created_at}")

Удаление Skill

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

# Step 1: Delete all versions
versions = client.beta.skills.versions.list(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", betas=["skills-2025-10-02"]
)

for version in versions.data:
    client.beta.skills.versions.delete(
        skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
        version=version.version,
        betas=["skills-2025-10-02"],
    )

# Step 2: Delete the Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv", betas=["skills-2025-10-02"]
)

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

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

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

Skills, управляемые Anthropic:

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

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

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

# Создать новую версию
from anthropic.lib import files_from_dir

new_version = client.beta.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("/path/to/updated_skill"),
    betas=["skills-2025-10-02"],
)

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

# Использовать последнюю версию
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Полные сведения см. в справочнике API Create Skill Version.

Как загружаются Skills

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

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

Варианты использования

Организационные Skills

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

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

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

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

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

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

Личные Skills

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

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

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

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

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

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

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

Объедините Excel и пользовательские Skills анализа 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"),
    betas=["skills-2025-10-02"],
)

# Использовать с Excel для создания финансовой модели
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)

Ограничения и ограничения

Ограничения запроса

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

Ограничения окружения

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

Нет доступа в сеть - Не может выполнять внешние вызовы API
Нет установки пакетов во время выполнения - Доступны только предустановленные пакеты
Изолированная среда - Каждый запрос получает свежий контейнер

Полный список доступных пакетов см. в документации инструмента выполнения кода.

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

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

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

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

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

Избегайте:

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

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

Для производства:

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

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

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

Рассмотрения кэширования подсказок

# Первый запрос создает кэш
response1 = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)

# Добавление/удаление Skills нарушает кэш
response2 = client.beta.messages.create(
    model="claude-opus-4-6",
    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",
            },  # Промах кэша
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

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

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

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

try:
    response = client.beta.messages.create(
        model="claude-opus-4-6",
        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}")
        # Обработайте ошибки, специфичные для Skill
    else:
        raise

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

Справочник API

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

Руководство по авторству

Лучшие практики для написания эффективных Skills

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

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

Was this page helpful?