Система навыков Codex Agent Skills
Agent Skills — это механизм расширения задач Codex. Упаковывая инструкции, ресурсы и дополнительные скрипты в стандартизированные пакеты навыков, они позволяют Codex надёжно выполнять определённые рабочие процессы.
Agent Skill — это по сути папка, которая должна содержать файлSKILL.md. Файл должен как минимум содержать метаданные, такие как имя и описание, а также руководство, объясняющее AI-агенту, как выполнить конкретную задачу. Пакеты навыков также могут включать скрипты, справочные материалы, шаблоны и различные другие ресурсы.
my-skill/ ├── SKILL.md # 必备文件：元数据 + 执行指引 ├── scripts/ # 可选：可执行脚本 ├── references/ # 可选：参考文档 ├── assets/ # 可选：模板、各类资源文件 └── ... # 其他额外文件与目录
Терминология
- AI-агенты: интеллектуальный AI-агент (распространённый отраслевой перевод)
- Agent Skills: Agent Skill (проприетарная концепция, сохраняйте фиксированное обозначение)
- metadata: метаданные
- workflows: рабочий процесс/поток выполнения
Что такое Agent Skills
Skills — это формат создания многоразовых рабочих процессов.
Каждый Skill — это по сути каталог, содержащий файлSKILL.md. Codex читает инструкции в нём и выполняет их шаг за шагом.
Можно рассматривать навык как "стандартную операционную процедуру", написанную для Codex: она чётко определяет, что делать, когда делать и как делать. Затем Codex может автоматически активировать её в нужный момент или выполнить её, когда вы явно вызываете её.
Навыки — это "формат создания", тогда как плагины — это "формат распространения". Сначала используйте навыки, чтобы спроектировать сам рабочий процесс; упакуйте его как плагин, когда нужно распространить его среди других разработчиков.
Навыки доступны в Codex CLI, расширении IDE и приложении Codex.
Вы можете просматривать или создавать навыки в плагине:
В Codex есть встроенныйSkill Creator, нажмитеCreat skill, чтобы перейти в окно создания навыка, где мы можем напрямую сказать ему, какой навык создать:
Просмотр установленных навыков:
Как работают навыки
Codex использует механизмпрогрессивного раскрытиядля управления контекстным окном, чтобы избежать одновременной загрузки всего содержимого навыков и вытеснения пространства промпта.
Процесс прогрессивной загрузки
При запуске Codex загружает только имя, описание и путь к файлу каждого навыка в качестве начального списка.
Только когда Codex решает использовать навык, он загружает полное содержимое инструкцииSKILL.md.
Чтобы не вытеснять пространство промпта, количество символов в начальном списке навыков ограниченопримерно 2% контекстного окна модели, или 8,000 символов, когда контекстное окно неизвестно.
Если установлено слишком много навыков, Codex сначала сокращает описания; если лимит всё ещё превышен, некоторые навыки могут не появиться в начальном списке, и Codex отображает предупреждение.
Это ограничение бюджета применяется только к первоначальному списку навыков. После того как Codex выбирает навык, он всё равно читает полный файл SKILL.md для этого навыка.
Два метода запуска
Codex поддерживает два способа активации навыков:
Явный вызов
Ссылайтесь на навык напрямую в запросе. В CLI или IDE используйте/skillsкоманду или введите$символ, чтобы указать навык.
При явном вызове Codex не нужно выполнять никакой проверки соответствия; он напрямую загружает полный SKILL.md и выполняет его.
Неявное сопоставление
Когда описание задачи, которое вы предоставляете, совпадает с полемdescriptionнавыка, Codex автоматически выбирает этот навык.
Точность неявного сопоставления полностью зависит от качества поля description.
При написании description ставьте основные варианты использования и ключевые слова-триггеры в начало, чтобы даже при усечении description Codex всё равно мог правильно сопоставить.
Структура каталога навыка
Навык — это каталог, содержащий файлыSKILL.md, и может включать необязательные скрипты, справочную документацию, файлы ресурсов и конфигурацию метаданных.
my-skill/
├── SKILL.md # 必备项：使用指引 + 元数据
├── scripts/ # 可选：可执行代码
├── references/ # 可选：参考文档
├── assets/ # 可选：模板、各类资源
└── agents/
└── openai.yaml
Обязанности каждого файла/каталога следующие:
| Файл/каталог | Обязательно? | Описание |
|---|---|---|
| SKILL.md | Обязательный | Основной файл инструкций для навыка; должен содержатьnameиdescriptionполе |
| scripts/ | Optional | Хранит исполняемый код, используемый для сценариев, требующих детерминированного поведения или вызова внешних инструментов |
| references/ | Optional | Хранит дополнительную справочную документацию, к которой Codex может обращаться при выполнении навыка |
| assets/ | Optional | Хранит файлы статических ресурсов, такие как шаблоны и изображения |
| agents/openai.yaml | Optional | Настраивает метаданные UI, политику вызова и объявления зависимостей инструментов |
Быстрый старт: создайте свой первый навык
Рекомендуется использовать встроенный создатель навыков для быстрого создания каркаса навыка.
Создание с помощью skill-creator
Введите следующую команду в Codex, чтобы запустить интерактивный процесс создания:
Пример
$skill-creator
Создатель задаст следующие вопросы по порядку:
| Шаг | Вопрос | Описание |
|---|---|---|
| 1 | Что делает этот навык? | Определите задачу, которую навык должен выполнять |
| 2 | Когда он должен срабатывать? | Решите, срабатывает ли он при явном вызове или неявном сопоставлении |
| 3 | Только инструкции или включает скрипты? | По умолчанию рекомендуется режим чистых инструкций, так как он лаконичен и прост в поддержке |
Ручное создание
Вы также можете вручную создать каталог навыка и файл SKILL.md:
Пример
name: my-skill
description: Объясните, когда этот навык должен срабатывать, а когда — нет.
---
Codex выполнит задачу, следуя приведённым ниже инструкциям навыка.
Codex автоматически обнаруживает изменения в файлах навыков. Если навык не вступает в силу сразу после обновления, перезапустите Codex.
Инструкции по настройке
Расположение хранилища навыков
Codex читает навыки из четырёх областей: уровень репозитория, уровень пользователя, уровень администратора и уровень системы.
Для уровня репозитория Codex сканирует вверх от текущей рабочей директории до корня репозитория в поисках.agents/skillsкаталога.
Если два навыка имеют одинаковоеname, Codex не объединяет их; оба появятся в селекторе навыков.
| Область действия | Путь хранения | Сценарий применения |
|---|---|---|
| REPO | $CWD/.agents/skills | Навыки в текущем рабочем каталоге, подходящие для навыков, общих для команды, для конкретного модуля или микросервиса |
| REPO | $CWD/../.agents/skills | Навыки в родительских каталогах, подходящие для общих областей во вложенных структурах каталогов |
| REPO | $REPO_ROOT/.agents/skills | Навыки в корне репозитория, подходящие для базовых навыков, общих для всех подкаталогов всего репозитория |
| USER | $HOME/.agents/skills | Личный набор навыков пользователя, подходящий для навыков, которые пользователь может использовать в любом репозитории |
| ADMIN | /etc/codex/skills | Общие навыки на уровне машины или контейнера, подходящие для скриптов SDK, автоматизации и стандартных навыков администратора |
| СИСТЕМА | Поставляется OpenAI по умолчанию | Встроенные навыки для широкой аудитории, такие как skill-creator и навыки plan, доступны всем пользователям сразу после запуска Codex |
Codex поддерживает символические ссылки для каталогов навыков и следует цели символической ссылки при сканировании.
Указанный выше путь применяется для локальной разработки и обнаружения. Если вам нужно распространять навыки пользователям за пределами одного репозитория или упаковывать их вместе с интеграцией приложения, используйте механизм Plugins.
Включение и отключение навыков
В~/.codex/config.tomlВы можете отключить навык, не удаляя файлы, с помощью[[skills.config]]параметра конфигурации:
Пример
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
После изменения файла конфигурации необходимо перезапустить Codex, чтобы изменения вступили в силу.
Необязательная настройка метаданных
Вagents/openai.yamlможно настроить метаданные интерфейса, политики вызова и объявления зависимостей инструментов для навыков:
Пример
# Конфигурация интерфейса: управляет отображением навыка в Codex App
interface:
display_name: "Отображаемое пользователю имя"
short_description: "Краткое описание для пользователя"
icon_small: "./assets/small-logo.svg"
icon_large: "./assets/large-logo.png"
brand_color: "#3B82F6"
default_prompt: "Необязательный вспомогательный промпт для использования с навыком"
# Конфигурация политики: управляет поведением при вызове навыка"
policy:
allow_implicit_invocation: false # Установите false, чтобы отключить неявное сопоставление
# Конфигурация зависимостей: объявляет инструменты, требуемые навыком
dependencies:
tools:
- type: "mcp"
value: "openaiDeveloperDocs" # Имя MCP-сервера
description: "MCP-сервер документации OpenAI"
transport: "streamable_http" # Транспортный протокол
url: "https://developers.openai.com/mcp" # Адрес сервиса MCP
allow_implicit_invocationЗначение по умолчанию дляtrue. Если установитьfalse, Codex не будет неявно вызывать навык на основе пользовательских запросов, но явный$skillвызов по-прежнему работает.
| Элемент конфигурации | Type | Значение по умолчанию | Описание |
|---|---|---|---|
| interface.display_name | String | Пусто | Название, отображаемое в Codex App |
| interface.short_description | String | Пусто | Краткое описание, отображаемое в Codex App |
| interface.icon_small | Путь | Пусто | Путь к маленькому значку (формат SVG) |
| interface.icon_large | Путь | Пусто | Путь к большому значку (формат PNG) |
| interface.brand_color | Значение цвета | Пусто | Фирменный цвет, используемый для отображения в интерфейсе |
| interface.default_prompt | String | Пусто | Периферийный промпт по умолчанию, используемый при использовании этого навыка |
| policy.allow_implicit_invocation | Boolean | истина | Разрешено ли Codex неявно сопоставлять и вызывать навык |
| dependencies.tools | Массив | Пусто | Объявляет инструменты MCP, от которых зависит навык; каждый элемент должен указывать type, value, description и т. д. |
Распространение и установка навыков
Распространение навыков через плагины
Папка навыка напрямую подходит для локального создания и рабочих процессов в пределах репозитория.
Если вам нужно распространять переиспользуемые навыки, объединять несколько навыков вместе или публиковать навыки вместе с интеграцией приложения, их следует упаковать какплагин。
Плагин может содержать один или несколько навыков и, опционально, включать сопоставления приложений, конфигурации серверов MCP и презентационные ресурсы.
Установка рекомендуемых навыков
Вы можете использовать$skill-installer, чтобы установить отобранные навыки помимо встроенных в локальную среду Codex.
Например, установите$linearнавык:
Пример
$skill-installer linear
Вы также можете загружать навыки из других репозиториев с помощью skill-installer.
Codex автоматически обнаруживает недавно установленные навыки. Если они не появляются сразу, перезапустите Codex.
skill-installer подходит для локальной настройки и экспериментов. Чтобы распространять собственные навыки для повторного использования, предпочитайте механизм Plugins.
Лучшие практики
| Принцип | Описание | Сценарий применения |
|---|---|---|
| Один навык выполняет одну задачу | Сохраняйте фокус каждого навыка на одной ответственности; избегайте загрузки навыка со слишком большим количеством несвязанных задач | Все навыки должны следовать |
| Инструкции важнее скриптов | Если процесс можно описать с помощью инструкций, не пишите скрипт, если только не требуется детерминированное поведение или вызов внешних инструментов | Режим чистых инструкций рекомендуется для большинства сценариев |
| Используйте шаблоны повелительных предложений | Пишите шаги повелительными предложениями, чётко указывая входные и выходные данные каждого шага | При написании инструкций SKILL.md |
| Проверьте эффективность сопоставления description | Используйте реальные промпты, чтобы проверить, правильно ли срабатывает навык, обеспечивая точность description | После написания навыка |
| Необходимые ключевые триггерные слова | Поместите ключевые сценарии использования и триггерные слова в начало description, чтобы обеспечить сопоставление даже после усечения. | Когда возможно усечение description |
Часто задаваемые вопросы
Обновления навыка не вступают в силу?
Codex автоматически обнаруживает изменения в файлах навыка.
Если навык не появляется в списке после обновления, перезапустите Codex.
Что произойдет, если два навыка имеют одинаковое имя?
Codex не объединяет навыки с одинаковым именем; оба будут отображаться в селекторе навыков.
Рекомендуется избегать использования одного и того же имени навыка в разных областях видимости, чтобы не возникало путаницы.
Что делать, если неявное сопоставление неточно?
Сначала проверьтеdescription, ясно ли описаны сценарии использования и границы навыка.
Поместите основные слова-триггеры в начало и не допускайте, чтобы ключевая информация оказывалась во второй половине описания.
Если неявное сопоставление не требуется, вы можетеagents/openai.yamlвallow_implicit_invocationустановить вfalse。
Когда использовать Skills, а когда использовать Plugins?
Skills — это формат создания, подходящий для локальной разработки и совместного использования командой внутри репозитория.
Когда вам нужно распространять навыки другим разработчикам, упаковывать несколько навыков или выпускать их вместе с интеграцией в приложение, используйте формат Plugins.
Как обрабатывать усеченный начальный список навыков?
Упростите описание каждого навыка, чтобы оно было кратким и точным.
Убедитесь, что основные слова-триггеры находятся в самом начале описания, чтобы сопоставление работало корректно даже при сокращении.
Для навыков, которые обычно не используются в текущей задаче, рассмотрите возможность временного отключения.
Другие расширения