# Codex Skills для начинающих: автоматизация рабочих сценариев ИИ-агента

> Практическое руководство по созданию и использованию Skills в Codex: анатомия SKILL.md, явная и авто-активация, разница между навыками, скриптами и тулами, Skills API и настройка безопасности.

## 1. Что такое Codex Skill: переход от разовых промптов к повторяемым сценариям

В процессе регулярной разработки с **Codex** инженеры часто вводят один и тот же набор инструкций: какие файлы проанализировать, по каким стандартам выполнять проверку, какие архитектурные ограничения соблюдать и в каком виде представить результат. Необходимость повторять эти требования в каждом диалоге замедляет работу и приводит к случайным ошибкам.

**Codex Skill (навык)** — это сохраненный, повторно используемый рабочий сценарий для определенного типа задач. Создание навыка не является дообучением (fine-tuning) модели: веса нейросети остаются неизменными. Вместо этого агент получает четкий регламент действий, который динамически подгружается в контекстное окно именно тогда, когда возникает соответствующая задача.

```mermaid
flowchart LR
    subgraph AdHoc ["Традиционный подход (Ручной ввод)"]
        User1["Пользователь"] -->|Каждый раз вводит длинные правила| Prompt["Длинный разовый промпт"]
        Prompt --> Agent1["Codex"]
    end

    subgraph Modular ["Подход на основе Skills"]
        User2["Пользователь"] -->|Краткий запрос: $code-review| Agent2["Codex"]
        SkillsDir["Репозиторий Skills (SKILL.md)"] -->|Автоматическая загрузка правил| Agent2
        Agent2 --> Output["Стандартизированный результат"]
    end
```

> [!NOTE]
> В официальной экосистеме OpenAI навыки уже стали стандартом автоматизации. Например, для перевода кодовой базы на актуальные модели OpenAI предоставляет готовый Skill `openai-docs`, знающий все нюансы свежего SDK без необходимости вручную прикреплять документацию.

---

## 2. Критерии выбора: когда нужен Skill, а когда достаточно обычного промпта

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

| Критерий оценки | Обычный разовый промпт | Codex Skill |
| :--- | :--- | :--- |
| **Частота использования** | Разовая уникальная задача | Регулярный сценарий (ежедневно или перед релизом) |
| **Сложность процесса** | 1–2 простых действия | Многошаговый регламентированный пайплайн с проверками |
| **Дополнительные ресурсы** | Не требуются | Требует вспомогательных скриптов, справочников или чеклистов |
| **Требования к результату** | Произвольный текст | Фиксированная структура отчета (таблица, JSON) |
| **Границы безопасности** | Стандартные настройки сессии | Четко зафиксированные права на чтение и запись |

### Типичные кандидаты для оформления в виде Skill

- **Предрелизный аудит репозитория:** Запуск линтеров, поиск забытых отладочных инструкций (`console.log`, `TODO`), валидация типов.
- **Стандартизированное код-ревью:** Проверка изменений на соответствие внутренним соглашениям команды без внесения несанкционированных правок.
- **Генерация релизных заметок:** Сбор списка объединенных PR, их структурирование по категориям и обновление `CHANGELOG.md`.
- **Миграция компонентов:** Пошаговый рефакторинг устаревших конструкций по утвержденному шаблону.

> [!TIP]
> **Инженерное правило трех раз:** Если вы ловите себя на том, что уже в третий раз объясняете Codex один и тот же порядок действий («сначала прочитай этот файл, запусти тесты, ничего сам не меняй, оформи ответ в виде таблицы») — этот процесс пора упаковать в отдельный Skill.

---

## 3. Механика активации: явный вызов через $name против автоматического подбора

Codex поддерживает два взаимодополняющих способа активации навыков: прямой детерминированный вызов пользователем и автоматическое распознавание на основе семантического совпадения.

### Явный вызов (Explicit Invocation)

Пользователь напрямую указывает имя нужного навыка через знак доллара `$`:

```bash
$code-review проверь последние изменения в ветке feature/auth
```

Этот способ дает 100% предсказуемость: Codex мгновенно активирует указанный Skill, делает его инструкции базовым регламентом и применяет их к переданным аргументам.

### Автоматическая активация (Semantic Auto-Match)

Если префикс `$name` не указан, Codex анализирует текст запроса и сопоставляет его с полем `description` всех доступных навыков:

```mermaid
flowchart TD
    Req["Запрос: 'Подготовь релизные заметки для v2.1.0'"] --> Router{"Семантический анализ запроса"}
    Router -->|Match: description release-notes| LoadSkill["Загрузка .codex/skills/release-notes/SKILL.md"]
    Router -->|No Match| Standard["Обычный диалог без накладных расходов"]
    LoadSkill --> Exec["Выполнение регламентированного сценария"]
```

```text
Удачное описание (высокая точность активации):
description: Проверяет измененные файлы проекта на регрессии, ошибки типов и стиль перед релизом. Используйте при аудите PR.

Неудачное описание (размытые границы):
description: Помогает разработчику писать хороший код.
```

---

## 4. Анатомия навыка и структура SKILL.md: метаданные, правила и ресурсы

Минимальный Skill состоит всего из одного файла — `SKILL.md`. Более зрелые навыки могут содержать вложенные скрипты автоматизации, справочные руководства и шаблоны.

```text
project-review/
├── SKILL.md                   # Основной файл (метаданные + инструкции)
├── scripts/
    └── check-deps.sh          # Скрипт для быстрых автоматических проверок
├── references/
    └── styleguide.md          # Справочник: внутренний код-стайл команды
└── templates/
    └── report-template.md     # Шаблон итогового отчета
```

### Структура файла `SKILL.md`

Файл состоит из двух частей: блока метаданных YAML Frontmatter в начале и пошаговых инструкций в формате Markdown.

```markdown
---
name: project-review
description: Проводит комплексный аудит кода перед релизом, проверяет типы и формирует отчет об ошибках без внесения изменений.
---

Инструкции по аудиту:
1. Запустить "npm run typecheck" для поиска ошибок компиляции TypeScript.
2. Изучить git diff относительно основной ветки main.
3. Разбить найденные замечания на категории: Critical, Warning, Suggestion.
4. Категорически запрещено изменять исходные файлы проекта.
5. Предоставить сводный отчет по шаблону templates/report-template.md.
```

> [!IMPORTANT]
> **Принцип лаконичности:** Не перегружайте `SKILL.md` длинными вводными рассуждениями. Чем короче и четче инструкции, тем меньше места они занимают в контекстном окне и тем точнее агент следует заданному алгоритму.

---

## 5. Области хранения: проектные навыки против персональных глобальных

Codex разделяет навыки по двум областям видимости в зависимости от их назначения:

```mermaid
flowchart TD
    subgraph GlobalScope ["Глобальные навыки (~/.codex/skills/)"]
        G1["Персональный стиль коммитов"]
        G2["Генератор лицензионных заголовков"]
    end

    subgraph ProjectScope ["Проектные навыки (.codex/skills/)"]
        P1["Архитектурный линтер репозитория"]
        P2["Генератор миграций БД и DTO"]
        P3["Чек-лист перед выкаткой в прод"]
    end

    Dev["Разработчик"] -->|Личные привычки| GlobalScope
    Team["Команда через Git"] -->|Общие стандарты| ProjectScope
```

### Проектные навыки (`.codex/skills/` или `.agents/skills/`)
Хранятся в корне репозитория и фиксируются в Git.
- **Назначение:** Стандартизация процессов для всей команды разработчиков.
- **Преимущество:** Любой инженер или CI/CD раннер, клонирующий репозиторий, сразу получает единый набор инструментов.

### Персональные навыки (`~/.codex/skills/`)
Располагаются в домашней папке пользователя операционной системы.
- **Назначение:** Личные рабочие сценарии конкретного разработчика.
- **Преимущество:** Доступны во всех проектах и терминалах на данной машине.

---

## 6. Практический воркшоп: создание навыка проверки кода с помощью $skill-creator

Самый быстрый способ создать новый навык — использовать встроенный в Codex инструмент `$skill-creator`.

### Шаг 1. Запуск мастера создания

В терминальной сессии Codex вызовите команду:

```bash
$skill-creator
```

Опишите желаемый сценарий простыми словами:

```text
Создай проектный навык с именем "pr-validator".
Задача: проверка измененных файлов в текущем pull request.
Правила:
1. Запустить npm run lint и npm test.
2. Проверить наличие тестов для новых утилит.
3. Запретить агенту самостоятельно исправлять найденные дефекты.
4. Вывести результат в виде таблицы: Файл, Строка, Проблема, Уровень риска.
```

### Шаг 2. Проверка сгенерированного файла

Мастер создаст директорию `.codex/skills/pr-validator/` и запишет файл `SKILL.md`:

```markdown
---
name: pr-validator
description: Validates pull request changes by running lint and test suites, checking test coverage for new modules, and returning an issue table without modifying code.
---

Execution Steps:
1. Identify modified files using git diff against the target branch.
2. Execute "npm run lint" and capture any linter warnings or errors.
3. Execute "npm test" to ensure regression safety.
4. Verify whether newly created source files in src/ have corresponding test files in tests/.
5. Strict constraint: Do NOT modify any project files under any circumstances.
6. Present the audit findings in a markdown table:
   | File | Line | Issue | Severity |
```

### Шаг 3. Тестирование навыка в новой сессии

Откройте новую сессию Codex и протестируйте работу созданного навыка:

```bash
$pr-validator проверь текущую ветку перед открытием PR
```

Убедитесь, что агент запустил тесты, не изменял файлы и оформил отчет в виде таблицы.

---

## 7. Триада возможностей агента: навык (Skill), скрипт (Script) и инструмент (Tool)

Разработчики иногда путают понятия навыка, скрипта и инструмента (Tool / MCP). Они решают разные технические задачи и взаимно дополняют друг друга.

```mermaid
flowchart TD
    subgraph Triad ["Триада возможностей автономного агента"]
        Skill["SKILL (Навык)<br><i>'Мышление и регламент'</i><br>Определяет алгоритм, контекст и правила"]
        Script["SCRIPT (Скрипт)<br><i>'Детерминированное вычисление'</i><br>Быстро и надежно выполняет действия на диске"]
        Tool["TOOL (Инструмент / MCP)<br><i>'Органы чувств и руки'</i><br>Предоставляет доступ к API, терминалу, базам данных"]
    end

    Skill -->|Управляет логикой| Script
    Skill -->|Использует| Tool
    Script -->|Выполняется через| Tool
```

### Сравнительная таблица триады

| Компонент | Роль в системе | Способ выполнения | Пример |
| :--- | :--- | :--- | :--- |
| **Skill (Навык)** | **Регламент и принятие решений** | Интерпретируется языковой моделью | Инструкция по аудиту безопасности |
| **Script (Скрипт)** | **Вычислительное действие** | Запускается в оболочке ОС | Bash-скрипт парсинга тегов версий |
| **Tool (Инструмент)** | **Интерфейс доступа к окружению** | Вызывается через Tool Calling | MCP-сервер для работы с GitHub API |

> [!NOTE]
> Навык объясняет, **что** и **в какой последовательности** нужно сделать. Скрипт быстро производит вычисления без расхода токенов. Инструмент дает агенту права на взаимодействие с внешней средой.

---

## 8. Программное управление через Skills API и версионирование

OpenAI предоставляет **Skills API** для программного управления наборами навыков в серверных приложениях и облачных пайплайнах.

```bash
# Создание нового навыка через HTTP API
curl https://api.openai.com/v1/skills \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "schema-migrator",
    "description": "Автоматическая валидация и создание безопасных миграций базы данных",
    "instructions": "Проверь схему Prisma, убедись в отсутствии деструктивных drop column..."
  }'
```

### Зачем нужно версионирование Skills

1. **Неизменность продакшна (Immutability):** При обновлении создается новая версия (`v1`, `v2`). Автоматизированные CI/CD процессы жестко фиксируют номер версии, защищая пайплайн от неожиданных изменений.
2. **Мгновенный откат (Rollback):** Если новая формулировка привела к ошибкам, можно в одну секунду переключиться на стабильную предыдущую версию.
3. **A/B тестирование промптов:** Возможность запускать параллельные тесты двух вариантов инструкций для оценки точности и скорости выполнения.

---

## 9. Безопасность, границы автономии и правила подтверждения действий

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

```mermaid
flowchart LR
    Action["Действие агента"] --> Decision{"Категория риска"}
    Decision -->|Безопасное: Read-Only| Auto["Автономное выполнение без пауз<br><i>(Чтение файлов, запуск тестов)</i>"]
    Decision -->|Опасное: Write / Network| Confirm["Обязательный запрос подтверждения<br><i>(Удаление данных, деплой)</i>"]
```

### Матрица уровней доверия

:::tabs
@tab Разрешено автономно
- Чтение исходного кода, конфигураций и документации.
- Анализ логов компиляции и ошибок в терминале.
- Запуск изолированных unit-тестов в режиме чтения.
- Форматирование аналитических таблиц и отчетов.
@tab Требует подтверждения инженера
- Изменение глобальных конфигурационных файлов (`package.json`, `.env`).
- Удаление, перемещение или перезапись существующих файлов.
- Выполнение сетевых запросов или отправка данных на внешние серверы.
- Создание коммитов или пуш изменений в удаленный Git-репозиторий.
:::

> [!WARNING]
> **Не дублируйте запреты многократно:** Избегайте повторения фраз «ничего не меняй» в каждом предложении. Достаточно один раз четко сформулировать ограничения, иначе агент станет излишне осторожным и начнет запрашивать разрешение даже на чтение обычного файла.

---

## 10. Итоговая шпаргалка и чек-лист создания надежного Skill

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

### Справочник команд разработчика

```bash
# ─── Управление навыками в Codex ─────────────────────────────────
$skill-creator                      # Запуск интерактивного мастера создания
$<skill-name> <описание задачи>     # Явный детерминированный вызов навыка
/skills                             # Просмотр списка доступных навыков

# ─── Расположение файлов в системе ───────────────────────────────
.codex/skills/<name>/SKILL.md       # Проектный навык (версионируется в Git)
~/.codex/skills/<name>/SKILL.md      # Персональный навык (для всей рабочей машины)
```

### Чек-лист готовности навыка к релизу

- [ ] **Корректное имя:** До 64 символов, строчные буквы латиницы через дефис (`kebab-case`).
- [ ] **Двусоставное описание:** Поле `description` содержит четкую формулу «что делает навык» и «в каких случаях его вызывать».
- [ ] **Лаконичное тело:** Объем `SKILL.md` не превышает 500 строк и содержит только специфику проекта.
- [ ] **Нумерованная структура:** Инструкции оформлены последовательными шагами (`1.`, `2.`, `3.`).
- [ ] **Определены границы безопасности:** Зафиксированы разрешенные файлы для чтения и операции, требующие подтверждения.
- [ ] **Протестировано в новой сессии:** Навык проверен как прямым вызовом `$name`, так и через автоматический семантический подбор.