Skills для Codex — это каталоги с инструкциями и дополнительными файлами, которые помогают агенту повторяемо выполнять конкретный рабочий процесс. Основа навыка — файл SKILL.md с метаданными и правилами; рядом могут лежать примеры, скрипты и справочные материалы. Skill не является отдельной моделью и не выдаёт агенту новые права: он описывает, как применять уже доступные инструменты.
Зачем нужны Skills
Обычный промпт удобно написать один раз, но в команде он быстро теряется. Skill превращает повторяемую последовательность в видимый пакет: что проверить сначала, какие файлы прочитать, в каком формате вернуть результат и как убедиться, что задача завершена. Это полезно для ревью, подготовки релиза, миграций документации, проверки SEO или запуска тестов.
Хороший кандидат на skill имеет стабильный вход и проверяемый выход. Например, на входе есть репозиторий и номер задачи, а на выходе — список изменённых файлов, результаты тестов и незакрытые риски. Если процесс каждый раз требует принципиально нового исследования и не имеет критериев готовности, его лучше оставить обычной задачей.
Учебный пример: вместо универсального навыка «делай сайт» создайте узкий workflow «проверь страницу перед публикацией». Он может требовать открыть шаблон, проверить обязательные поля, выполнить локальный тест и вернуть ссылки на найденные ошибки. Узкая область проще для проверки и реже вмешивается в несвязанные задачи.
Минимальная структура каталога
Официальная документация OpenAI описывает skill как папку с обязательным SKILL.md. Дополнительные каталоги необязательны и должны появляться только при реальной пользе.
my-skill/
├── SKILL.md
├── references/
│ └── checklist.md
├── scripts/
│ └── validate.sh
└── examples/
└── sample.mdМинимальный файл начинается с YAML front matter с полями name и description, затем содержит короткие инструкции. Название должно быть однозначным, а описание — объяснять, когда навык применять. Слишком широкое описание ухудшает выбор навыка: агенту сложнее понять, относится ли он к текущей задаче.
---
name: release-check
description: Проверяет проект перед публикацией и возвращает список блокеров.
---
Сначала проверь состояние репозитория и обязательные файлы.
Затем запусти команды из раздела «Проверка».
Не публикуй изменения и остановись при обнаружении блокера.Пути в skill должны быть относительными к каталогу навыка, если это возможно. Не зашивайте домашний каталог конкретного пользователя и не рассчитывайте на установленную только у автора утилиту без проверки. Если нужен скрипт, укажите, что он делает, какие входы принимает и какой код возврата означает ошибку.
Как писать инструкции, которые работают
Инструкция должна менять решение агента, а не повторять общие советы. Начинайте с триггера и границ: когда skill применять, а когда не применять. Затем задайте порядок действий, критерии остановки и формат результата. Читателю должно быть ясно, какие файлы нужны до старта и какие проверки обязательны перед завершением.
| Раздел | Что указать | Пример |
|---|---|---|
| Когда использовать | Триггер и нецели | Перед выпуском, не для разработки |
| Вход | Файлы и параметры | Корень проекта и окружение |
| Процедура | Порядок действий | Проверка → исправление → тест |
| Выход | Формат отчёта | Изменения, тесты, риски |
Пишите проверяемыми глаголами: «прочитай», «сравни», «запусти», «остановись», «верни». Избегайте слов «обычно», «при необходимости» и «сделай качественно», если рядом нет условия, по которому результат можно оценить. Если возможны разные варианты, зафиксируйте предпочтительный и опишите исключение.
Ресурсы, скрипты и контекст
Длинную справку не стоит помещать целиком в основной SKILL.md. Вынесите стабильные правила в references, примеры — в examples, а механические проверки — в scripts. Основной файл должен объяснять маршрут и указывать, когда читать дополнительный ресурс. Это уменьшает лишний контекст и позволяет обновлять чек-лист отдельно от workflow.
Скрипт должен быть детерминированным и безопасным по умолчанию. Сначала пусть он проверяет состояние, а запись или удаление делает только при явно заданном режиме. Не передавайте секреты через аргументы командной строки: они могут оказаться в истории shell или списке процессов. Логи должны содержать полезную диагностику, но не токены, пароли и персональные данные.
Если skill ссылается на команду, проверяйте её наличие и актуальный синтаксис в целевом окружении. Не утверждайте, что скрипт всегда доступен, если он зависит от конкретной IDE, ОС или версии пакета. Когда есть несколько способов, выбирайте самый переносимый и явно называйте ограничения.
Где обнаруживается и выполняется Skill
Документация OpenAI различает локальное выполнение и hosted-вариант. Для Agents API родительские каталоги навыков регистрируются как capability directories, после чего среда может обнаруживать вложенные каталоги с SKILL.md. В Codex конкретные пути и правила обнаружения зависят от версии клиента, поэтому перед установкой сверяйтесь с текущей документацией и репозиторием.
Важно не путать обнаружение и разрешения. Skill может попросить использовать инструмент, но не должен рассматриваться как механизм выдачи доступа к сети, файлам или внешнему сервису. Эти права задаются окружением, политиками и настройками пользователя. Если workflow требует внешнего действия, опишите подтверждение и безопасную остановку до него.
Учебная проверка после добавления навыка:
- убедиться, что каталог находится в зарегистрированном родительском пути;
- проверить front matter и уникальность имени;
- запустить простой запрос, который явно соответствует description;
- проверить, что нерелевантный запрос не вызывает навык;
- сравнить фактический отчёт с ожидаемым форматом.
Безопасность и границы автоматизации
Skill — это исполняемый workflow в широком смысле: он может направить агента к чтению файлов, запуску команд или обращению к подключённым инструментам. Поэтому новый навык нужно просматривать как кодовую инструкцию. Проверяйте источники скриптов, команды с записью и удалением, обработку ошибок, сетевые вызовы и раскрытие данных.
Начинайте с режима только чтения. После нескольких успешных запусков добавляйте запись, ограниченную конкретной директорией. Для операций с публикацией, платежами, удалением и отправкой сообщений нужен отдельный шаг подтверждения или явное правило остановки. Не маскируйте необратимые действия под «финальную проверку».
| Риск | Защита | Проверка |
|---|---|---|
| Слишком широкий доступ | Ограничить пути и окружение | Тест на соседний каталог |
| Утечка секрета | Маскирование и env-механизм | Проверить логи и diff |
| Опасная команда | Подтверждение и dry-run | Запустить на копии |
| Устаревшая инструкция | Ссылка на первичный источник | Регулярный пересмотр |
Как тестировать и поддерживать навык
Проверяйте skill на типичном сценарии, неполном входе и конфликтующем требовании. В первом случае он должен дать ожидаемый результат. Во втором — сообщить, чего не хватает, а не выдумать данные. В третьем — соблюдать более узкое ограничение, например «не менять файлы», если оно задано пользователем.
Полезно хранить рядом несколько маленьких примеров, но не подменять ими реальные тесты. Скрипт можно запускать отдельно от агента, чтобы понять, ошибка ли в инструкции или в автоматической процедуре. После изменения SKILL.md повторяйте тот же набор проверок: хеш файла и дата не говорят о качестве поведения.
Следите за устаревшими ссылками, командами и предположениями о версиях. В основной текст включайте только факты, которые нужны для решения, а изменчивые детали сопровождайте ссылкой на официальный источник. Если функция исчезла или изменилась, удалите старое утверждение, а не оставляйте его «на всякий случай».
Чек-лист перед использованием в команде
Перед передачей навыка коллегам проверьте:
- name и description точно описывают область применения;
- SKILL.md не содержит выдуманных возможностей и не обещает результат без проверки;
- все относительные пути существуют, а скрипты имеют понятный интерфейс;
- нет секретов, лишних персональных данных и опасных команд без защиты;
- описан формат финального отчёта и критерий остановки;
- есть первичные источники для изменчивых продуктовых фактов.
Skills лучше развивать небольшими версиями: одно изменение, один набор проверок, затем обновление документации. Для общих материалов можно изучить руководства, для практических задач — раздел проектов, а дополнительные статьи найти в блоге.
Как выбрать границы одного навыка
Один skill должен отвечать за один узнаваемый workflow. Если в него одновременно входят анализ требований, написание кода, деплой и рассылка уведомлений, результат становится трудно предсказать и тестировать. Разделите такой процесс на навыки или оставьте внешние переходы ручными. Хорошая граница обычно совпадает с одним типом входа и одним форматом отчёта.
Признак слишком широкого skill — длинный список исключений. Если половина SKILL.md объясняет, когда правило не действует, описание нужно сузить. Признак слишком узкого — инструкция повторяется только для одной разовой операции. В последнем случае лучше сохранить шаблон запроса или документацию, а не добавлять постоянный пакет.
Учебный пример разбиения: навык «проверка статьи» читает HTML и возвращает ошибки разметки; навык «проверка ссылок» выполняет HTTP-проверки; навык «подготовка выпуска» объединяет результаты и останавливается при блокере. Так проще повторить отдельную проверку и понять, где возникла ошибка.
Входы, выходы и повторяемость
В начале skill перечислите обязательные входы: путь к проекту, формат файла, переменные окружения без самих секретов, допустимую область изменений и команду проверки. Если вход неполный, инструкция должна предписывать сообщить об этом. Запрет на выдумывание данных важнее стремления любой ценой вернуть красивый отчёт.
Формат выхода лучше сделать коротким и стабильным. Например: статус, изменённые файлы, проверки, блокеры и следующие действия. Не требуйте от агента повторять большой лог; достаточно сохранить команду и ключевую строку ошибки, если полный вывод уже доступен в терминале. Стабильный формат облегчает ручное ревью и последующую автоматизацию.
Повторяемость означает не одинаковый текст ответа, а одинаковые правила принятия решений. Допустимы разные формулировки, но при одном и том же входе skill должен читать те же источники, выполнять те же проверки и останавливаться на тех же рисках. Для этого удаляйте случайные советы и явно задавайте порядок действий.
Версионирование и обновление документации
Храните skill рядом с проектом или в отдельном репозитории, где видны изменения и ревью. Даже если формат файла простой, обновление инструкции может изменить поведение агента так же заметно, как изменение кода. В описании коммита указывайте, какое решение стало другим и каким тестом оно подтверждено.
Продуктовые факты, команды и пути могут устареть. Для них добавляйте первичный источник и дату последней проверки. Не копируйте длинные фрагменты документации: достаточно кратко записать подтверждённое ограничение и ссылку. Если источник недоступен, исключите факт или сформулируйте его с явным ограничением, а не заполняйте пробел догадкой.
При обновлении полезно проверить три версии поведения: старый обычный сценарий, новый сценарий ради которого внесено изменение и негативный сценарий с неполным входом. Если меняется скрипт, отдельно протестируйте код возврата и сообщения об ошибке. Если меняется только description, проверьте, что навык вызывается в нужном контексте и не перехватывает соседние задачи.
Наблюдаемость и ручное ревью
Агентный workflow должен оставлять достаточно следов для проверки: какие файлы прочитаны, какие команды выполнены, какие изменения предложены и почему задача остановилась. Не превращайте лог в стенограмму всей сессии; фиксируйте только события, влияющие на результат. Для чувствительных проектов маскируйте значения и не сохраняйте необязательные данные.
Ревьюер должен уметь ответить на три вопроса: skill сделал то, что обещает description; он не вышел за разрешённые границы; его вывод подтверждается файлами и тестами. Если на любой вопрос нет ответа, навык ещё не готов для широкого использования. Доступность внешних приложений и политик проверяется отдельно от текста SKILL.md.
Такой контроль не делает workflow медленным. Наоборот, короткий детерминированный skill экономит время, потому что повторяет уже согласованный порядок и оставляет человеку только содержательные решения. Автоматизация полезна там, где она делает работу прозрачнее, а не там, где просто скрывает количество шагов.