# 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 або фіксована таблиця) |
| **Права та обмеження** | Поточні налаштування сесії | Чітко зафіксовані дозволені та заборонені дії |

### Типові сценарії для створення навички

- **Передрелізна перевірка репозиторію:** Запуск лінтерів, пошук залишеного налагоджувального коду (`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

Найпростіший та найшвидший спосіб створити нову навичку — скористатися системним мета-інструментом `$skill-creator`, вбудованим у Codex.

### Крок 1. Ініціалізація майстра створення

У діалоговому вікні Codex викликаємо команду:

```bash
$skill-creator
```

Після цього описуємо бажаний робочий процес природною мовою:

```text
Створи для мене проєктний скіл із назвою "pr-validator".
Ціль: перевірити змінені файли у поточному pull request.
Правила:
1. Запустити npm run lint та npm test.
2. Перевірити, чи додані unit-тести для нових модулів.
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-скрипт парсингу git-тегів |
| **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`). Продакшн-пайплайни прив'язуються до конкретної зафіксованої версії, унеможливлюючи несподівані збої через випадкові зміни.
2. **Безпечний відкат (Rollback):** Якщо оновлений опис призвів до регресії або погіршення якості генерації коду, команда може миттєво повернути попередній номер версії.
3. **A/B тестування інструкцій:** Можливість одночасно порівнювати продуктивність двох альтернативних редакцій навички на реальних завданнях.

---

## 9. Безпека, межі автономії та правила підтвердження дій

Skill безпосередньо впливає на те, які операції агент виконує у вашій системі. Тому в тілі навички обов'язково мають бути чітко розмежовані автономні та контрольовані дії.

```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`).
- Видалення або перезапис файлів у репозиторії.
- Виконання мережевих запитів або відправка даних у зовнішні API.
- Створення комітів або пуш змін у віддалений Git-репозиторій.
:::

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

---

## 10. Підсумкова шпаргалка та чек-лист створення надійного Skill

Збережіть цей чек-лист та орієнтуйтеся на нього під час проєктування кожної нової навички.

### Швидка шпаргалка інженера

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

# ─── Файлова структура проєкту ───────────────────────────────────
.codex/skills/<name>/SKILL.md       # Проєктна навичка (для всієї команди)
~/.codex/skills/<name>/SKILL.md      # Персональна навичка (для поточної машини)
```

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

- [ ] **Чітке ім'я:** До 64 символів, у нижньому регістрі латиницею, через дефіс (`kebab-case`).
- [ ] **Інформативний опис:** Поле `description` містить чітку формулу «що робить навичка» та «коли її слід запускати».
- [ ] **Лаконічне тіло:** Текст `SKILL.md` не перевищує 500 рядків і містить лише специфіку проєкту.
- [ ] **Покроковий пайплайн:** Інструкції розбиті на нумеровані кроки без двозначностей.
- [ ] **Визначено межі безпеки:** Зафіксовано, які файли дозволено читати та для яких дій обов'язково потрібне підтвердження користувача.
- [ ] **Перевірено в чистій сесії:** Навичка протестована як через явний виклик `$name`, так і через автоматичний підбір опису.