Умения агента (Agent Skills): как упаковать набор задач и научить Codex выполнять их

📚 Навигация по серии: Предыдущая статья [21 · Субагенты (Subagents)] описывала распределение тяжелых задач между помощниками с изолированным контекстом. В этой главе мы изменим подход: вместо деления задач мы займемся инкапсуляцией возможностей. Мы научимся упаковывать повторяющиеся цепочки действий в модули умений (Agent Skills), чтобы Codex вызывал их самостоятельно при возникновении нужного сценария. В следующей главе [23 · Плагины (Plugins)] мы разберем упаковку и дистрибуцию готовых умений для их использования другими разработчиками.

Я изучил официальный репозиторий github.com/openai/skills от OpenAI.

Структура умения (Skill) в нем предельно проста: для его работы требуется единственный файл SKILL.md. В начале файла в блоке разделителей указываются метаданные, ниже пишутся инструкции по выполнению задачи. Официальная документация позиционирует этот небольшой каталог как «формат описания повторно используемых рабочих процессов» (the authoring format for reusable workflows). Вы фиксируете в нем последовательность действий один раз, и Codex обращается к ней при необходимости, избавляя вас от ручного ввода.

Многие при первом знакомстве думают: «Это просто те же斜杠-команды в новой обертке. Разве команда /review из главы 12 не работает так же?». На самом деле разница принципиальна. 斜杠-команды вы вызываете вручную. Модули Skill работают автономно: Codex анализирует задачу, сопоставляет ее с описанием доступных умений, автоматически загружает нужное и при этом практически не расходует контекст в режиме ожидания.

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

После прочтения этой статьи вы получите:

• Что такое Skill: обязательный файл SKILL.md, скрипты и логика работы в виде каталога
• Как работает Progressive Disclosure (пошаговое раскрытие) для экономии контекста модели
• Разницу между явным вызовом (через $) и неявным запуском по смыслу (сопоставление описаний)
• Правильные папки для хранения умений: .agents/skills проекта и $HOME/.agents/skills
• Практическое использование команд создания $skill-creator, установки $skill-installer и настройки отключения умений в конфигурационном файле

---

01 Что такое умение (Skill)

Начнем с определения: модуль Skill представляет собой каталог с обязательным файлом SKILL.md, а также опциональными скриптами и справочными материалами, упакованными в виде конкретного навыка агента. Официальное руководство формулирует это так: «a Skill is a directory containing a SKILL.md file and optional scripts and resources».

Почему нужен этот инструмент? В повседневной работе с Codex вы постоянно повторяете одни и те же инструкции. Например, перед коммитом кода вы всегда требуете: «запусти тесты, переведи описание изменений на русский язык, добавь префикс feat или fix». Писать эти требования вручную десятки раз в неделю непродуктивно. Подобные повторяющиеся чек-листы — идеальная цель для умений.

Аналогия: инструкция по сборке конструктора Lego. Инструкция в коробке не собирает модель за вас, но она содержит детальные пошаговые иллюстрации («сначала закрепить раму, затем установить колеса, затем закрыть крышей»). Любой человек, следуя схеме, соберет игрушку одинаково. Модуль Skill — это системная пошаговая инструкция для Codex. Вы описываете логику (например, «составить список изменений и оценить риски») в файле SKILL.md, и Codex обращается к ней при решении задач.

Базовая структура файла SKILL.md включает метаданные и тело документа:

---
name: skill-name
description: 说清这个技能该在什么时候触发、什么时候不该触发。
---

供 Codex 遵循的技能指令写在这里。

Блок между разделителями --- называется YAML frontmatter (метаданные файла). Системные требования обязывают указать в нем ключи name (имя умения для ручного вызова) и description (описание возможностей для автоматического запуска). Ниже в формате Markdown пишутся пошаговые инструкции для модели.

⚠️ Типичная ошибка неофициальных руководств: использование в блоке метаданных ключа trigger (якобы для настройки ключевых слов запуска) и сохранение файлов в ~/.codex/skills/. В спецификации Codex ключа trigger не существует, запуск завязан на семантическое сопоставление поля description. Папки умений находятся в .agents/skills, а не в служебных каталогах конфигурации.

Каталог умения может содержать дополнительные папки:

my-skill/
├── SKILL.md          # Системное описание умения (обязательно)
├── scripts/          # Скрипты автоматизации (опционально)
└── references/       # Справочные материалы и документация (опционально)

Спецификация требует обязательного наличия только SKILL.md. Руководство рекомендует: ограничивайтесь простыми текстовыми инструкциями везде, где это возможно, прибегая к скриптам только для интеграции с внешними утилитами CLI или жестко фиксированных процессов. Модели Codex лучше работают по текстовым инструкциям, чем по жестким скриптам.

Примеры полезных умений на практике:

• commit: сборка изменений, проведение тестов локально и генерация описания коммита по правилам Conventional Commits;
• api-conventions: проверка создаваемого кода на соответствие RESTful-стандартам компании и обязательное добавление валидации аргументов;
• release-checklist: пошаговый сценарий подготовки релиза (обновление лога изменений, простановка тегов Git, запуск тестов).

💡 Резюме одной фразой: Skill — это папка с обязательным файлом SKILL.md (содержит имя name, описание description и инструкции) и опциональными скриптами/ресурсов. Вы настраиваете его один раз, и Codex использует этот навык в работе. Если задачу можно решить системными инструкциями, не пишите лишние скрипты.

---

02 Важнейший принцип: Progressive Disclosure (пошаговое раскрытие)

Это самый важный концептуальный раздел. Почему вы можете подключать множество умений, не опасаясь переполнения контекста модели? Дело в принципе пошагового раскрытия (progressive disclosure — загрузка данных строго по необходимости).

Напомним логику контекстного окна модели (подробно описано в главе 02). Рабочая область памяти AI имеет лимит. Каждый токен в чате расходует баланс и снижает качество анализа глубоких логических связей. Если при старте сессии загружать в нее тексты всех подключенных умений, память переполнится мгновенно.

Аналогия: таблички с меню на раздаче в столовой. Вы идете вдоль прилавка и видите только короткие названия блюд («Суп гороховый», «Салат овощной»). Вы понимаете ассортимент, но рецепты приготовления и список ингредиентов не занимают место на вашем подносе. Только когда вы выбираете конкретное блюдо, повар берет соответствующий рецепт на кухне. Умения работают по этой логике:

Codex 启动时，只带着每个技能的名称、描述和文件路径。只有当它决定使用某个技能时，才会加载该技能完整的 SKILL.md 指令。

Синтаксис разделен на этапы:

• Режим ожидания: Codex держит в памяти только имена, описания description и пути к файлам умений (таблички в меню);
• Запуск: когда задача сопоставляется с описанием, Codex подгружает в контекст полный Markdown-текст файла SKILL.md (рецепт).

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

Схема этапов раскрытия:

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

Однако стартовый список заголовков также имеет системные ограничения:

为了不挤占提示词的其余空间，这份初始清单被限制在模型上下文窗口的约 2%，或上下文窗口未知时的 8,000 个字符。如果装了很多技能，Codex 会先缩短描述；对于极大的技能集，部分技能可能被从初始清单里省略，Codex 会给出警告。

Это накладывает важное требование на разработчика: всегда размещайте ключевые слова и суть умения в самом начале поля description. При сжатии списка описания могут урезаться с конца, поэтому важные зацепки должны идти первыми. Это аналогично правилу размещения инструкций в начале AGENTS.md (глава 11): самое важное пишем в начале.

💡 Резюме одной фразой: принцип Progressive Disclosure экономит контекст, загружая в сессию только имя и описание умения в режиме ожидания, раскрывая полный файл SKILL.md строго при вызове. Стартовый список ограничен лимитом в 2% (или 8000 символов) — размещайте ключевые триггеры в начале описания.

---

03 Два способа вызова умений: явное указание имени и фоновое сопоставление

Для запуска умений в Codex предусмотрены два сценария.

Аналогия: заказ еды в ресторане. Вы можете точно назвать блюдо («Принесите борщ») — заказ сразу пойдет на кухню без лишних вопросов. Или вы можете описать пожелание («Хочу что-нибудь горячее, жидкое и сытное»), и официант сам сопоставит запрос с меню и принесет подходящее блюдо.

Явный вызов (по имени)

Вы явно указываете имя умения в чате. Спецификация CLI и IDE позволяет использовать斜杠-команду /skills или символ $ перед именем умения:

$commit

Ввод символа $ открывает список доступных умений. При явном вызове Codex не производит проверку соответствия промпта описанию, а сразу импортирует полный файл SKILL.md в сессию.

⚠️ Ошибка старых версий: вызов по символу @ не поддерживается в спецификации. Для работы с умениями используется строго символ $.

Неявный вызов (по описанию)

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

Это удобный сценарий, но он накладывает требования на составление поля description:

因为隐式匹配依赖 description，所以要写简洁、范围清晰、边界明确的描述。把关键用例和触发词前置，这样即使描述被缩短，Codex 仍能匹配到这个技能。

Избегайте размытых описаний вроде «помогает писать код». Пишите конкретные фразы, которые вы будете использовать в чате: «анализирует изменения на диске. Используется при запросах „что я изменил“, „сгенерируй описание изменений“ или „посмотри diff“».

Сравнение двух подходов:

Параметр	Явный вызов ($ / /skills)	Неявный вызов (сопоставление)
Способ запуска	Ввод символа $ или выбор через /skills	Обычный запрос в чате, сопоставляемый алгоритмом
Решение Codex	Без проверок, мгновенный запуск	Сопоставляет промпт с полем description
Качество работы	Точность вашего выбора	Правильность формулировки описания
Сфера применения	Точный контроль времени запуска умения	Автоматизация фоновых рутинных задач
Возможность отключения	Отключить нельзя	Можно отключить (через параметр allow_implicit_invocation, раздел 05)

💡 Резюме одной фразой: явный вызов по символу $ или команде /skills надежен и предсказуем. Неявный запуск по описанию удобен, но требует тщательного составления поля description с использованием реальных фраз пользователя в начале текста.

---

04 Каталоги размещения умений: структура папок .agents/skills

Спецификация Codex определяет считывание умений на четырех уровнях: проект (REPO), пользователь (USER), администратор (ADMIN) и система (SYSTEM). При сканировании проекта Codex проверяет путь от текущей папки вверх до корня репозитория, собирая все файлы умений.

Пути каталогов приведены в таблице:

Область действия	Путь к папке	Сфера применения
REPO (текущая папка)	$CWD/.agents/skills	Текущий рабочий каталог — специфичные умения модуля
REPO (родительская папка)	$CWD/../.agents/skills	Родительский каталог — общие умения вложенной структуры
REPO (корень репозитория)	$REPO_ROOT/.agents/skills	Корень репозитория — общие умения для всей кодовой базы
USER (пользователь)	$HOME/.agents/skills	Глобально на вашем ПК — умения доступны во всех проектах
ADMIN (система)	/etc/codex/skills	Доступно всем пользователям данного ПК (административные скрипты)
SYSTEM (встроенные)	Поставляются с Codex	Системные умения (skill-creator и планировщики)

⚠️ Важное отличие путей: папки умений сохраняются в скрытую директорию .agents/skills (локально или в домашней папке пользователя). Папки ~/.codex/ зарезервированы под файлы конфигурации ( config.toml), не создавайте в них каталоги умений, система не сможет их прочитать.

Спецификация определяет: глобальные личные умения (например, правила коммита) хранятся в $HOME/.agents/skills, а специфичные для проекта (например, правила сборки контейнера) — в папке .agents/skills в корне проекта.

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

Файлы умений отслеживаются системой автоматически, изменения в SKILL.md применяются без перезапуска. При возникновении сбоев обновите сессию Codex.

💡 Резюме одной фразой: файлы умений сохраняются в локальные папки .agents/skills (поиск идет вверх до корня проекта) или глобальную папку $HOME/.agents/skills. Не используйте пути ~/.codex/ (они зарезервированы под настройки). При совпадении имен файлы не перезаписываются, а выводятся списком в интерфейсе.

---

05 Практика: создание умений через $skill-creator, установка и отключение

Рассмотрим практические аспекты работы с умениями.

Создание умений через $skill-creator

Рекомендуется использовать встроенный мастер создания умений:

$skill-creator

Интерактивный мастер задаст три вопроса: назначение умения, условия запуска и необходимость использования внешних скриптов. После этого в каталоге автоматически сформируется папка умения с шаблоном SKILL.md.

Вы также можете создать папку и файл SKILL.md вручную по шаблону из раздела 01.

Установка готовых умений через $skill-installer

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

$skill-installer linear

Установщик скачает файлы и разместит их в вашем каталоге.

Позиционирование: $skill-installer предназначен для быстрого ознакомления с умениями. Для распространения пакетов умений с файлами настроек в команде используется формат плагинов (Plugins), детальный разбор которого представлен в главе 23. Skill — это формат описания, Plugin — формат дистрибуции.

Отключение умений без удаления файлов

Если вам нужно временно деактивировать умение (например, встроенное), пропишите его параметры в глобальный файл настроек ~/.codex/config.toml:

# ~/.codex/config.toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Для применения изменений перезапустите сессию. Это позволяет временно отключать неиспользуемые умения для экономии лимитов стартового списка.

Блокировка автоматического (неявного) запуска

Вы можете запретить системе автоматически применять умение на основе семантического сопоставления. Для этого создайте файл agents/openai.yaml внутри папки умения:

# agents/openai.yaml
policy:
  allow_implicit_invocation: false

При значении false умение будет запускаться строго при явном вызове через символ $. Это полезно для деструктивных операций (например, отправка релиза в продакшн), чтобы AI случайно не применил навык при обычном диалоге.

Сводная таблица параметров управления:

Задача	Инструмент	Расположение / Команда
Быстрое создание умения	$skill-creator	Запуск команды в чате
Установка готовых умений	$skill-installer [имя]	Запуск команды в чате
Временное отключение умения	Блок [[skills.config]]	Файл ~/.codex/config.toml
Отключение неявного вызова	Флаг allow_implicit_invocation: false	Файл agents/openai.yaml в каталоге умения
Размещение файлов	Папка с файлом SKILL.md	Пути .agents/skills или $HOME/.agents/skills

💡 Резюме одной фразой: создание выполняется через $skill-creator, установка — через $skill-installer. Отключение настраивается в файле config.toml (блок [[skills.config]]), блокировка неявного запуска — в agents/openai.yaml. Не путайте папки: настройки хранятся в .codex, файлы умений — в .agents.

---

06 Практика: создание и тестирование простого умения за 3 минуты

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

Шаг 1. Создаем папку умения (в Unix-терминале)

mkdir -p ~/.agents/skills/explain-self

В Windows используйте PowerShell: mkdir ~/.agents/skills/explain-self (при необходимости создайте родительские каталоги по очереди).

Шаг 2. Записываем файл SKILL.md

Текстовым редактором запишите файл ~/.agents/skills/explain-self/SKILL.md:

---
name: explain-self
description: 用大白话解释一段代码或一个报错。当用户说「这段代码啥意思」「这个报错咋回事」「帮我读读这个」时使用。
---

把用户给的代码或报错，用初学者能懂的大白话讲清楚：

1. 这东西整体在干啥（一句话）
2. 逐行 / 逐段拆开说
3. 如果是报错，指出最可能的原因和怎么改

不要堆术语，能用生活类比就用。

Поле description содержит маркеры запросов для семантического сопоставления.

Шаг 3. Запускаем сессию и проверяем активность

codex

Вызовите список умений:

/skills

Ожидаемый результат: в списке отобразится умение explain-self со своим описанием. Это подтверждает корректность обнаружения. Полный текст инструкций в память еще не загружен.

Шаг 4. Проверка автоматического (неявного) запуска

Отправьте запрос без символа $, используя фразу из описания:

这段代码啥意思：print(sum([1,2,3]) / len([1,2,3]))

Ожидаемый результат: Codex сопоставит запрос с описанием и активирует умение explain-self. Ответ будет структурирован согласно файлу SKILL.md (общая суть вычислений среднего арифметического, разбор функций и результат 2.0).

Шаг 5. Проверка явного запуска

Вызовите умение напрямую:

$explain-self 这个报错咋回事：ZeroDivisionError: division by zero

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

💡 Резюме одной фразой: выполните на практике последовательность «создание scout.toml с флагом read-only → создание calc.py → вызов субагента scout в чате → проверка сохранности calc.py после завершения».

---

07 Итоги

Мы разобрали устройство умений (Skills) в Codex, принципы экономии контекста и способы управления поведением модели.

Повторим ключевые выводы:

Тема	Ответ	Ключевой нюанс
Что такое Skill	Папка с файлом SKILL.md и скриптами	Обязательные поля метаданных: name и description
Экономия контекста	Принцип Progressive Disclosure	В режиме ожидания загружаются только заголовки (лимит 2% или 8000 символов)
Способ запуска	Явный или неявный	Использование символа $ или автоматическое сопоставление по описанию
Где хранить	Папки .agents/skills	В локальной папке проекта или глобально в $HOME/.agents/skills
Инструменты управления	Запуск команд и файлы настроек	Создание через $skill-creator, установка через $skill-installer, отключение в config.toml

Теперь вы умеете: описывать структуру умения (Skill) и принципы экономии контекста (Progressive Disclosure). Вы понимаете отличия явного и неявного способов вызова и умеете составлять качественные описания для автоматического запуска. Вы знаете правила размещения файлов в каталогах .agents/skills, логику поведения при совпадении имен, методы создания через $skill-creator и отключения в config.toml. Упаковка повторяющихся инструкций в модули умений позволяет обучить Codex вашим внутренним стандартам разработки.

Помните три основных системных правила: файлы сохраняются в .agents, а не .codex; в метаданных нет ключа trigger; вызов по имени выполняется через символ $, а не @. Это защитит от ошибок совместимости.

---

В следующей статье — [23 · Плагины (Plugins)]. Модули умений (Skills) работают локально на вашем ПК или в текущем репозитории. Чтобы передать настроенные интеграции и умения коллегам или сообществу для простой установки, используется формат плагинов (Plugins). Спецификация определяет: «Skill — это формат описания, а Plugin — формат дистрибуции». В следующей главе мы научимся упаковывать группу умений со всеми настройками в единый плагин. И небольшой вопрос на размышление: если вы хотите передать созданный в этой практике навык explain-self коллегам, достаточно ли просто закоммитить его в Git или требуется дополнительный шаг?

---

Рекомендуемое чтение

• Четыре типовых рабочих сценария: исследование, багфиксинг, рефакторинг и тесты
• Расширения для IDE (VS Code и другие)
• Плагины (Plugins): пакетная установка и распространение возможностей