Agent Skills

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

Узнайте, как использовать Agent Skills для расширения возможностей Claude через 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`

Оба источника 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 для привязки к определенной версии:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Создание Skill

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

Требования:

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

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

Список Skills

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

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

Получение Skill

Получите детали о конкретном Skill:

Удаление Skill

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Максимум 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 в вашем контейнере разрушит кэш:

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

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

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

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

Справка по API

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

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

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

# 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"]
)

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

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

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

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

# 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"]
)

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

# 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"]
)

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

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

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

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