OpenAI Skills: повторювані процедури в Codex, ChatGPT та API

Коли команда регулярно виконує схожу роботу, її кроки можна зберегти у Skill — пакеті інструкцій і, за потреби, довідок, шаблонів та скриптів. Але наявність Skill не означає, що кожен продукт його знайде, викличе, зможе виконати потрібну дію або підтвердить результат.

У цій главі розглянуто задокументовану поведінку Skills у продуктах OpenAI станом на 26 вересня 2026 року. Загальну модель Skill, правила тригера й ризики сторонніх пакетів пояснює глава 31; постійні правила репозиторію та відмінність між інструкцією і дозволом — глава 36. Тут зосередимося на відмінностях між поверхнями OpenAI та способах підключення Skill до API.

37.1. П’ять рівнів, які легко змішати

У розмовах про агентів легко змішати модель, продукт, поверхню, середовище виконання та сам Skill. Ці п’ять рівнів пов'язані, але відповідають на різні запитання.

Модель обробляє контекст і формує відповідь або запит до інструмента. Продукт — це Codex, ChatGPT або інший сервіс, який надає людям конкретний робочий процес. Поверхня — інтерфейс, у якому людина працює: наприклад, Codex у терміналі, його розширення для середовища розробки або ChatGPT на вебсайті. Runtime, або середовище виконання, з'єднує модель із файлами, оболонкою команд (shell), інструментами, обмеженнями й правилами доступу. Нарешті, Skill — це опис повторюваного робочого процесу, який модель може застосувати в такому середовищі.

API (Application Programming Interface — програмний інтерфейс) дає застосунку спосіб звертатися до сервісу через визначений контракт. OpenAI API та бібліотека SDK (Software Development Kit — комплект засобів розробки) — не той самий локальний Codex, запущений у терміналі: розробник передає файли, інструменти й налаштування окремо. Інструкції Skill не переносять автоматично файлову систему, інструменти, автентифікацію чи дозволи з одного середовища в інше.

Skill також не замінює інші частини розробки:

Механізм	На яке запитання відповідає	Межа
AGENTS.md	Які сталі правила діють для цієї роботи в репозиторії?	Не є процедурою, яку потрібно підвантажувати лише для вузького типу задачі.
Інструкція до поточної задачі (task prompt)	Що треба зробити саме зараз?	Описує конкретне завдання, а не повторюваний процес для багатьох завдань.
Skill	Як виконувати повторюваний робочий процес і за яких умов?	Не створює відсутній доступ до файлів чи зовнішніх систем.
Інструмент або інтеграція (connector)	Яку дію чи запит середовище виконання технічно може виконати?	Наявність інструмента не визначає, коли він доречний і як перевірити результат.
Subagent	Яку частину роботи можна передати окремому агенту?	Це спосіб організації виконання, а не формат інструкцій або джерело дозволів.

Наприклад, Skill може наказувати спершу прочитати вимогу в Jira, потім зіставити її з кодом і підготувати PR (Pull Request — запит на включення змін). Для цього середовище має реально надати читання Jira, доступ до коду й механізм створення PR. Якщо конектора немає, Skill не може його вигадати.

37.2. Одна назва — кілька робочих поверхонь

Поточна документація OpenAI називає спільний формат Agent Skills і описує його використання в Codex, ChatGPT та API. Вона окремо перелічує поверхні, де доступні самостійні Skills і плагіни. Це список, опублікований у документації на дату перевірки; він не є обіцянкою однакової доступності в кожному тарифі, робочому просторі чи клієнті. Політика організації та налаштування конкретного продукту можуть впливати на доступ.

Поверхня або канал доставки	Як Skill доходить до неї	Як його можна вибрати	Де відбувається робота
Codex CLI (Command-Line Interface — інтерфейс командного рядка) та IDE (Integrated Development Environment — інтегроване середовище розробки)	Зазвичай це локальна директорія Skill у репозиторії або іншому підтримуваному каталозі	Явний вибір через <code>$назва</code> чи меню <code>/skills</code>; також можливий вибір за описом	У runtime Codex, з тими файлами, оболонкою команд та інструментами, які налаштовані й дозволені в цій сесії
ChatGPT desktop app	Окремі Skills можна створювати й переглядати в настільному застосунку; Skills у плагінах також доступні в режимах Chat і Work	Явний вибір через <code>@</code>; неявний вибір залежить від опису й налаштувань	Дії виконують можливості, доступні цьому робочому простору. Skill не додає відсутню інтеграцію
ChatGPT у вебі й на мобільному пристрої	У документації перелічено Skills, упаковані в плагіни	Через плагін і його доступність у конкретному workspace	Поява Skill у каталозі не означає наявності кожного потрібного доступу
Codex у ChatGPT desktop app або CLI через плагін	Skills можуть бути частиною плагіна; окремі локальні Skills доступні у CLI та IDE extension	Залежить від установленого плагіна й середовища Codex	Плагін розповсюджує процедуру та, за потреби, налаштування інтеграції; фактичні права визначає середовище виконання
Responses API із hosted shell (керованим середовищем команд)	Завантажений Skill можна долучити за ідентифікатором і версією або передати ZIP-пакунок під час створення контейнера	Після монтування модель може вибрати Skill; явна вказівка в запиті робить намір зрозумілішим, але не гарантує правильне виконання. Документація API	У налаштованому OpenAI середовищі команд та його контейнері
Responses API із local shell (локальним середовищем команд)	Запит містить локальні ім'я, опис і шлях до директорії Skill; вкладення <code>skill_reference</code> для цього режиму не підтримується	Модель бачить метадані й може прочитати інструкцію за вказаним шляхом. Документація API	У локальному середовищі, яке контролює розробник запиту
Agents API	Директорії з Skills уже мають існувати в ізольованому середовищі виконання (sandbox); запит реєструє батьківські каталоги	Середовище знаходить SKILL.md і додає назви та описи до контексту; модель може прочитати обраний Skill. Документація Agents API	У sandbox, конфігурацію якого визначає застосунок
Плагін	Спосіб зібрати Skills і необов'язкові інтеграції в одному пакунку	Залежить від каталогу й поверхні	Skill описує процедуру; інтеграція надає операції й дані. Дозвіл на дію задає продукт або середовище виконання

OpenAI описує плагін як спосіб розповсюджувати один чи кілька Skills і, за потреби, налаштування інтеграцій в одному пакунку. MCP (Model Context Protocol — протокол контексту моделі) може надати ці інтеграції, але сам сервер MCP не є процедурою роботи. Документація перелічує окремі Skills для ChatGPT desktop app, Codex CLI та IDE extension; Skills у плагінах також доступні в ChatGPT web, desktop і mobile, а в Codex — через ChatGPT desktop app та CLI. Це перелік описаних поверхонь, не обіцянка однакової доступності на всіх тарифах і в усіх робочих просторах. Деталі наведено в посібнику зі створення Skills та документації про Skills у плагінах.

Опис шляху в документації не гарантує, що кожна версія застосунку реалізує виявлення Skills без помилок. Наприклад, у відкритому issue #40458 користувач повідомив, що Codex для Windows версії 26.818.2441.0 не показував репозиторні Skills з документованого каталогу, хоча автор перевірив формат файлів, корінь репозиторію та довіру до проєкту. Це звіт про одну конкретну версію й конфігурацію, а не доказ, що всі Windows-застосунки мають ту саму проблему. Практичний висновок: після встановлення перевіряйте, чи потрібний Skill справді з'явився на тій поверхні, де команда працюватиме.

Таблиця відповідає на запитання «де це можливо», але ще не пояснює, що саме потрапляє в контекст і коли виконуються файли. Для цього розгляньмо пакет.

37.3. Пакет Skill і метадані OpenAI

У мінімальному Skill є директорія з файлом <code>SKILL.md</code>. На початку файла стоять метадані, а далі — звичайний Markdown-текст із процедурою. Для цього формату потрібні поля <code>name</code> та <code>description</code>. Відкрита специфікація Agent Skills додає правила: ім'я має містити від 1 до 64 малих латинських літер, цифр і дефісів, не починатися й не закінчуватися дефісом, не містити повторних дефісів та збігатися з назвою директорії. Опис обмежено 1024 символами; він має повідомляти, що робить Skill і коли його застосовувати. Це правила формату, а не гарантія однакової поведінки всіх продуктів Agent Skills Specification.

Невеликий вигаданий приклад:

---
name: jira-pr-preflight
description: Підготувати реалізацію Jira-задачі та чернетковий PR. Використовувати для задач, які явно просять реалізувати в репозиторії; не використовувати для пояснень концепцій, перегляду статусу без змін або підготовки релізу.
---

Спершу прочитай Jira-задачу, її критерії та правила репозиторію.
Якщо Jira або GitHub-інструмента немає, повідом про це й зупинися
перед дією, яку неможливо виконати чи підтвердити.
Після змін покажи перелік перевірених критеріїв і доказів.
Створи чернетковий PR лише коли доступний авторизований механізм.
Не зливай PR і не публікуй реліз.

Директорія може додатково мати <code>references/</code> з довідками для читання, <code>scripts/</code> з виконуваним кодом і <code>assets/</code> із шаблонами чи іншими файлами. Це не взаємозамінні ресурси:

• посилання на reference означає, що його слід прочитати за конкретної умови;
• команда запуску скрипта означає виконання коду й можливі побічні ефекти;
• asset може бути шаблоном або даними, але сам по собі не є командою;
• наявність файла в директорії не доводить, що runtime його знайшов, прочитав чи виконав.

Перед запуском скрипта треба зрозуміти шлях від кореня Skill, вхідні та вихідні файли, версію runtime, зовнішні залежності, доступ до мережі й очікувані побічні ефекти. Читання <code>references/</code> теж може бути ризиковим, якщо звідти до контексту потрапляють недовірені інструкції, але читання файла саме по собі не є запуском shell-команди.

OpenAI також документує необов'язковий файл <code>agents/openai.yaml</code>. Він використовує YAML (YAML Ain't Markup Language — «YAML — це не мова розмітки», формат структурованих даних) і може задавати назву й короткий опис для інтерфейсу, налаштовувати політику неявного виклику та декларувати залежності від інструментів. Наприклад, <code>allow_implicit_invocation: false</code> у політики Codex вимикає вибір Skill за описом, залишаючи явний виклик. Це файл адаптації до OpenAI, а не заміна <code>SKILL.md</code>. Опис залежності від інструмента теж не авторизує виклик і не встановлює connector самостійно. Ці поля можуть змінитися; актуальні описи наведені в офіційній документації зі створення Skills.

Додаткові метадані мають бути корисними власному хосту. Не додавайте поле лише тому, що інша платформа його розуміє. Специфікація називає, наприклад, <code>allowed-tools</code> експериментальним і прямо застерігає, що підтримка залежить від реалізації. Один і той самий файл може бути синтаксично прийнятним у кількох продуктах, але поле, яке керує поведінкою Claude Code, не стає через це правилом Codex.

37.4. Від опису до виклику

Codex читає назву й опис Skills під час пошуку кандидата. Повний текст <code>SKILL.md</code> додається, коли Skill обрано; інші довідки можна завантажувати лише тоді, коли процедура на них посилається. Це прогресивне завантаження: спершу легкий покажчик, потім докладна інструкція для конкретної роботи.

Поточний посібник Codex перелічує локальні джерела: репозиторні каталоги <code>.agents/skills</code> від поточної робочої директорії вгору до кореня репозиторію, користувацький <code>$HOME/.agents/skills</code>, адміністративний <code>/etc/codex/skills</code> і вбудовані системні Skills. Для локального каталогу у вкладеній папці Codex може знайти Skills цієї папки та батьків до кореня репозиторію. Сторінка також каже, що Codex підтримує символічні посилання і не об'єднує Skills з однаковим ім'ям. Це документована поведінка; наведений вище повідомлення про проблему в настільному застосунку Windows показує, чому перевірку discovery слід робити на фактичній поверхні й версії. Джерело: поточний посібник OpenAI.

Тут є практичний ресурсний ліміт. У поточній документації Codex первинний список Skills займає до 2% вікна контексту моделі або 8000 символів, якщо розмір вікна невідомий. Спершу Codex скорочує описи; якщо Skills багато, частина може не потрапити до початкового списку й система може показати попередження. Цей ліміт стосується списку метаданих, а не повного тексту обраного Skill. Тому довжелезний опис (description) не робить тригер точнішим — він може приховати частину інших описів і розмити область самого Skill.

Явний виклик корисний, коли людина вже знає потрібну процедуру. У ChatGPT це може бути вибір через <code>@</code>; в Codex CLI чи IDE — вибір у меню <code>/skills</code> або посилання на Skill через <code>$назва</code>. Неявний виклик зручний, коли завдання природно збігається з описом, але залишається рішенням моделі. У Responses API документація теж каже, що змонтований Skill модель може використати сама, а явна фраза на кшталт «використай Skill X» робить намір запиту виразнішим. Жоден із цих варіантів не доводить, що процедура завершилася правильно.

Опис має допомагати відрізнити близькі наміри. Для кожного Skill корисно визначити позитивні приклади, де він справді потрібен, і негативні приклади, схожі за словами, але інші за роботою. Якщо два Skills мають однакове ім'я, Codex їх не об'єднує. Це не «дві половини одного пакета»: користувач може побачити обидва варіанти, а автоматичний вибір стане менш передбачуваним. Розділяйте область дії або явно задавайте унікальні імена.

Коли невдалий автоматичний вибір може змінити зовнішню систему, текстового звуження опису може бути недостатньо. Для Codex вимкніть неявний виклик через підтримувані метадані, залиште процедуру доступною явним викликом і перевіряйте дію правами runtime. Опис керує маршрутизацією до інструкції, а не доступом до кнопки «опублікувати».

37.5. Skill через OpenAI API

У прикладах документації API спосіб передати Skill залежить від типу shell-середовища.

Для hosted shell документація Responses API показує два способи: послатися на завантажений Skill через <code>skill_id</code> і, за потреби, <code>version</code>, або під час створення контейнера передати його ZIP-пакунок як inline Skill. У другому варіанті запит містить назву, опис і ZIP-вміст у Base64; це дає змогу використати Skill без попереднього створення його версії у сховищі. Для local shell документація натомість показує <code>name</code>, <code>description</code> і <code>path</code> до директорії, доступної середовищу, і прямо зазначає, що вкладення <code>skill_reference</code> там не підтримується. Це три описані способи подати ресурси; не переносіть формат одного середовища в інше документація OpenAI Skills API.

У Agents API Skills виявляються через <code>environment.capability_directories</code>. Каталоги мають бути абсолютними унікальними шляхами всередині наявного ізольованого середовища (sandbox), уже існувати й не містити сегментів <code>.</code> або <code>..</code>. Сесія може зареєструвати до 32 таких каталогів. Після запуску середовище шукає в них <code>SKILL.md</code>, додає описи в контекст, а модель може вибрати релевантну інструкцію. Це ще раз показує: API не використовує локальне виявлення Codex автоматично. Вимоги до каталогів і ліміти описано в документації Agents API.

Завантажений Skill можна версіювати. Документація API описує <code>default_version</code>, <code>latest_version</code> і явне поле версії у посиланні. Для відтворюваної процедури краще зафіксувати конкретну версію, а не покладатися на «найновішу»: після оновлення поведінка може змінитися, хоча назва Skill залишилася тією самою. У завантаженому ZIP-пакунку має бути рівно один файл <code>SKILL.md</code> (назва зіставляється без урахування регістру); на дату перевірки офіційна документація обмежує ZIP 50 мегабайтами, версію — 500 файлами, а розпакований вміст — 25 мегабайтами. Це продуктові ліміти, які можуть змінитися; їх наведено в розділі перевірки пакетів Skills.

Важливо не плутати локальне середовище в актуальному shell tool із застарілим окремим інструментом <code>local_shell</code>. Документація Skills API показує передачу Skills до локального shell-середовища як <code>environment.type: "local"</code>; окремий посібник local shell радить для нових інтеграцій використовувати shell tool. Для Responses API shell tools метадані Skill додаються до user prompt, а не system prompt; це уточнення описує Responses API shell tools і не поширюється автоматично на Agents API. Ці API-конкретні деталі та рекомендації можуть змінитися.

Не плутайте локальне середовище в новому shell tool із застарілим окремим інструментом <code>local_shell</code>: Skills API показує передачу Skills до локального shell-середовища як <code>environment.type: "local"</code>, а посібник local shell радить для нових інтеграцій використовувати shell tool. Для Responses API shell tools документація уточнює, що інструкції Skills додаються до user prompt, а не system prompt; це опис shell tools і не поширюється автоматично на Agents API. Сам API-виклик може повернути текст, інструментальну подію або артефакт у sandbox; він не створює PR чи зміну в іншому сервісі без окремого інструмента та коду, який передає результат. SDK полегшує формування запиту до API, але не робить файлові шляхи локального процесу видимими віддаленому середовищу й не прибирає потреби налаштувати інструменти. Hosted shell, local shell і Agents API потребують різної підготовки файлів та середовища; документація не описує це як один універсальний виклик Skills OpenAI Skills API.

37.6. Skill не є дозволом

Якщо текст Skill каже «прочитай Jira», а середовище не має під'єднаної інтеграції Jira, модель може лише пояснити цю межу. Якщо текст каже «створи pull request», але немає авторизованого засобу запису в GitHub, сама фраза не надає такого доступу. Результат залежить від можливостей продукту й середовища виконання, облікових даних інтеграції, політик організації та наслідків дії.

Це стосується й скриптів. Скрипт із <code>scripts/</code> може читати файли, надсилати мережеві запити чи змінювати дані — але лише якщо середовище надало йому такі можливості. У свою чергу, наявність мережевого дозволу не робить будь-який мережевий виклик прийнятним. OpenAI окремо попереджає, що Skills в Responses API можуть містити prompt injection, тобто інструкції, які намагаються вплинути на вибір інструментів і винести дані назовні. Документація вимагає перевіряти Skill як потенційно недовірені інструкції та код, особливо коли до його роботи підключено мережу. Тому перевіряють походження, історію змін, код, залежності, мережеві цілі, доступ до секретів і sandbox — до того, як надавати пакету робоче середовище. Ці рекомендації наведені в розділі Risks and safety документації API.

Не розміщуйте секрет у тексті Skill або прикладах. Довідка може описати, де очікується секретний параметр, не розкриваючи його значення; інструмент має використовувати керований секрет із належним обмеженням доступу. Якщо зовнішня дія має людський ризик — наприклад, merge, платіж, видалення клієнтських даних або deploy — процедура повинна зупинитися перед нею, якщо немає явного дозволу й зовнішнього бар'єра, який перевіряє його.

37.7. Підтримка та оцінювання

Skill змінюється разом із продуктом, репозиторієм і підключеними інструментами. Під час рев'ю оновлення перевіряють не лише формулювання, а й те, чи залишилися правильними шляхи до файлів, назви tools, версії runtime, формат входів, вихідні докази та стоп-умови. Якщо посилання веде на змінний приклад у GitHub, зафіксуйте commit; якщо Skill завантажено у Responses API — конкретну версію. Версію плагіна не слід плутати з версією кожного Skill усередині нього.

Перевірка має охоплювати щонайменше три незалежні результати:

1. Виявлення: чи знайшло середовище виконання Skill і чи був він доступний у потрібній сесії?
2. Вибір і виконання: чи викликався він на призначених запитах, не перехоплював чужі й чи модель виконала потрібні кроки?
3. Результат і права: чи є потрібні докази у виході, чи позначені прогалини, і чи кожна дія залишилася в дозволених межах?

Порівняйте прямі й перефразовані позитивні запити, схожі негативні запити, граничний випадок з неповними даними та спробу зовнішньої дії без потрібного дозволу. Хибне спрацювання — процедура почалася там, де вона не потрібна; хибний пропуск — вона не почалася там, де була б корисна. Відстежуйте обидва, а не лише частку успішно завершених запусків.

Реальний, але не універсальний сигнал про ризик надлишкових Skills описав Eric Provencher в інженерному блозі OpenAI 11 вересня 2026 року: довгі чи суперечливі описи можуть ускладнити вибір, а поступове завантаження допомагає не тримати нерелевантні інструкції постійно в контексті. Автор наводить спостереження зі своєї практики роботи з Codex і GPT-6 Astra; GPT — скорочення від Generative Pre-trained Transformer («генеративний попередньо навчений трансформер»). Це не гарантія поведінки кожної моделі. Поточна документація Codex незалежно підтверджує механізм скорочення та пропуску описів, але вибір конкретного Skill слід перевіряти на потрібній поверхні й моделі. Набори позитивних, негативних і межових запитів описані в главі 31.9; детальні методи оцінювання агентів — у главі 69.

37.8. Повний приклад: задача Jira завершується чернетковим PR

Ситуація. Невелика команда отримує Jira-задачу «Додати експорт щомісячного рахунку». Розробник часто повторює той самий початок роботи: прочитати критерії, знайти відповідні компоненти, внести зміну, виконати доступні перевірки, створити pull request і пояснити, що саме підтверджено. Потрібно зменшити пропущені кроки, не перетворюючи Skill на універсального агента релізів.

Рішення. Умовний пакет з прикладу вище має вузький опис: лише реалізація Jira-задачі в репозиторії. Інструкція визначає джерела істини: Jira — для вимог, правила репозиторію — для локальних домовленостей, файли коду — для поточної поведінки, а результати перевірок — як доказ. Процедура читає критерії приймання, позначає неоднозначність до редагування коду, обмежує перелік змінених файлів, реалізує мінімальну зміну, запускає лише доступні й доречні перевірки та збирає їхні фактичні результати. Потім вона створює чернетковий PR через доступний авторизований засіб запису в GitHub. У відповідь включає посилання на Jira і PR, змінені файли, карту «критерій → доказ», що не перевірялося й чому. Процедура не зливає PR у цільову гілку (merge), не розгортає зміни в production, не видає відсутні результати безперервної інтеграції (CI, Continuous Integration) за успішні та зупиняється, якщо конектора Jira чи GitHub немає.

Спостережуваний результат у змодельованому прикладі. Коли процедура справді виконається, її звіт може показати: PR містить зміну одного сервісу й тест експорту; форматування пройшло; перевірка CI недоступна й лишилася неперевіреною; чернетковий PR відкритий для перегляду, злиття не виконано. Це приклад очікуваного звіту, а не перевірка, виконана під час написання глави. Рев'юер зможе звірити твердження з файлами та результатом команди, а не покладатися на фразу «усе готово».

Чому це підходить. Skill зберігає повторювану процедуру й очікуваний формат доказів. Конектор Jira, оболонка команд або засіб GitHub виконують окремі операції. Користувач може передати лише цю Jira-задачу, а процедура все одно обмежує область одним репозиторієм і зупиняється перед злиттям.

Коли не підходить. Якщо експорт зачіпає бухгалтерські правила, персональні дані або потребує незворотної міграції, звичайний Skill для реалізації може не мати достатніх передумов. Потрібні окреме рішення власника продукту, перевірка політик даних і спеціаліст із фінансової логіки. Якщо середовище має лише читання репозиторію, Skill не може створити PR; він може повернути план і доказ того, де саме зупинився.

37.9. Повний приклад: широкий тригер забирає загальне запитання

Ситуація. У навчальному сценарії Skill для перевірки змін у коді має опис: «Допомагає з розробкою, GitHub, кодом, релізами та всіма питаннями про проєкт». Людина запитує: «Поясни, навіщо перед злиттям об'єднувати кілька комітів». Модель помилково обирає процедуру рев'ю PR, шукає змінені файли, не знаходить їх і просить надати репозиторій. Skill активувався на запит про поняття, хоча перевірки конкретних змін не просили.

Рішення. Автор скорочує опис і називає потрібну роботу, її вхід та межі:

description: Перевіряти конкретний pull request за критеріями пов'язаної задачі, порівнюючи опис, зміни й доступні докази CI. Використовувати, коли прямо просять переглянути PR; не використовувати для загальних пояснень Git, створення коду, написання PR-опису чи запуску релізу.

Після цього автор перевіряє перефразування: «Перевір PR 184 за задачею A1M-123» має бути позитивним прикладом; «Що означає злиття комітів?» — негативним; «Порівняй ці зміни з попередньою версією» — граничним. Останнє запитання може просити аналіз конкретних змін, але це ще не обов'язково повна перевірка за критеріями. Якщо Skill має викликатися лише явно, автор також вимикає неявний виклик у підтримуваних метаданих Codex і залишає <code>$pr-review</code> для ручного запуску.

Очікуваний результат перевірки. Загальне запитання про об'єднання комітів не має обирати Skill, а запит із конкретним PR — приводити до перевірки критеріїв і доказів. Запит про різницю між способами роботи з гілками залишається граничним, тому автор додає його до набору й вирішує, чи належить він цьому Skill, іншій процедурі або звичайній відповіді. Це очікування, а не виміряний результат; його перевіряють на цільовій моделі й поверхні після зміни опису.

Чому це підходить. Опис є маршрутизувальним сигналом, не повним контрактом. Конкретний об'єкт роботи й тип запиту звужують область краще, ніж перелік великих тем. Негативні приклади показують, з чим Skill не слід плутати.

Коли не підходить. Якщо продукт не дає керувати неявним викликом, опис зменшить, але не виключить хибні вибори. Якщо помилковий запуск здатен додати коментарі чи змінити статус, потрібна окрема перевірка прав і підтвердження на рівні інструмента. Надійність вимірюють набором запитів на цільовій поверхні, а не тільки читанням нової description.

37.10. Повний приклад: Skill Claude Code адаптують до Codex

Ситуація. Команда бере Skill із Claude Code, який після прямого виклику <code>/pr-summary</code> читає змінені файли, запускає команди GitHub CLI та повертає короткий звіт. У його блоці метаданих на початку файла є <code>disable-model-invocation</code>, <code>allowed-tools</code> і <code>context: fork</code>; тіло використовує підстановку shell-команди та змінну шляху до директорії Skill. Команда просто копіює каталог у Codex і очікує, що ті самі перемикачі обмежать активацію та дадуть команді права.

Проблема. Claude Code визначає власне значення цих полів: <code>disable-model-invocation</code> прибирає автоматичний виклик, <code>allowed-tools</code> може дозволити названі інструменти на час поточного ходу, а <code>context: fork</code> запускає процедуру в окремому контексті субагента Claude Code, який не отримує історію батьківської розмови. У тілі Skill конструкція з префіксом <code>!</code> може заздалегідь виконати shell-команду, а потім підставити її вивід у текст інструкції; Claude Code також підставляє <code>${CLAUDE_SKILL_DIR}</code> у текст і правила Bash. Це механізми Claude Code, а не переносимий синтаксис Skill. Ці правила не є властивістю спільного формату <code>SKILL.md</code> і не переносять ті самі права в Codex. Codex використовує власні шляхи виявлення, файл <code>agents/openai.yaml</code> для метаданих і політики виклику та власні дозволи оболонки команд. Делегування окремому Codex субагенту проєктують окремо (див. главу 38). Навіть коли файл відкрився, підстановка Claude Code або попереднє схвалення команди не перетворюється на дозвіл Codex Claude Code: Skills.

Дія. Автор відділяє повторно використовувану процедуру від налаштувань конкретного середовища. У переносимому <code>SKILL.md</code> лишається суть робочого процесу: як звірити змінені файли з критеріями, як позначити доказ і коли зупинитися. Проєктні правила й приватні ідентифікатори залишаються зовнішнім контекстом. Claude-специфічні поля й динамічні вставки не видаються за спільні налаштування. Для Codex автор додає його підтримувані метадані явного виклику, розташовує пакет у задокументованій директорії, перевіряє фактичну назву інструмента GitHub й адаптує шлях до скрипту відносно кореня Skill. Якщо засіб командного рядка не встановлений або середовище не дозволяє його запуск, інструкція називає цю передумову й не оголошує роботу завершеною.

Очікуваний результат. Після адаптації команда зберігає суть процедури: читання змін, критерії, звіт і стоп-умову. Skill знаходиться за правилами Codex і має викликатися заданим способом; права на інструменти визначає середовище. Перевірочний набір має включати конкретний запит про PR, загальне запитання про Git і сесію без інтеграції з GitHub. Це план перевірки, а не результат запуску; до нього додають фактичні спостереження лише після перевірки в цільовому Codex.

Чому це підходить. Портовано знання процесу, а не внутрішню механіку платформи. Офіційна специфікація Agent Skills дає спільний базовий файл, але Claude Code і Codex мають додаткові й відмінні механізми виклику, шляхи, дозволи та правила виконання. Метадані OpenAI описують налаштування OpenAI; вони не перетворюють ключі лише для Claude Code на команди Codex.

Коли не підходить. Автоматичне перенесення небезпечне, якщо вихідний Skill запускає deployment, змінює production або містить shell-шаблони, які формують команди з тексту задачі. Спершу треба переглянути весь пакет і визначити кожен побічний ефект. Якщо спільного переносимого процесу майже немає, дешевше й безпечніше написати окремий Codex Skill, зберігши лише перевірені критерії та формат результату.

37.11. Практична модель для автора

Під час проєктування OpenAI Skill мисліть не назвою файла, а ланцюжком доказів:

1. Який конкретний повторюваний запит має приводити до цього Skill?
2. Яке джерело істини він читає, і які поля чи дані ще треба перевірити?
3. Яку частину становлять інструкції, довідки, скрипти й зовнішні інструменти?
4. На якій саме поверхні він існує: Codex, ChatGPT, Responses API чи Agents API?
5. Хто має право читати, виконувати код, записувати у зовнішню систему й підтверджувати результат?
6. Які позитивні, негативні та межові приклади доводять, що Skill доречно вибирається й дає корисний вихід?

Якщо для відповіді на будь-яке запитання автор підмінює факти припущенням («файл є — отже його знайшли», «інструмент названо — значить він дозволений», «модель відповіла — значить дію виконано»), процедура не готова. Звірте відповідне середовище виконання, каталог і систему дозволів; за потреби залиште чесну стоп-умову.

Коротко: <code>SKILL.md</code> зберігає робочий процес, а метадані OpenAI адаптують його до деяких функцій Codex і ChatGPT. Для API файли та інструменти треба під'єднати окремим способом. Виявлення Skill, його виклик, читання ресурсів, запуск коду, дозвіл на зовнішню дію й доказ результату — окремі переходи. Перевірка кожного переходу робить повторювану процедуру надійнішою.

Джерела та подальше читання

Мінливі сторінки й репозиторій перевірено 26 вересня 2026 року.

1. OpenAI, Build skills, поточна онлайн-документація; попередня адреса developers.openai.com/codex/skills перенаправляє на цю сторінку. Підтримувані поверхні, структура файлів, виклик і метадані в Codex та ChatGPT; доступ 2026-09-26.
2. OpenAI, Skills — API documentation, поточна онлайн-документація. Hosted-посилання, inline-пакунок, локальний шлях, Agents API, версії, ліміти й ризики; доступ 2026-09-26.
3. OpenAI, Skills — Plugins concepts, поточна онлайн-документація. Роль Skills у робочому процесі та відмінність від інтеграції MCP; доступ 2026-09-26.
4. Agent Skills, Specification, поточна специфікація формату. Обов'язкові <code>name</code> та <code>description</code>, правила імені й опису та обмеження між реалізаціями; доступ 2026-09-26.
5. Anthropic, Extend Claude with skills — Claude Code Docs, поточна онлайн-документація. Використана лише для порівняння метаданих Claude Code та його механізмів виклику й доступу; доступ 2026-09-26.
6. OpenAI, openai/plugins: openai-platform-api-key/SKILL.md, commit <code>1dc195897af4161d039b80d8471ec0a10c9bbc89</code>. Переглянуто як приклад вузької області дії, негативних тригерів, меж безпеки й посилань на references; доступ 2026-09-26.
7. OpenAI, openai/plugins: plugin-eval/evaluate-skill/SKILL.md, той самий commit. Переглянуто як приклад окремої процедури оцінювання Skill; доступ 2026-09-26.
8. OpenAI Codex, Issue #40458: Windows Desktop App does not discover repository-local skills, звіт створено 24 серпня 2026 року для Codex App 26.818.2441.0 у Windows. Використано як одиничне повідомлення про конкретну версію, а не доказ загальної несправності; статус і опис доступу перевірено 2026-09-26.
9. OpenAI, Eric Provencher, Rethinking skills and prompts for GPT-6 Astra, 11 вересня 2026 року. Використано як датоване авторське спостереження про завеликі й суперечливі описи, а не як нормативну вимогу; доступ 2026-09-26.
10. OpenAI, Local shell, поточний посібник із локального shell tool; використано для розмежування його від застарілого <code>local_shell</code>; доступ 2026-09-26.