Amiga
Оглавление курса · урок 11 из 16

Модуль 2 · Расширения · урок 11 из 16

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

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

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

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

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

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

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

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

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

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

Описание читает модель, а не человек в каталоге. Из него должно быть понятно, что навык делает, когда его применять и когда нет. Самые важные слова ставьте в начало: если навыков много, Codex укорачивает описания, и хвост может не дойти до модели.

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

markdown · .agents/skills/mr-description/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. Скрипт и шаблон

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

bash · .agents/skills/mr-description/scripts/collect.sh
#!/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. Скрипт ничего не скачивает и не пишет, поэтому одинаково работает и в песочнице без сети.

markdown · .agents/skills/mr-description/assets/template.md
## Что сделано

## Зачем

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

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

Документация предупреждает: если инструкций и существующих инструментов достаточно, скрипт не добавляйте. Это код, и его придётся поддерживать.

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

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

yaml · .agents/skills/mr-description/agents/openai.yaml
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, она проверяет шапку и правила именования.
  • Записывайте ошибки. Если агент дважды сделал одно и то же не так, добавьте строчку в раздел «Границы».

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

Попробуйте сами

10–15 мин на рабочем месте
  1. Создайте mr-description из этого урока в своём репозитории, поправьте шаблон под принятый у вас формат MR и вызовите $mr-description на текущей ветке.
  2. Проверьте навык на пяти группах запросов из шага 6 и запишите, где он ошибся. В зависимости от типа ошибки исправьте description или тело.
  3. Возьмите правило из AGENTS.md, которое нужно только в одном типе задач, и перенесите его в отдельный навык. Убедитесь, что без упоминания он включается именно в этих задачах.

Коротко

  • Навык начинается с одной задачи, понятного результата и списка того, чего он не делает.
  • В name только строчные буквы, цифры и дефисы, и имя совпадает с папкой. В description написано, что навык делает, когда его применять и когда нет, главные слова стоят в начале.
  • Тело делится на вход, шаги, выход и границы, явные указания пользователя важнее навыка.
  • Скрипт добавляют только ради точности и повторяемости, шаблоны кладут в assets/.
  • Срабатывание проверяют набором запросов: ошибки выбора лечат описанием, ошибки результата правкой тела.
Отметка хранится только в вашем браузере
Хотите связаться с владельцем
компании напрямую?
Дмитрий Тарасов
Дмитрий Тарасов
СЕО

НАПИСАТЬ

Написать в MAX