Delay-delo Портфолио fullstack-разработчика

На главную / Статьи и заметки

Как создать skill для Codex и автоматизировать повторяющиеся задачи разработки

ИИ и автоматизация 13 июня 2026 г. 11 мин чтения

Разработчик редко пишет один и тот же код дважды, но постоянно повторяет одни и те же действия. Перед коммитом запускает тесты, проверяет линтер, ищет случайно добавленные секреты, просматривает изменённые файлы и составляет краткий отчёт. При создании нового модуля снова объясняет AI-агенту структуру каталогов, правила именования и порядок проверки.

Поначалу это не раздражает. Через неделю появляется большой промт, сохранённый где-то в заметках. Через месяц у него уже пять версий, и никто не помнит, какая актуальна. Знакомая история?

Skill в Codex переносит такой рабочий процесс из случайного промта в отдельный управляемый модуль. Вы один раз описываете правила, добавляете нужные команды и сохраняете вспомогательные материалы. После этого Codex применяет их при подходящих задачах.

Это не магическая кнопка и не новый язык программирования. По сути, skill - небольшая инструкция для AI-агента, упакованная вместе со скриптами и справочными файлами. Главное здесь не размер. Главное - повторяемость.

Схема автоматизации задач разработки через skill в Codex

Что именно можно автоматизировать через skill

Хороший кандидат встречается регулярно, выполняется по понятным правилам и имеет проверяемый результат. Например, проверка проекта перед pull request, подготовка нового модуля, анализ ошибки, обновление документации или аудит изменённых файлов.

Skill полезен и там, где команда часто объясняет агенту один и тот же контекст. Допустим, новый API-модуль всегда создаётся по принятому шаблону. Сначала контракт, затем тест, после него минимальный код, обновление документации и запуск конкретной команды. Вместо длинного промта этот процесс можно записать один раз.

А вот слишком общая инструкция вроде «пиши хороший код» почти бесполезна. Codex не получает из неё ни последовательности действий, ни критерия завершения. Чем точнее область применения, тем стабильнее поведение агента.

Из чего состоит skill

Минимальный skill представляет собой каталог с файлом SKILL.md. В начале файла размещается YAML-блок с названием и описанием. Ниже идут инструкции в Markdown.

project-preflight/
└── SKILL.md

Для рабочего сценария структура обычно шире:

project-preflight/
├── SKILL.md
├── scripts/
│   ├── check-project.ps1
│   └── check-project.sh
├── references/
│   └── review-rules.md
└── assets/
    └── report-template.md

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

Не нужно складывать всё в SKILL.md. Если инструкция разрастается, Codex тратит контекст на сведения, которые не нужны в каждой задаче. Основной файл лучше оставить навигатором, а детали вынести отдельно.

Структура каталога пользовательского skill для Codex

Создаём skill для проверки проекта

Разберём практический пример. Нам нужен skill под названием project-preflight. Он должен проверять проект перед коммитом или pull request.

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

На Windows 11 создайте каталог через PowerShell:

New-Item -ItemType Directory -Force `
  -Path "$HOME\.agents\skills\project-preflight\scripts"

New-Item -ItemType Directory -Force `
  -Path "$HOME\.agents\skills\project-preflight\references"

New-Item -ItemType File -Force `
  -Path "$HOME\.agents\skills\project-preflight\SKILL.md"

Глобальный пользовательский каталог подходит для skill, который нужен в разных проектах. Командный skill лучше хранить в репозитории или отдельном Git-репозитории, где изменения можно проверять через review.

Пишем YAML-заголовок

Начало SKILL.md определяет, как Codex распознаёт модуль. Поле name содержит короткое машинное имя. Поле description объясняет, когда навык следует применять.

---
name: project-preflight
description: Use when checking a software project before a commit or pull request. Inspect changed files, run available validation commands, check for exposed secrets, and produce a concise verification report without modifying unrelated code.
---

Описание важнее, чем кажется. Codex может найти skill по смыслу запроса, поэтому фраза должна описывать не тему вообще, а момент применения.

Слабый вариант звучит так:

description: Helps check projects.

Из него непонятно, что именно проверяется и когда запускать процесс. Сильный вариант перечисляет ситуацию, основные действия и ограничения.

Описываем рабочий процесс

После YAML-блока добавьте инструкции. Они должны говорить агенту, что делать, в каком порядке и где остановиться.

# Project Preflight

Run a structured project check before a commit or pull request.

## Required workflow

1. Read AGENTS.md and project documentation if they exist.
2. Inspect the current branch and working tree.
3. List changed and untracked files.
4. Detect the project's available validation commands.
5. Run relevant lint, test, type-check, and build commands.
6. Check changed files for exposed secrets and debug artifacts.
7. Produce a concise report with commands, results, and blockers.

## Safety rules

- Do not modify unrelated files.
- Do not install new dependencies without explicit permission.
- Do not disable tests or validation rules.
- Do not report success when a required command failed.
- Do not commit, push, or merge changes.
- Never print secret values in the report.

## Completion criteria

The report must include:

- current branch;
- changed files;
- commands executed;
- exit status of every command;
- failed checks;
- skipped checks and reasons;
- final status: PASS, FAIL, or BLOCKED.

Внутри skill допустимы списки, поскольку это техническая инструкция для агента. В статье они показаны в блоке кода, а не используются как элементы оформления страницы.

Обратите внимание на отрицательные правила. Они нужны не для красоты. AI-агент любит быть полезным и иногда начинает «заодно» обновлять зависимости, исправлять чужой код или обходить падающую проверку. Явные ограничения уменьшают такую самодеятельность.

Добавляем PowerShell-скрипт

Текстовая инструкция подходит для анализа, но повторяемые команды надёжнее вынести в скрипт. Для Windows создайте файл scripts/check-project.ps1.

param(
    [string]$ProjectPath = "."
)

$ErrorActionPreference = "Stop"

Set-Location $ProjectPath

$results = @()

function Invoke-ProjectCheck {
    param(
        [Parameter(Mandatory = $true)]
        [string]$Name,

        [Parameter(Mandatory = $true)]
        [string]$Command
    )

    Write-Host ""
    Write-Host "Running: $Name"
    Write-Host "Command: $Command"

    & powershell.exe -NoProfile -Command $Command
    $exitCode = $LASTEXITCODE

    $script:results += [PSCustomObject]@{
        Name     = $Name
        Command  = $Command
        ExitCode = $exitCode
        Status   = if ($exitCode -eq 0) { "PASS" } else { "FAIL" }
    }
}

Write-Host "Current branch:"
git branch --show-current

Write-Host ""
Write-Host "Changed files:"
git status --short

if (Test-Path "package.json") {
    $packageJson = Get-Content "package.json" -Raw | ConvertFrom-Json

    if ($packageJson.scripts.lint) {
        Invoke-ProjectCheck -Name "Lint" -Command "npm run lint"
    }

    if ($packageJson.scripts.test) {
        Invoke-ProjectCheck -Name "Tests" -Command "npm run test"
    }

    if ($packageJson.scripts.build) {
        Invoke-ProjectCheck -Name "Build" -Command "npm run build"
    }
}

if (Test-Path "composer.json") {
    if (Test-Path "vendor\bin\phpunit.bat") {
        Invoke-ProjectCheck `
            -Name "PHPUnit" `
            -Command ".\vendor\bin\phpunit.bat"
    }

    if (Test-Path "vendor\bin\phpstan.bat") {
        Invoke-ProjectCheck `
            -Name "PHPStan" `
            -Command ".\vendor\bin\phpstan.bat analyse"
    }
}

Write-Host ""
Write-Host "Verification summary:"
$results | Format-Table -AutoSize

if ($results.Status -contains "FAIL") {
    exit 1
}

exit 0

Скрипт не пытается угадать весь стек. Он ищет известные конфигурации и запускает только доступные команды. Для реального проекта его можно дополнить проверкой других менеджеров пакетов, контейнеров или внутренних инструментов.

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

Связываем инструкцию со скриптом

Теперь укажите в SKILL.md, когда Codex должен запускать файл:

## Automated check

On Windows, run:

```powershell
powershell.exe -ExecutionPolicy Bypass -File scripts/check-project.ps1
```

Treat a non-zero exit code as a failed verification.

After the script finishes, inspect its output and verify that
project-specific commands from AGENTS.md were not missed.

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

Запуск PowerShell-скрипта из пользовательского skill Codex

Добавляем справочные правила

Допустим, у команды есть отдельные требования к review. Не обязательно загружать их при каждом запуске. Создайте файл references/review-rules.md и сослаться на него из основного документа.

## Review reference

Read `references/review-rules.md` when:

- the task involves a pull request;
- more than five source files changed;
- authentication, payments, permissions, or migrations changed.

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

В справочном файле можно хранить критерии безопасности, правила архитектуры и формат замечаний. Не дублируйте сведения из AGENTS.md. Skill описывает повторяемый процесс, а AGENTS.md - правила конкретного проекта.

Как запустить новый skill

После добавления файлов перезапустите Codex, поскольку перечень доступных skills обычно загружается при старте новой сессии.

Для явного запуска сформулируйте запрос так:

Примени skill project-preflight.

Проверь текущий проект перед pull request.
Не исправляй ошибки автоматически.
Верни отчёт с командами, кодами завершения и блокирующими проблемами.

Можно написать и естественнее:

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

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

Как проверить, что skill действительно работает

Наличие файла ещё не означает, что процесс получился надёжным. Skill стоит тестировать примерно так же, как код.

Сначала запустите контрольный запрос без skill и сохраните поведение агента. Затем повторите задачу с новым модулем. Сравните порядок действий, количество пропущенных проверок и формат отчёта.

Подготовьте несколько сценариев. В первом все команды проходят. Во втором тест падает. В третьем отсутствует часть зависимостей. В четвёртом среди изменённых файлов лежит подозрительный .env. В пятом репозиторий не содержит знакомых конфигураций.

Хороший skill ведёт себя предсказуемо во всех случаях. При падении теста он не пишет PASS. При отсутствии команды указывает BLOCKED или отмечает пропуск. При обнаружении секрета сообщает имя файла, но не выводит само значение.

А знаете что? Именно тест с ошибкой обычно приносит больше пользы, чем идеальный сценарий. На нём быстро видно, пытается ли агент честно остановиться или начинает обходить собственные правила.

Сценарии тестирования пользовательского skill в Codex

Типичные ошибки при создании skills

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

Вторая ошибка - расплывчатое описание. Codex должен понимать момент запуска по двум или трём предложениям. Если description подходит к половине задач разработки, автоматическое подключение станет непредсказуемым.

Третья ошибка - отсутствие критериев завершения. Фраза «проверь проект» не говорит, какой отчёт вернуть и какое состояние считать успешным.

Четвёртая ошибка - скрытая модификация проекта. Проверяющий skill не должен самовольно редактировать файлы. Анализ и исправление лучше разделить. Сначала отчёт, затем отдельное разрешение на изменения.

Пятая ошибка - огромный SKILL.md. Основной документ должен объяснять маршрут. Большие таблицы, шаблоны и узкие инструкции удобнее хранить в references и assets.

Шестая ошибка - вера в один удачный запуск. AI может правильно выполнить привычный сценарий и ошибиться на пограничном. Несколько контрольных запросов дают гораздо более честную картину.

Skill, AGENTS.md и обычный промт - где граница

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

Например, правило «не менять публичный API без согласования» относится к проекту и должно находиться в AGENTS.md. Процесс «перед pull request собери перечень изменений, запусти проверки и подготовь отчёт» подходит для skill.

Они не конкурируют. Codex сначала учитывает контекст проекта, а затем применяет специализированный процесс.

Когда пора создавать собственный skill

Посмотрите на последние задачи в Codex. Если один и тот же промт повторился трижды, это уже кандидат. Если перед каждым запуском приходится вставлять инструкцию из заметок, кандидат почти очевиден.

Начните с узкой операции, где легко определить успех. Проверка перед коммитом подходит лучше, чем попытка сразу описать всю разработку продукта.

Сохраните skill в Git. Изменяйте его небольшими коммитами. Проверяйте новые правила на реальных сценариях и удаляйте пункты, которые ничего не меняют. Документ должен оставаться рабочим инструментом, а не коллекцией красивых фраз.

Хороший skill не делает Codex умнее сам по себе. Он убирает случайность из повторяющихся действий. Агент получает понятный маршрут, разработчик - воспроизводимый результат, а команда перестаёт каждый раз объяснять один и тот же процесс заново.