Экспериментальная система skills в OpenAI Codex: как агент учится пользоваться инструментами

В Codex появилась экспериментальная фича — skills: декларативное описание локальных «навыков» агента с автоматическим discovery и строгими правилами применения. В статье разберём, как это работает под капотом, зачем нужно и как использовать это в своих проектах.

Введение: зачем агенту вообще нужны skills

Современный агент поверх LLM — это не просто «читалка текста», а оркестратор инструментов:

• скриптов разработки и деплоя;

• внутренних API и сервисов;

• генераторов документации и отчётов;

• служебных утилит по работе с логами, БД, инфраструктурой.

Чтобы ИИ-агент эффективно пользовался этими инструментами, ему нужно:

1. знать, какие инструменты существуют;

2. понимать, когда их применять;

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

4. делать всё это, не раздувая контекст до десятков тысяч токенов.

Типичный путь — зашивать инструкции про инструменты прямо в system‑prompt: «для деплоя запусти такой-то скрипт, для логов прочитай такой-то файл» и т.д. Однако такой подход плохо масштабируется:

• контекст переполняется повторяющимися инструкциями;

• документация в репозитории и в промпте расходится;

• становится сложно обновлять описание инструментов без ручного редактирования промпта.

Экспериментальная система skills в Codex решает эту проблему:

• каждый навык описывается на диске в виде отдельного каталога;

• на старте агент автоматически находит все доступные skills;

• в контекст подмешивается компактный раздел ## Skills cо списком навыков и строгими правилами использования;

• подробные инструкции остаются в файлах, а не в промпте — агент читает их «по требованию».

В итоге инструменты перестают быть «магическими командами из промпта» и превращаются в явные, версионируемые навыки агента, описанные в вашем рабочем окружении.

Исторически похожая идея сначала обкатывалась не в Codex, а в экосистеме конкурирующего агента (по мотивам Claude от Anthropic), где модель училась системно работать с внешними инструментами через механизм tool use (см. «Build with Claude / Tool use»). Уже затем концепция была переосмыслена и оформлена в виде файловых skills в Codex.

В этой статье мы опираемся на открытую реализацию Codex: модуль codex-rs/core/src/skills/render.rs в репозитории https://github.com/openai/codex (коммит ad7b9d63c326d5c92049abd16f9f5fb64a573a69).

Архитектура skills: как навык выглядит на диске

В терминах Codex skill — это небольшой модуль возможностей, описанный в файловой системе под ~/.codex/skills. Для каждого навыка создаётся директория, внутри которой лежит документация и вспомогательные артефакты.

Типичная структура навыка:

~/.codex/skills/
  log-analyzer/
    SKILL.md
    scripts/
      parse_logs.py
      summarize.sh
    references/
      log-format.md
    assets/
      report-template.md

Ключевую роль играет файл SKILL.md:

• в нём хранится YAML‑описание навыка (имя, человекочитаемое описание и др.);

• это описание является главным триггером: агент сопоставляет текст запроса пользователя с description и решает, применять ли skill;

• сам SKILL.md задаёт «контур» документации, на которую агент может опираться, не затягивая в контекст весь репозиторий.

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

SkillMetadata и рендер списка навыков

На уровне кода ядро работы со списком навыков реализовано в модуле codex-rs (Rust‑реализация ядра Codex). Для каждого навыка строится структура SkillMetadata, которая, как минимум, содержит:

• name — имя навыка;

• description — человекочитаемое описание из SKILL.md;

• path — путь до файла или каталога навыка.

На основе этого списка Codex умеет генерировать компактный фрагмент Markdown, который вставляется в контекст в начале диалога. Это делает функция render_skills_section в codex-rs/core/src/skills/render.rs:

use crate::skills::model::SkillMetadata;

pub fn render_skills_section(skills: &[SkillMetadata]) -> Option<String> {
    if skills.is_empty() {
        return None;
    }

    let mut lines: Vec<String> = Vec::new();
    lines.push("## Skills".to_string());
    lines.push("These skills are discovered at startup from ~/.codex/skills; each entry shows name, description, and file path so you can open the source for full instructions. Content is not inlined to keep context lean.".to_string());

    for skill in skills {
        let path_str = skill.path.to_string_lossy().replace('\', "/");
        lines.push(format!(
            "- {}: {} (file: {})",
            skill.name, skill.description, path_str
        ));
    }

    // далее добавляется блок с правилами использования

    Some(lines.join("n"))
}

Здесь можно выделить несколько важных технических моментов:

1. Опциональный рендер. Если доступных навыков нет, функция возвращает None — раздел ## Skills просто не попадает в контекст.

2. Минималистичный вывод. В список попадает только:
   — заголовок ## Skills,
   — короткое пояснение,
   — строки вида - Name: Description (file: path). Никаких длинных инструкций или содержимого SKILL.md здесь нет.

3. Нормализация путей. Вызов replace('\', "/") приводит путь к единообразному виду, удобному и для Unix, и для Windows. Это полезно как для человека (можно скопировать путь), так и для UI‑обвязки.

Результат работы render_skills_section — небольшой Markdown-фрагмент, который можно добавить в system‑prompt или в ранний контекст диалога:

## Skills
These skills are discovered at startup from ~/.codex/skills; each entry shows name, description, and file path so you can open the source for full instructions. Content is not inlined to keep context lean.

- LogAnalyzer: Parse and summarize application logs (file: ~/.codex/skills/log-analyzer/SKILL.md)
- TrendFetcher: Query Google Trends and store results (file: ~/.codex/skills/trends/SKILL.md)
- SiteDeployer: Build and deploy the main web app (file: ~/.codex/skills/site-deployer/SKILL.md)

Дальше к этому списку добавляется большой блок правил поведения — его текст берётся из отдельного гиста и вшивается в код как многострочная raw‑строка. Именно этот блок превращает стек файлов и скриптов в явный протокол работы агента с навыками.

Протокол работы агента со skills: что зашито в ## Skills

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

Discovery: где искать навыки и инструкции

Текст инструкции подчёркивает:

Available skills are listed in project docs and may also appear in a runtime “## Skills” section (name + description + file path). These are the sources of truth; skill bodies live on disk at the listed paths.

То есть для агента «истинами» являются:

• список skills в разделах документации проекта;

• runtime‑раздел ## Skills, который он видит в контексте;

• реальные файлы на диске, указанные в этом списке.

Агент не должен придумывать навыки сам — он опирается на явный каталог.

Trigger rules: когда skill нужно использовать обязательно

Дальше идёт набор правил активации навыков:

If the user names a skill (with $SkillName or plain text) OR the task clearly matches a skill’s description, you must use that skill for that turn.

Это значит:

• если пользователь явно упоминает навык ($LogAnalyzer или «используй LogAnalyzer»);

• или формулировка задачи попадает под description навыка;

агент обязан использовать соответствующий skill в текущем ходе.

Отдельное важное уточнение:

Do not carry skills across turns unless re-mentioned.

Skill не «приклеивается» навсегда. Для каждого нового шага агент заново анализирует запрос и принимает решение, какие навыки применимы сейчас. Это защищает от ситуации, когда один удачно применённый инструмент начинает использоваться автоматически «везде».

Progressive disclosure: как не утопить модель в документации

Следующий блок посвящён экономии контекста:

After deciding to use a skill, open its SKILL.md. Read only enough to follow the workflow.

Эта идея разворачивается в несколько правил:

1. После выбора навыка агент открывает его SKILL.md и читает ровно столько, сколько нужно для текущей задачи.

2. Если в SKILL.md есть ссылки на references/, агент загружает только указанные файлы, а не всю папку.

3. Если есть каталог scripts/, предпочтительно запускать или модифицировать существующие скрипты, а не перепечатывать их содержимое в prompt.

4. Если есть assets/ и шаблоны, их нужно переиспользовать, а не изобретать структуры с нуля.

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

Координация нескольких навыков

Для случаев, когда к задаче подходят сразу несколько skills, задано правило:

If multiple skills apply, choose the minimal set that covers the request and state the order you’ll use them.

Агент должен:

• выбрать минимальный набор навыков, который покрывает задачу;

• явно обозначить порядок их применения.

Пример:

• для задачи «проанализировать логи и оформить отчёт» можно использовать LogAnalyzer и IncidentReporter;

• агент сначала проговаривает: «Сначала применю LogAnalyzer для парсинга логов, затем IncidentReporter для формирования отчёта»;

• затем следует сценариям из соответствующих SKILL.md.

Это делает поведение агента предсказуемым и прозрачным.

Контекст‑гигиена (context hygiene)

Отдельный блок посвящён гигиене контекста:

• не вставлять в промпт большие куски документации целиком, а суммировать их;

• не строить длинные цепочки вложенных ссылок;

• выбирать только релевантные вариации (например, конкретный framework или provider, если их несколько).

Skills в этом смысле выступают «воротами» в мир документации: навык задаёт начальную точку входа и ограничивает объём загружаемой информации.

Safety и fallback: что делать, если skill недоступен

Последний важный элемент протокола:

If a skill can’t be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue.

Если:

• файл навыка отсутствует;

• путь из ## Skills недоступен;

• SKILL.md не даёт достаточно ясных инструкций;

агент должен:

1. явно объяснить, почему skill нельзя применить;

2. выбрать запасной путь (например, более ручной разбор кода или логов);

3. продолжить выполнение задачи, не «ломаясь» и не выдавая молчаливые ошибки.

Практический пример: skills в реальном рабочем процессе

Представим проект, в котором Codex‑агент помогает команде разработки и эксплуатации веб‑сервиса. В ~/.codex/skills настроены следующие навыки:

• DeployService — сборка и деплой основного сервиса;

• LogAnalyzer — парсинг и агрегирование логов;

• TrendFetcher — работа с Google Trends и сохранение результатов в локальное хранилище.

Раздел ## Skills в контексте будет содерж��ть, среди прочего, строку:

- TrendFetcher: Query Google Trends and store results (file: ~/.codex/skills/trends/SKILL.md)

Сценарий использования:

1. Пользователь: «Собери тренды по запросу “industrial sensors” за последний год и запиши результат в нашу БД».

2. Агент:

   • по описанию понимает, что задача попадает в область TrendFetcher;

   • открывает ~/.codex/skills/trends/SKILL.md;

   • находит там инструкции (например, «вызвать scripts/fetch_trends.py, затем scripts/store_results.sh»);

   • выполняет шаги и возвращает пользователю краткий сводный отчёт.

Позже пользователь обращается с задачей:

«Посмотри последние логи продакшена и скажи, не выросла ли ошибка timeout для API /rfq».

Теперь агент смотрит на описания навыков, видит, что подходит LogAnalyzer, и:

• выбирает именно его;

• не применяет TrendFetcher, несмотря на то, что тот был использован в предыдущем запросе;

• следует инструкциям из ~/.codex/skills/log-analyzer/SKILL.md.

Ещё один характерный сценарий — контент‑маркетинг. Вместо того чтобы городить отдельного «агента‑маркетолога», «агента для SEO‑описаний» и «агента для карточек товаров», можно завести одного Codex‑агента с набором контентных skills, например:

• SeoArticleWriter — пишет SEO‑статьи под заданные ключи и структуру;

• ProductCardGenerator — генерирует карточки товаров (заголовок, преимущества, характеристики, FAQ);

• CategoryLandingBuilder — собирает SEO‑лендинги для категорий (подбор блоков, перелинковка, вставка сниппетов).

Раздел ## Skills в таком случае может содержать, среди прочего, строки:

- SeoArticleWriter: Write long-form SEO articles given keywords, brief, and target audience (file: ~/.codex/skills/seo-article-writer/SKILL.md)
- ProductCardGenerator: Generate product cards with SEO titles, benefits, and specs (file: ~/.codex/skills/product-card-generator/SKILL.md)

Дальше всё работает по уже описанному протоколу:

• запрос «Напиши SEO‑статью про промышленные датчики для блога поставщика» будет триггерить SeoArticleWriter — агент откроет его SKILL.md, посмотрит, как собирать бриф, структуру и метатеги, и выполнит шаги из сценария;

• запрос «Сгенерируй 50 карточек товаров для каталога датчиков давления по этим CSV‑данным» — активирует ProductCardGenerator, который в SKILL.md может описывать пайплайн: парсинг источника → нормализация атрибутов → шаблонизация текста → экспорт в нужный формат.

Так один агент остаётся «лицом» для менеджера по маркетингу или контент‑специалиста, а сложность разбивается на прозрачные, проверяемые навыки, которые живут в файловой системе и эволюционируют вместе с бизнес‑процессами.

Таким образом skills превращают набор скриптов и утилит в набор осмысленных, контекстно применимых навыков, которыми агент пользуется осознанно.

Ограничения текущей реализации и возможности развития

Текущая реализация системы skills в Codex — намеренно минималистичная, но уже полезная на практике.

Преимущества:

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

• Единый формат описания. SKILL.md становится точкой входа для документации и сценариев.

• Контролируемый контекст. Раздел ## Skills остаётся небольшим, а тяжёлые материалы загружаются только по запросу.

• Явный протокол. Вшитые в раздел правила делают поведение агента предсказуемым и объяснимым.

Ограничения:

• в текущей версии нет явного версионирования протокола skills;

• список навыков обновляется на старте, динамическое hot‑reload ещё не описано;

• нет стандартных категорий для навыков (DevOps, Data, Content и т.д.) — всё определяется описаниями.

Возможные направления развития:

• добавить версию протокола и схемы в SKILL.md;

• расширить метаданные (например, область применения, уровень доступа, тип окружения);

• интегрировать список skills в UI, чтобы человек мог управлять статусом и конфигурацией навыков.

Заключение

Экспериментальная система skills в Codex — это шаг к тому, чтобы агенты работали с инструментами так же дисциплинированно, как опытные инженеры:

• инструменты описаны явно, версионируются и живут рядом с кодом;

• инструкции по применению вынесены из промпта в SKILL.md;

• в контекст попадает только компактный каталог навыков и чёткий протокол поведения.

Для разработчика это означает:

• меньше ручного prompt‑инжиниринга;

• больше прозрачности и повторяемости поведения агента;

• возможность строить поверх Codex собственные наборы навыков, которые легко развивать и поддерживать.

Если вы уже используете Codex как помощника в разработке или эксплуатации, следующий логичный шаг – сформулировать свои внутренние инструменты в терминах skills, описать их в SKILL.md и дать агенту возможность пользоваться ими так же уверенно, как это делает человек.