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

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

Для полного справочника 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
Бета-заголовки:
- 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.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()

# Шаг 1: Используйте Skill для создания файла
response = client.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"}]
)

# Шаг 2: Извлеките file IDs из ответа
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

# Шаг 3: Загрузите файл с помощью 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"]
    )

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

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

# Получите метаданные файла
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")

# Список всех файлов
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Удалите файл
client.beta.files.delete(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)

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

Многооборотные разговоры

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

# Первый запрос создает контейнер
response1 = client.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"}]
)

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

response2 = client.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,  # Переиспользуйте контейнер
        "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.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"}]
)

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

    messages.append({"role": "assistant", "content": response.content})
    response = client.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.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()

# Вариант 1: Использование помощника files_from_dir (только Python, рекомендуется)
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"]
)

# Вариант 2: Использование zip-файла
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"]
)

# Вариант 3: Использование кортежей файлов (имя файла, содержимое файла, тип MIME)
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 символа), description (максимум 1024 символа)

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

Список Skills

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

# Список всех 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})")

# Список только пользовательских 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, вы должны сначала удалить все его версии:

# Шаг 1: Удалите все версии
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"]
    )

# Шаг 2: Удалите Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

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

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

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

Версии используют формат даты: 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.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"}]
)

# Используйте последнюю версию
response = client.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 и пользовательские DCF анализ Skills:

# Создайте пользовательский DCF анализ 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"]
)

# Используйте с Excel для создания финансовой модели
response = client.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 символа, description 1024 символа

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

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.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"}]
)

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

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

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

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

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

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

Справочник API

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

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

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

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

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

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

Справочник API

SDK

Примеры

API третьих сторон

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

Поддержка и конфигурация

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

Начните работу с 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

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

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

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

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