Skill в Codex - это папка с обязательным SKILL.md и опциональными references, scripts, templates и assets. Ключевая идея в том, как он загружается: в начальном контексте Codex видит только метаданные навыка, а полный файл подтягивается лишь при явном вызове или совпадении цели пользователя с описанием. Этот механизм progressive disclosure - способ держать много навыков наготове, не оплачивая их контекстом заранее: грузится только то, что реально понадобилось.

Отсюда решающая роль описания в метаданных. Именно по нему Codex решает, релевантен ли навык текущей задаче, поэтому description должно точно называть, когда навык применять, а не что он абстрактно умеет. Полезно один раз увидеть каркас SKILL.md. Ниже - frontmatter с name и description ("используй, когда меняется поведение или схема API и нужны проверки контракта, интеграции и совместимости") и сам набор шагов. Точное описание - это то, что включает навык в нужный момент, а не наугад.

Тело навыка - это проверяемая процедура, а не расплывчатый совет. Хороший SKILL.md ведёт по шагам: определить публичный контракт и затронутых вызывающих, прогнать узкий контрактный тест до правки, внести минимальное изменение, удовлетворяющее требуемому поведению, проверить. Такая структура превращает повторяемую задачу в воспроизводимый порядок, которому агент следует одинаково, а не изобретает каждый раз заново по памяти о том, "как обычно делаем".

Instruction-only навык - это хороший выбор по умолчанию. Пока навык - это просто инструкция без исполняемого кода, он несёт минимум риска: его нельзя использовать как канал выполнения, его легко прочитать и отревьюить. Скрипт добавляют только тогда, когда он действительно нужен - для детерминированной операции, которую словами не выразить надёжно. Соблазн "сразу написать скрипт" стоит сдерживать: чаще всего внятной инструкции достаточно, а скрипт добавляет то, за что потом отвечать.

Любой скрипт в навыке расширяет supply-chain и permission-риск, и это надо учитывать явно. Скрипт - это исполняемый код, который поедет вместе с навыком к тем, кто его установит, и получит права процесса. Поэтому для скрипта указывают входы, выходы, ожидаемые коды возврата и негативные случаи - то есть описывают его как проверяемый компонент, а не как чёрный ящик. Навык со скриптом ревьюят строже, чем instruction-only, ровно потому, что цена ошибки в нём выше.