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

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

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

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

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

Начните работу с 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 заголовки:
- 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-sonnet-4-5-20250929",
    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-sonnet-4-5-20250929",
    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-sonnet-4-5-20250929",
    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-sonnet-4-5-20250929",
    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-sonnet-4-5-20250929",
    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-sonnet-4-5-20250929",
        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-sonnet-4-5-20250929",
    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 поддерживают версионирование для безопасного управления обновлениями: Управляемые Anthropic Skills:

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

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

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

# Create a new version
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"]
)

# Use specific version
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}]
)

# Use latest version
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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:

# Create custom DCF analysis Skill
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"]
)

# Use with Excel to create financial model
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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: 8МБ (все файлы вместе)
Требования YAML frontmatter:
- name: Максимум 64 символа, только строчные буквы/цифры/дефисы, без XML тегов, без зарезервированных слов
- description: Максимум 1024 символа, не пусто, без XML тегов

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

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

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

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

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

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

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

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

Избегайте:

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

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

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

# Pin to specific versions for stability
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "1759178010641129"  # Specific version
    }]
}

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

# Use latest for active development
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # Always get newest
    }]
}

Рассмотрения кэширования приглашений

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

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

# Adding/removing Skills breaks cache
response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    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"}]
)

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

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

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

try:
    response = client.beta.messages.create(
        model="claude-sonnet-4-5-20250929",
        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}")
        # Handle skill-specific errors
    else:
        raise

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

Справка по API

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

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

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

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

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

Первые шаги

Модели и цены

Создавайте с Claude

Возможности

Инструменты

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

SDK для агентов

MCP в API

Claude на сторонних платформах

Инженерия подсказок

Тестирование и оценка

Усилить защиту

Администрирование и мониторинг

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

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

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

​Обзор

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

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

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

​Параметр Container

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

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

​Долгоживущие операции

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

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

​Создание Skill

​Список Skills

​Получение Skill

​Удаление Skill

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

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

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

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

​Персональные Skills

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

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

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

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

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

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

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

​Рассмотрения кэширования приглашений

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

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

Справка по API

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

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

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

Обзор

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

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

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

Параметр Container

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

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

Долгоживущие операции

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

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

Создание Skill

Список Skills

Получение Skill

Удаление Skill

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

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

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

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

Персональные Skills

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

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

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

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

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

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

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

Рассмотрения кэширования приглашений

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

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