Модуль 2 · Расширения · урок 11 из 16
Пишем свой навык
В прошлом уроке вы узнали, что такое навык и как 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 предлагает пять групп:
- Прямые запросы: «сделай описание MR».
- Косвенные с той же целью: «что написать в merge request по этой ветке?»
- Неполные, на которые навык должен задать вопрос: ветка без номера задачи.
- Запросы, где навык срабатывать не должен: «сделай ревью этой ветки».
- Пограничные, где навык не должен ничего придумывать: ветка без коммитов относительно
main.
Ошибки бывают двух видов, и чинят их по-разному. Если навык срабатывает не вовремя или не срабатывает вовсе, правьте description. Если срабатывает правильно, но результат плавает, правьте тело.
Шаг 7. Сопровождение
- Держите
SKILL.mdкоротким. Стандарт Agent Skills рекомендует до 500 строк, подробности выносите вreferences/и ссылайтесь на них из тела не глубже одного уровня. - Обращайтесь с навыком как с кодом. Он лежит в git, меняется через MR и проходит ревью. Особенно это касается скриптов, ведь агент выполняет их от вашего имени.
- Проверяйте формат. В репозитории стандарта есть библиотека
skills-refс командойskills-ref validate ./mr-description, она проверяет шапку и правила именования. - Записывайте ошибки. Если агент дважды сделал одно и то же не так, добавьте строчку в раздел «Границы».
Когда навыков станет несколько и ими захотят пользоваться в других репозиториях, их пора упаковать в плагин.
Попробуйте сами
10–15 мин на рабочем месте- Создайте
mr-descriptionиз этого урока в своём репозитории, поправьте шаблон под принятый у вас формат MR и вызовите$mr-descriptionна текущей ветке. - Проверьте навык на пяти группах запросов из шага 6 и запишите, где он ошибся. В зависимости от типа ошибки исправьте
descriptionили тело. - Возьмите правило из AGENTS.md, которое нужно только в одном типе задач, и перенесите его в отдельный навык. Убедитесь, что без упоминания он включается именно в этих задачах.
Коротко
- Навык начинается с одной задачи, понятного результата и списка того, чего он не делает.
- В
nameтолько строчные буквы, цифры и дефисы, и имя совпадает с папкой. Вdescriptionнаписано, что навык делает, когда его применять и когда нет, главные слова стоят в начале. - Тело делится на вход, шаги, выход и границы, явные указания пользователя важнее навыка.
- Скрипт добавляют только ради точности и повторяемости, шаблоны кладут в
assets/. - Срабатывание проверяют набором запросов: ошибки выбора лечат описанием, ошибки результата правкой тела.