Пишем свой навык

В прошлом уроке разобрали, что такое навык и как Codex его находит. Теперь напишем свой — не через $skill-creator, а руками, чтобы понимать каждую строчку. Пример — навык, который готовит описание merge request по текущей ветке. Задача знакомая, результат легко проверить, и в ней есть всё: инструкции, скрипт и шаблон.

Шаг 1. Одна задача и понятный результат

Прежде чем открывать редактор, ответьте на три вопроса:

• С чего начинается задача? Ветка task-<номер> с коммитами относительно main.
• Как выглядит готовый результат? Текст MR из четырёх разделов: что сделано, зачем, как проверить, риски.
• Чего навык не делает? Не создаёт MR, не пушит, не придумывает номер задачи и ссылки.

Если на последний вопрос ответить трудно, навык, скорее всего, слишком широкий. Документация советует держать в одном навыке одну работу и делить навыки, когда у них разные триггеры, входы или критерии успеха.

Шаг 2. Имя и описание

Структура каталога:

.agents/skills/mr-description/
├── SKILL.md
├── scripts/
│   └── collect.sh
└── assets/
    └── template.md

Требования стандарта Agent Skills к name: до 64 символов, только строчные латинские буквы, цифры и дефис, без дефиса в начале и в конце и без двух дефисов подряд. Имя должно совпадать с названием папки. description — до 1024 символов.

Описание пишется для модели, а не для каталога. В нём должно быть, что навык делает, когда его применять и когда нет. Ключевые слова — в начало: если навыков много, Codex укорачивает описания, и хвост может не дойти до модели.

Шаг 3. Тело SKILL.md

---
name: mr-description
description: Описание merge request (MR) по текущей git-ветке — что сделано, зачем, как проверить, риски. Использовать, когда просят описание MR, текст для merge request или сводку изменений ветки. Не использовать для ревью кода и для создания самого MR.
---

# Описание merge request

## Вход
- Текущая ветка. Базовая ветка — `main`, если пользователь не назвал другую.
- Номер задачи берётся из имени ветки вида `task-<номер>`. Если имя другое,
  спроси номер, не придумывай его.

## Шаги
1. Из корня репозитория запусти `scripts/collect.sh <базовая-ветка>` (путь — относительно папки навыка) и прочитай вывод.
2. Если изменённых файлов больше 30, сгруппируй их по каталогам, а не перечисляй.
3. Прочитай диффы ключевых файлов, чтобы понять смысл изменений, а не только их список.
4. Заполни шаблон `assets/template.md`.

## Выход
- Только текст описания в Markdown, без вступления и без комментариев о процессе.
- В разделе «Как проверить» — конкретные шаги: команды тестов, страницы стенда.

## Границы
- Не создавай MR, не пушь и не меняй файлы репозитория.
- Не указывай тесты, которые ты не видел в диффе или не запускал.
- Если в диффе есть миграции или изменения конфигурации, обязательно упомяни их в «Рисках».
- Прямые указания пользователя важнее этих инструкций.

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

Шаг 4. Скрипт и шаблон

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

#!/usr/bin/env bash
set -euo pipefail

base="${1:-main}"
if git rev-parse --verify --quiet "origin/$base" >/dev/null; then
  base="origin/$base"
fi

branch="$(git rev-parse --abbrev-ref HEAD)"
echo "branch: $branch"
case "$branch" in
  task-*) echo "task: ${branch#task-}" ;;
  *) echo "task: unknown" ;;
esac

echo "--- commits"
git log --oneline "$base..HEAD"
echo "--- files"
git diff --stat "$base...HEAD"

Не забудьте chmod +x scripts/collect.sh. Скрипт ничего не скачивает и не пишет — он одинаково работает и в песочнице без сети.

## Что сделано

## Зачем

## Как проверить

## Риски и что не вошло

Правило из документации: не добавляйте скрипт, если инструкций и существующих инструментов достаточно. Скрипт — это код, который придётся поддерживать.

Шаг 5. Метаданные и зависимости

Файл agents/openai.yaml необязателен. Он задаёт отображение в интерфейсе десктопного приложения, политику вызова и зависимости. Например, если навык опирается на MCP-сервер GitLab из урока «MCP на практике», это можно объявить:

interface:
  display_name: "Описание MR"
  short_description: "Текст merge request по текущей ветке"
policy:
  allow_implicit_invocation: true
dependencies:
  tools:
    - type: "mcp"
      value: "gitlab"
      description: "GitLab MCP для чтения задачи и MR"
      transport: "streamable_http"
      url: "https://git.example.com/api/v4/mcp"

Зависимость делает инструмент доступным, но не заменяет инструкций: в теле навыка всё равно нужно сказать, какие инструменты вызывать, в каком порядке и что делать, если данных нет.

Шаг 6. Проверка срабатывания

Навык проверяют на наборе запросов, а не одним удачным примером. Руководство OpenAI предлагает пять групп:

1. Прямые запросы: «сделай описание MR».
2. Косвенные с той же целью: «что написать в merge request по этой ветке?»
3. Неполные, на которые навык должен задать вопрос: ветка без номера задачи.
4. Запросы, где навык срабатывать не должен: «сделай ревью этой ветки».
5. Пограничные, где навык не должен ничего придумывать: ветка без коммитов относительно main.

Разбирайте два вида ошибок отдельно. Навык срабатывает не вовремя или не срабатывает — правьте description. Срабатывает правильно, но результат плавает — правьте тело.

Шаг 7. Сопровождение

• Держите SKILL.md коротким. Стандарт Agent Skills рекомендует до 500 строк; подробности выносите в references/ и ссылайтесь на них из тела на один уровень вглубь.
• Навык — это код. Он лежит в git, меняется через MR и проходит ревью. Особенно скрипты: агент выполняет их от вашего имени.
• Проверяйте формат. В репозитории стандарта есть библиотека skills-ref с командой skills-ref validate ./mr-description — она проверяет шапку и правила именования.
• Собирайте ошибки. Если агент дважды сделал одно и то же не так, это строчка в разделе «Границы».

Когда навыков станет несколько и ими захотят пользоваться в других репозиториях, их пора упаковать в плагин.