Скил в Codex - это небольшая папка с инструкциями, скриптами и вспомогательными файлами, которые превращают общую модель в специализированного помощника для конкретной повторяемой задачи. Хороший скил не пытается объяснить Codex очевидные вещи. Он хранит то, что важно именно в вашей среде: адреса сервисов, порядок действий, ограничения безопасности, примеры команд, правила проверки и готовые скрипты.
В качестве примера удобно разобрать скил для публикации в Wiki.js. В нашем случае он нужен для портала WiKi Briz по адресу https://wiki.briz.cln.su: Codex пишет Markdown-статью, публикует ее через GraphQL API, загружает изображения, обновляет ручное меню и не раскрывает API-токены в чате или репозиториях.
Скил стоит создавать, когда задача повторяется и в ней есть локальные правила, которые легко забыть:
Если задача одноразовая, достаточно обычного промта. Если же вы уже второй или третий раз объясняете Codex один и тот же порядок действий, это кандидат на скил.
Типовой скил лежит в каталоге ~/.codex/skills/<skill-name> и содержит:
wikijs-briz-publisher/
├── SKILL.md
├── agents/
│ └── openai.yaml
└── scripts/
├── publish_wikijs.py
├── upload_wikijs_asset.py
└── update_wikijs_navigation.py
Файл SKILL.md обязателен. В нем есть YAML front matter с name и description, а ниже - рабочие инструкции для Codex. Скрипты нужны там, где операция должна выполняться одинаково каждый раз: публикация страницы, загрузка asset-файлов, обновление навигации.
Поле description - главный механизм срабатывания скила. Codex видит его до загрузки тела SKILL.md, поэтому именно там нужно перечислить, когда использовать скил.
Пример:
---
name: wikijs-briz-publisher
description: "Publish Markdown documentation, images, and navigation menu entries to the user's Wiki.js portal WiKi Briz at https://wiki.briz.cln.su through the API. Use when the user asks to publish docs, update knowledge base pages, upload Wiki.js assets, manage Wiki.js menu entries, or work with WiKi Briz."
---
В тело SKILL.md не стоит прятать условия срабатывания. Тело будет прочитано уже после того, как Codex решил использовать скил.
В SKILL.md нужно держать только то, что помогает выполнить задачу:
WiKi Briz;https://wiki.briz.cln.su/graphql;ru;/ru в URL, если namespacing отключен;Пример ключевых правил:
## Core Facts
- Portal alias: `WiKi Briz`
- Portal URL: `https://wiki.briz.cln.su`
- GraphQL endpoint: `https://wiki.briz.cln.su/graphql`
- Default locale: `ru`
- Default path prefix: `doc/linux/ansible`
- Markdown pages must use editor value `markdown`.
- Browser and menu URLs must not include `/ru` when multilingual namespacing is disabled.
- Never ask the user to paste API tokens into chat.
Токены не должны лежать в скиле, git-репозитории или тексте статьи. Для Codex удобно использовать private-хранилище:
/Users/neon/.codex/private/wikijs-briz.env
Пример содержимого:
# Wiki.js API secrets for Codex
# Default target: WiKi Briz
WIKIJS_URL=https://wiki.briz.cln.su
WIKIJS_TOKEN=replace-with-real-token
WIKIJS_LOCALE=ru
WIKIJS_PATH_PREFIX=doc/linux/ansible
Права на файл:
chmod 600 /Users/neon/.codex/private/wikijs-briz.env
Скрипты должны читать конфиг в таком порядке: переменные окружения текущего процесса, project-local .env, затем private-файл Codex.
Скрипты делают скил надежным. Вместо того чтобы каждый раз заново писать GraphQL-запросы, Codex вызывает готовую команду:
python3 scripts/publish_wikijs.py docs/wiki/example.md --dry-run
python3 scripts/publish_wikijs.py docs/wiki/example.md
Для Wiki.js полезны три скрипта:
publish_wikijs.py - создает или обновляет Markdown-страницу;upload_wikijs_asset.py - загружает изображения и печатает Markdown-ссылки;update_wikijs_navigation.py - добавляет или чинит пункт ручного меню.Скрипт публикации должен искать страницу по path и locale. Если страница есть, он делает update. Если Wiki.js вернул PageNotFound, это нормальный сценарий для новой статьи, и скрипт должен выполнить create.
Практичный workflow выглядит так:
Пример front matter:
---
title: Создание скилов для Codex
description: Практическая инструкция по созданию Codex-скилов.
section: codex
path: sozdanie-skilov-codex
locale: ru
tags:
- codex
- skills
published: true
private: false
---
Такой файл будет опубликован по пути:
codex/sozdanie-skilov-codex
А браузерный URL будет:
/codex/sozdanie-skilov-codex
В Wiki.js новая страница может существовать, но не отображаться в ручном меню. Поэтому для базы знаний полезно сделать правило: после публикации новой статьи Codex обязательно добавляет пункт меню или явно сообщает, почему не смог этого сделать.
Для раздела Codex можно создать одноименную группу доступа Codex, добавить в нее нужных пользователей и использовать эту группу в visibilityGroups для пункта меню. Это разделяет две вещи:
Codex не должен создавать группы вслепую. Сначала нужно прочитать groups.list, проверить, существует ли группа, и только потом создавать недостающую. Пользователя также нужно искать по имени или email, а не подставлять случайный id.
После создания или изменения скила нужно выполнить минимальную проверку:
python3 -m py_compile scripts/publish_wikijs.py scripts/upload_wikijs_asset.py scripts/update_wikijs_navigation.py
python3 scripts/publish_wikijs.py docs/wiki/example.md --dry-run
Также нужно проверить, что токен не попал в SKILL.md, agents/openai.yaml, references/ или git diff.
PageCreateForbidden или PageUpdateForbidden означает, что API-токену не хватает прав или page rules запрещают запись в выбранный путь.
PageNotFound при lookup - нормальный случай для новой страницы. Это не ошибка публикации, а сигнал перейти к create.
Если Markdown отображается как обычный текст, проверьте, что страница создана с editor: markdown в нижнем регистре.
Если страница открывается с лишним /ru, проверьте настройку multilingual namespacing. Когда namespacing выключен, locale=ru остается API-параметром, но не частью URL.
Если Codex не может подключиться к wiki.briz.cln.su, проверьте сеть, VPN и доступность портала с той машины, где выполняется публикация.
Хороший скил - это не большая инструкция обо всем на свете, а компактный рабочий контракт между пользователем, Codex и конкретной системой. В примере с WiKi Briz скил фиксирует адрес портала, правила безопасности, порядок публикации, работу с меню и хранение секретов. Благодаря этому Codex может не просто написать статью, а довести публикацию до проверенного результата.