Skills в Codex: как переиспользовать рабочий процесс

Skill — это папка с инструкциями и ресурсами для узнаваемого повторяемого сценария. В центре находится SKILL.md с именем, описанием и процедурой.

Краткий ответ

Skill — это папка с инструкциями и ресурсами для узнаваемого повторяемого сценария. В центре находится SKILL.md с именем, описанием и процедурой. Skill полезен, когда команда снова и снова пишет один промпт или исправляет одинаковые ошибки агента.

Чем skill отличается от AGENTS.md

AGENTS.md задаёт постоянные соглашения области репозитория: команды, архитектурные правила и определение готовности. Skill описывает отдельный процесс, который активируется только для подходящей задачи.

Примеры skills:

починка упавшего CI job;
аудит миграции по чек-листу;
подготовка release notes;
анализ production-логов;
проверка доступности интерфейса;
обновление API-контракта и fixtures.

Не превращайте AGENTS.md в каталог длинных процедур. И не создавайте skill для правила «всегда запускать lint»: это устойчивое соглашение проекта.

Минимальная структура

---
name: migration-review
description: Проверяет план и код миграции БД на совместимость,
  повторный запуск и безопасный откат. Использовать при изменении схемы.
---

1. Прочитай схему, миграцию и путь чтения/записи.
2. Проверь expand-migrate-contract и старые версии приложения.
3. Запусти указанные dry-run и integration checks.
4. Верни риски по серьёзности с файлами и доказательствами.

Остановись, если нет резервной копии или неизвестна production-версия.

Описание определяет, когда skill следует рассмотреть. Детальная процедура находится в теле и загружается после активации, что экономит контекст.

Ресурсы, assets и scripts

Оставляйте SKILL.md коротким, а объёмные материалы размещайте рядом:

references/ — политика, схема, примеры и справочная информация;
assets/ — шаблоны выходных документов;
scripts/ — детерминированная обработка, которую нельзя надёжно заменить инструкцией.

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

Активация и границы

Skill может активироваться явно или по совпадению цели с description. Хорошее описание включает и область применения, и условия. Слишком общее «помогает с кодом» будет срабатывать неуместно.

В теле зафиксируйте:

ожидаемый вход;
порядок действий;
формат результата;
факты, которые нельзя додумывать;
условия остановки;
обязательные зависимости и проверки.

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

Как тестировать skill

Проверьте пять классов запросов:

1. прямой запрос, который обязан активировать skill; 2. косвенная формулировка той же цели; 3. неполный ввод, требующий вопроса; 4. соседняя задача, где skill не должен запускаться; 5. опасный edge case, где процедура обязана остановиться.

Отдельно оценивайте активацию и качество результата. Если выбран неверный skill — исправляйте name/description. Если skill выбран верно, но шаги нарушаются — уточняйте тело.

Практика: извлечение повторяемого процесса

Найдите три похожих завершённых задачи. Выпишите общий вход, одинаковые шаги, команды проверки и формат отчёта. Удалите детали одного репозитория, если skill должен быть пользовательским, либо сохраните их в repo-scoped skill.

Создайте первую instruction-only версию, протестируйте на реальной задаче и лишь затем добавляйте scripts или упаковку в plugin.

Частые вопросы

Где хранить skill для одного репозитория?

Официальная документация описывает repo-scoped каталоги .agents/skills на пути от текущей директории до корня. Пользовательские skills могут находиться в домашнем каталоге .agents/skills.

Нужно ли создавать plugin для каждого skill?

Нет. Локальная папка удобна для разработки и применения в своей среде. Plugin нужен, когда workflow требуется устанавливать и распространять вместе с другими skills, MCP-подключениями или assets.

Может ли skill сам выдать дополнительные разрешения?

Нет. Он описывает процесс, но действует в пределах текущих tools, sandbox, approval policy и политик workspace. Зависимость на инструмент не заменяет авторизацию.

Что важно запомнить

Skill упаковывает повторяемый сценарий, AGENTS.md — постоянные правила области.
Точное description управляет уместной активацией.
Вход, выход, остановка и проверки должны быть явными.
Сначала испытайте простую instruction-only версию на реальных запросах.

https://yadro-code.ru/lessons/without-university/codex-agent-workflows/codex-agent-12