Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Agent Skills расширяют возможности Claude с помощью организованных папок с инструкциями, скриптами и ресурсами. Это руководство показывает, как использовать как готовые, так и пользовательские Skills с Claude API.
Полный справочник API, включая схемы запросов/ответов и все параметры, см.:
О том, как «zero data retention» (нулевое хранение данных), или ZDR, применяется к этой функции, см. API и хранение данных.
Создайте свой первый Skill
Лучшие практики создания Skills
Для подробного ознакомления с архитектурой и реальными применениями Agent Skills прочитайте статью в инженерном блоге: Equipping agents for the real world with Agent Skills.
Skills интегрируются с Messages API через инструмент выполнения кода. Независимо от того, используете ли вы готовые Skills, управляемые Anthropic, или пользовательские Skills, которые вы загрузили, форма интеграции идентична: оба варианта требуют выполнения кода и используют одну и ту же структуру container.
Skills интегрируются в Messages API одинаково независимо от источника. Вы указываете Skills в параметре container с skill_id, type и необязательным version, и они выполняются в среде выполнения кода.
Вы можете использовать Skills из двух источников:
| Аспект | Skills от Anthropic | Пользовательские Skills |
|---|---|---|
| Значение type | anthropic | custom |
| Идентификаторы Skill | Короткие имена: pptx, xlsx, docx, pdf | Сгенерированные: skill_01AbCdEfGhIjKlMnOpQrStUv |
| Формат версии | На основе даты: 20251013 или latest | Временная метка epoch: 1759178010641129 или latest |
| Управление | Готовые и поддерживаемые Anthropic | Загрузка и управление через Skills API |
| Доступность | Доступны всем пользователям | Приватные для вашего рабочего пространства |
Оба источника skills возвращаются конечной точкой List Skills (используйте параметр source для фильтрации). Форма интеграции и среда выполнения идентичны. Единственное различие заключается в том, откуда берутся Skills и как они управляются.
Для использования Skills вам потребуется:
code-execution-2025-08-25 - Включает выполнение кода (требуется для Skills)skills-2025-10-02 - Включает Skills APIfiles-api-2025-04-14 - Для загрузки/скачивания файлов в/из контейнераSkills указываются с помощью параметра container в Messages API. Вы можете включить до 8 Skills в каждый запрос.
Структура идентична как для Skills от Anthropic, так и для пользовательских Skills. Укажите обязательные type и skill_id, и при необходимости включите version, чтобы закрепить конкретную версию:
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5",
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 для скачивания этих файлов.
Как это работает:
file_id для каждого созданного файла.Пример: создание и скачивание файла Excel
client = anthropic.Anthropic()
# Шаг 1: Используем Skill для создания файла
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create an Excel file with a simple budget spreadsheet",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Шаг 2: Извлекаем идентификаторы файлов из ответа
def extract_file_ids(response):
file_ids = []
for item in response.content:
if item.type == "bash_code_execution_tool_result":
content_item = item.content
if content_item.type == "bash_code_execution_result":
# каждый элемент содержимого — это блок bash_code_execution_output, содержащий file_id
for file in content_item.content:
file_ids.append(file.file_id)
return file_ids
# Шаг 3: Скачиваем файл через Files API
for file_id in extract_file_ids(response):
file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
file_content = client.beta.files.download(file_id=file_id)
# Шаг 4: Сохраняем на диск
file_content.write_to_file(file_metadata.filename)
print(f"Downloaded: {file_metadata.filename}")Дополнительные операции Files API:
client = anthropic.Anthropic()
file_id = "file_011CNha8iCJcU1wXNR6q4V8w"
# Получение метаданных файла
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")
# Список всех файлов
for file in client.beta.files.list():
print(f"{file.filename} - {file.created_at}")
# Удаление файла
client.beta.files.delete(file_id=file_id)Полную информацию о Files API см. в документации Files API.
Повторно используйте один и тот же контейнер в нескольких сообщениях, указав идентификатор контейнера:
client = anthropic.Anthropic()
# Первый запрос создаёт контейнер
response1 = client.beta.messages.create(
model="claude-opus-5",
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 a sample sales dataset and analyze it"}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Продолжаем разговор с тем же контейнером
messages = [
{"role": "user", "content": "Create a sample sales dataset and analyze it"},
{
# Переносим текст ассистента дальше; container.id несёт состояние выполнения
"role": "assistant",
"content": "\n".join(
block.text for block in response1.content if block.type == "text"
),
},
{"role": "user", "content": "What was the total revenue?"},
]
response2 = client.beta.messages.create(
model="claude-opus-5",
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:
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10
response = client.beta.messages.create(
model="claude-opus-5",
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 _ 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-5",
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 в одном запросе для обработки сложных рабочих процессов:
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
{"type": "anthropic", "skill_id": "pptx", "version": "latest"},
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
},
]
},
messages=[
{"role": "user", "content": "Analyze sales data and create a presentation"}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)Пакет Skill — это каталог, содержащий файл SKILL.md на верхнем уровне с YAML-метаданными name и description, а также любые вспомогательные скрипты или ресурсы. См. Начало работы с Agent Skills в API, чтобы создать его, и список Требования после примеров для полного перечня ограничений.
Загрузите свой пользовательский Skill, чтобы сделать его доступным в вашем рабочем пространстве. Вы можете загрузить zip-архив или отдельные файловые объекты; Python SDK дополнительно предоставляет вспомогательную функцию files_from_dir, которая принимает путь к каталогу.
Файлы идентифицируются по имени файла, которое вы прикрепляете. При пофайловой загрузке пути должны содержать общий каталог верхнего уровня (суффикс ;filename= в примере cURL и аргументы имени файла в примерах SDK), а zip-архив должен содержать каталог skill как единственную запись верхнего уровня.
ant beta:skills create \
--file example_skill.zip \
--beta skills-2025-10-02
# Загрузка отдельных файлов требует имён файлов с указанием пути, которые CLI
# пока не может задать. Вместо этого загрузите zip-архив.Требования:
name в метаданных SKILL.md (без учёта регистра и подчёркиваний: Financial_Skill соответствует financial-skill)display_title необязателен: если он опущен, он выводится из name в SKILL.md; явное значение должно быть уникальным среди пользовательских skills в вашем рабочем пространствеname: максимум 64 символа, только строчные буквы/цифры/дефисы, без XML-тегов, без зарезервированных слов ("anthropic", "claude")description: максимум 1024 символа, непустое, без XML-теговПолные схемы запросов/ответов см. в справочнике API Create Skill.
Получите все Skills, доступные вашему рабочему пространству, включая как готовые Skills от Anthropic, так и ваши пользовательские Skills. Используйте параметр source для фильтрации по типу skill:
# Перечислить все навыки (Skills)
ant beta:skills list
# Перечислить только пользовательские навыки
ant beta:skills list --source customПараметры пагинации и фильтрации см. в справочнике API List Skills.
Получите сведения о конкретном Skill:
ant beta:skills retrieve \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUvЧтобы удалить Skill, вы должны сначала удалить все его версии:
# Шаг 1: Получите список версий, затем удалите каждую из них
ant beta:skills:versions list \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--transform version --raw-output
# Повторите для каждого идентификатора версии из полученного списка
ant beta:skills:versions delete \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--version 1759178010641129 >/dev/null
# Шаг 2: Удалите Skill
ant beta:skills delete \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/nullПопытка удалить Skill с существующими версиями возвращает ошибку 400.
Skills поддерживают управление версиями для безопасного управления обновлениями:
Skills от Anthropic:
20251013Пользовательские Skills:
1759178010641129"latest", чтобы всегда получать самую последнюю версию# Создать новую версию
VERSION_NUMBER=$(ant beta:skills:versions create \
--skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
--file updated_skill.zip \
--transform version --raw-output)
# Использовать конкретную версию
ant beta:messages create \
--beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
max_tokens: 4096
container:
skills:
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: $VERSION_NUMBER
messages:
- role: user
content: Use updated Skill
tools:
- type: code_execution_20250825
name: code_execution
YAML
# Использовать последнюю версию
ant beta:messages create \
--beta code-execution-2025-08-25,skills-2025-10-02 <<'YAML'
model: claude-opus-5
max_tokens: 4096
container:
skills:
- type: custom
skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
version: latest
messages:
- role: user
content: Use latest Skill version
tools:
- type: code_execution_20250825
name: code_execution
YAMLПолную информацию см. в справочнике API Create Skill Version.
Когда вы указываете Skills в контейнере:
/skills/{directory}/.Архитектура прогрессивного раскрытия обеспечивает эффективное использование контекста: Claude загружает полные инструкции Skill только при необходимости.
Бренд и коммуникации
Управление проектами
Бизнес-операции
Создание контента
Анализ данных
Разработка и автоматизация
Объедините Skills для Excel и пользовательского DCF-анализа:
from anthropic.lib import files_from_dir
client = anthropic.Anthropic()
# Создание пользовательского навыка (Skill) для DCF-анализа
dcf_skill = client.beta.skills.create(
files=files_from_dir("/path/to/dcf_skill"),
)
# Использование с Excel для создания финансовой модели
response = client.beta.messages.create(
model="claude-opus-5",
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",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)name: максимум 64 символа, только строчные буквы/цифры/дефисы, без XML-тегов, без зарезервированных слов ("anthropic", "claude")description: максимум 1024 символа, непустое, без XML-теговSkills выполняются в контейнере выполнения кода со следующими ограничениями:
Доступные пакеты см. в разделе Инструмент выполнения кода.
Объединяйте Skills, когда задачи включают несколько типов документов или предметных областей:
Хорошие варианты использования:
Избегайте:
Для продакшена:
# Закрепите конкретные версии для стабильности
container = {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "1759178010641129", # Specific version
}
]
}Для разработки:
# Используйте latest для активной разработки
container = {
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest", # Always get newest
}
]
}При использовании кэширования подсказок (prompt caching) обратите внимание, что изменение списка Skills в вашем контейнере нарушает кэш:
client = anthropic.Anthropic()
# Первый запрос создаёт кэш
response1 = client.beta.messages.create(
model="claude-opus-5",
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 sales data"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Добавление/удаление Skills нарушает кэш
response2 = client.beta.messages.create(
model="claude-opus-5",
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",
}, # Cache miss
]
},
messages=[{"role": "user", "content": "Create a presentation"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)Для наилучшей производительности кэширования сохраняйте список Skills одинаковым между запросами.
Корректно обрабатывайте ошибки, связанные со Skills:
client = anthropic.Anthropic()
try:
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [
{
"type": "custom",
"skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
"version": "latest",
}
]
},
messages=[{"role": "user", "content": "Process data"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
except anthropic.BadRequestError as e:
if "skill" in str(e):
print(f"Skill error: {e}")
# Обработка ошибок, специфичных для навыка
else:
raiseAgent Skills не подпадают под соглашения ZDR. Определения Skill и данные выполнения хранятся в соответствии со стандартной политикой хранения данных Anthropic.
Информацию о применимости ZDR ко всем функциям см. в разделе API и хранение данных.
Полный справочник API со всеми конечными точками
Узнайте, как писать эффективные Skills, которые Claude сможет обнаруживать и успешно использовать
Запускайте код Python и bash в изолированном контейнере для анализа данных, генерации файлов и итеративной работы над решениями
Was this page helpful?