раздел 02

Skills (SKILL.md)

Навык (skill) - это готовая способность агента под конкретную типовую задачу. Внутри - файл SKILL.md с инструкцией: как делать вот такую работу правильно, шаг за шагом, с учётом всех граблей. Рядом могут лежать вспомогательные файлы: шаблоны, скрипты, примеры.

Отличие от инструкции проекта в том, что навык - переносимый и подключается по требованию. AGENTS.md (в Claude Code - CLAUDE.md) агент читает всегда, а навык - только когда задача под него подходит.

Как агент понимает, что навык пора применить

Вот тут главное. У каждого навыка есть описание - короткая фраза о том, что он делает и, самое важное, когда его применять. Агент держит перед глазами список описаний всех навыков. Когда приходит задача, он сверяет её с этими описаниями и сам подключает подходящий навык - подгружает его инструкцию и действует по ней.

Значит, вся сила навыка держится на точности описания-триггера. Размытое описание - и агент либо не поймёт, что навык нужен, либо подключит его невпопад.

Как устроен файл

---
name: pdf-invoice
description: >
  Формирование PDF-счёта из данных заказа. Использовать, когда просят
  выставить счёт, сделать инвойс, сгенерировать счёт на оплату по заказу.
---

# Как сформировать счёт

1. Взять данные заказа: покупатель, позиции, суммы.
2. Заполнить шаблон template.docx через docxtpl.
3. Сконвертировать в PDF через LibreOffice headless.
4. Проверить: суммы сходятся, реквизиты на месте.

Шаблон и пример - в файлах рядом.

Обрати внимание на description: там прямо перечислены формулировки задачи, по которым навык должен сработать. Это не украшение, а рабочий триггер.

Хорошо и плохо

Хорошо
Узкий навык под одну задачу: выставить счёт. Описание чётко говорит, когда применять, и перечисляет формулировки-триггеры. Агент сам подключает его в нужный момент.
Плохо
Навык-на-всё: работа с документами. Размытое описание помогать с файлами. Агент не понимает, когда он нужен, и либо игнорирует, либо тянет невпопад.

Когда заводить навык

Заводи навык, когда одну и ту же непростую работу приходится делать регулярно и у неё есть свои тонкости, которые агент иначе забывает. Разовую задачу оформлять навыком не нужно - проще объяснить в чате.

Куда дальше