Навыки

Системный промпт помощника аналитика растёт: как оформлять ТЗ, какие разделы обязательны, какой шаблон у нас в агентстве для таблицы требований. Скоро он занимает тысячи токенов, и большая их часть не нужна для конкретного вопроса. Навыки (Agent Skills) решают эту проблему: инструкции лежат отдельно, а модель читает их, только когда задача этого требует. В этом уроке разберём, как навыки устроены, как использовать их через API и чем они отличаются от инструментов.

Что такое навык

Навык — это папка с файлом SKILL.md и, при необходимости, дополнительными файлами: шаблонами, скриптами, справочниками. В начале SKILL.md — короткое описание: что навык делает и когда его применять. Дальше — подробные инструкции.

Работает это через постепенное раскрытие. В контексте модели постоянно живёт только короткое описание каждого навыка. Когда пользователь просит «оформи это ТЗ по нашему шаблону», модель по описанию понимает, что навык подходит, и читает полный файл. Если просят что-то другое, полный текст не загружается и токены не тратятся.

Если вы проходили курс по навыкам в Claude Code, формат вам знаком: там та же папка и тот же SKILL.md. Разница в том, где навык живёт и кто его загружает. В Claude Code — папка в репозитории, в API — контейнер выполнения кода, куда навык подключается параметром запроса.

Навыки в Messages API

В API навыки работают внутри контейнера выполнения кода: модель читает SKILL.md и запускает скрипты навыка там же, где выполняет код. Поэтому навыки подключаются вместе с инструментом code_execution, и на момент написания это делается через бета-эндпоинт с заголовком.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.beta.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000,
  betas: ["code-execution-2025-08-25"],
  container: {
    skills: [{ type: "anthropic", skill_id: "xlsx", version: "latest" }],
  },
  tools: [{ type: "code_execution_20260521", name: "code_execution" }],
  messages: [
    {
      role: "user",
      content:
        "Собери таблицу со статусом задач спринта для клиентского портала: " +
        "колонки «Задача», «Ответственный», «Статус», «Срок». Данные: ...",
    },
  ],
});

Три части, без любой из которых запрос не сработает: бета-заголовок code-execution-2025-08-25, параметр container.skills со списком навыков и инструмент code_execution актуальной версии. Обратите внимание: версия типа здесь code_execution_20260521, она отличается от той, что мы использовали в прошлом уроке без навыков. Берите версию из документации, не по памяти.

Anthropic поставляет готовые навыки для офисных форматов: pptx (презентации), xlsx (таблицы), docx (документы), pdf. Именно они делают из «модель написала текст» полноценный файл, который можно отправить заказчику. Список доступных навыков отдаёт эндпоинт GET /v1/skills.

Что приходит в ответ

Навык вместе с выполнением кода создаёт файл в контейнере, а в ответе появляется ссылка на него — file_id в блоках результатов выполнения кода. Файл скачивается через Files API.

for (const block of response.content) {
  if (block.type !== "bash_code_execution_tool_result") continue;
  const result = block.content;
  if (result.type !== "bash_code_execution_result" || !result.content) continue;
  for (const item of result.content) {
    if (item.type !== "bash_code_execution_output") continue;
    const download = await client.files.download(item.file_id);
    const bytes = Buffer.from(await download.arrayBuffer());
    // сохранить bytes на диск под безопасным именем
  }
}

Как и в прошлом уроке, имя файла — вывод модели: берите базовое имя, пишите в отдельную папку.

Свои навыки

Готовые навыки покрывают форматы файлов. Для правил агентства нужны свои: шаблон ТЗ, стандарт оформления отчёта по спринту, чек-лист ревью. Такие навыки загружаются через Skills API (client.skills) и подключаются в container.skills по идентификатору. Формат SKILL.md тот же, что в Claude Code, так что навык, написанный для разработчиков, можно переиспользовать в боте клиентского портала. Точные параметры загрузки и версионирования смотрите в документации по навыкам: они уточняются, и переписывать их здесь по памяти было бы неправильно.

Хороший навык пишется как инструкция для нового сотрудника: сначала одна фраза «когда это применять», потом конкретные шаги, потом примеры. Описание в начале — самое важное: по нему модель решает, загружать ли остальное. Расплывчатое «помогает с документами» не сработает, точное «оформляет техническое задание по шаблону агентства: разделы, нумерация требований, таблица приоритетов» — сработает.

Навык, инструмент или промпт

Три механизма легко перепутать, поэтому разведём их.

Системный промпт — то, что нужно всегда: роль, тон, базовые ограничения. Короткий и стабильный (стабильность важна для кэширования, об этом в уроке про контекст).

Инструмент — действие во внешнем мире: получить diff, записать в трекер, отправить письмо. Инструмент что-то делает; навык объясняет, как делать.

Навык — знание для типовой задачи, которое нужно не всегда: шаблон, регламент, последовательность шагов. Загружается по требованию, может включать скрипты, которые модель запустит в контейнере.

Помощник аналитика в итоге выглядит так: короткий системный промпт («ты помощник аналитика продуктовой студии, отвечай по-русски, ссылайся на номера требований»), навык «оформление ТЗ» и навык docx для выгрузки результата, плюс инструмент для чтения задач из трекера. Каждая часть на своём месте, и контекст не раздут.

Ограничения

Навыки в API работают только вместе с выполнением кода, а значит, только на тех платформах, где оно доступно: проверьте документацию, если вы работаете не с API Anthropic напрямую, а через облачного провайдера. Навыки не заменяют инструменты и не дают модели доступ к вашим системам. И как всё, что загружается в контекст, содержимое навыка — это инструкции, которым модель будет следовать: храните навыки в репозитории с ревью, как код.