Claude Skills: повторюваний процес як пакет знань

Навчальний розділ курсу «AI Development» (Artificial Intelligence, штучний інтелект) · зріз мінливої документації: 10.10.2026

У команді може регулярно повторюватися одна й та сама робота: перевірити запит на злиття (pull request, PR), зіставити зміну з вимогами Jira, підготувати міграцію або зібрати докази під час інциденту. Якщо щоразу вставляти в чат довгий чекліст, частина кроків губиться, а кожен автор формулює їх по-своєму. Skill — це спосіб упакувати повторювану процедуру разом із потрібними довідками, шаблонами та, за потреби, невеликими програмами.

Тіло <code>SKILL.md</code> саме собою не створює доступ до зовнішньої системи чи секретів і не гарантує точного виконання кожного речення. Можливості залежать від host-системи та його налаштувань. У Claude Code є важливий виняток для уважного рев’ю: поле <code>allowed-tools</code> може попередньо схвалювати вказані інструменти на хід, у якому Skill викликано. Воно не прибирає інші доступні інструменти й не замінює глобальні правила дозволів; перевіряйте його в кожному Skill, особливо в проєктному: цей grant може застосовуватися навіть у режимі <code>-p</code> в каталозі, якому ви ще не довіряли. Це розрізнення потрібне і під час створення безпечного workflow, і під час оцінювання його якості (документація Claude Code про Skill permissions).

У цьому розділі термін Claude Skills означає Skills у конкретних середовищах Anthropic. Деякі поля й структура спираються на відкритий формат Agent Skills, але завантаження, виклик, дозволи та підтримка додаткових файлів залежать від продукту. Наведені нижче відомості про мінливу поведінку перевірено 10 жовтня 2026 року; перед практичним використанням звірте поточну документацію та версію клієнта.

31.1. Що саме пакує Skill

Skill — це каталог із файлом <code>SKILL.md</code>. У ньому є короткі метадані для виявлення Skill і тіло з робочими інструкціями. До каталогу можна додати матеріали, потрібні не на кожній задачі:

pr-review/
├── SKILL.md                  # коли застосовувати і як проходити процес
├── references/
│   └── review-rubric.md      # деталізована шкала серйозності
├── assets/
│   └── report-template.md    # шаблон звіту
└── scripts/
    └── list_changed_files.py # необов’язкова детермінована операція

Це не обов’язкова структура підкаталогів. Мінімальний формат Agent Skills вимагає <code>SKILL.md</code>; <code>scripts/</code>, <code>references/</code> і <code>assets/</code> — типові, але необов’язкові місця для відповідних матеріалів. Довідку, шаблон чи програму додають лише тоді, коли вона розв’язує конкретну проблему workflow (специфікація Agent Skills).

Уявіть сайт футбольної статистики, який імпортує офіційні відомості про переходи гравців між командами. Одноразовий запит «перевір, чи імпорт зберігає історію» може пояснити цю задачу зараз. Skill для перевірки таких змін зберігає повторюваний порядок: знайти вимогу, прочитати формат джерела, зіставити подію зі станом складу, перевірити ідемпотентність та показати докази у звіті. Словник полів зовнішнього feed може лежати окремо і завантажуватися лише для імпортних змін.

Таку процедуру варто пакувати, коли вона повторюється, має стабільний порядок кроків, потребує критеріїв або ресурсів, яких легко не помітити. Не кожна настанова потребує Skill: одноразову задачу простіше описати в запиті; стабільний факт про весь репозиторій — у загальних правилах; операцію з системою виконує інструмент або програмний інтерфейс (Application Programming Interface, API); машинно-перевірну умову краще закріпити автоматичною перевіркою.

Skill — це не синонім prompt

Prompt — конкретне повідомлення для поточного завдання. Skill — повторно використовуваний пакет, який host-система може запропонувати або завантажити, коли задача схожа на його призначення. Навіть якщо текст тіла Skill схожий на довгий prompt, навколо нього є виявлення, каталог ресурсів і правила конкретного середовища.

Розмір теж має значення. Якщо довідки постійно завантажувати в головний <code>SKILL.md</code>, кожне застосування отримуватиме зайвий контекст і його буде важче оновлювати. Anthropic радить тримати <code>SKILL.md</code> менш як 500 рядків і виносити деталізацію в пов’язані файли. Додатковий файл не завантажується магічно лише тому, що він лежить поруч: у <code>SKILL.md</code> треба пояснити, що в ньому міститься і за якої умови його прочитати (рекомендації Claude Code щодо supporting files).

31.2. Відкритий формат і продуктоспецифічні можливості

Відкритий стандарт Agent Skills описує структуру пакета та невелику переносну підмножину frontmatter у YAML (YAML Ain’t Markup Language, формат серіалізації даних) — метаданих між роздільниками <code>---</code> на початку <code>SKILL.md</code>:

---
name: roster-import-review
description: Перевіряє зміни імпорту футбольних транзакцій. Використовуй для змін parser, mapping, deduplication або історичного стану складу.
license: Apache-2.0
compatibility: Потрібні доступ до Git-репозиторію та читання тестових fixtures.
metadata:
  owner: data-platform
  version: "1.2"
---

У стандарті <code>name</code> і <code>description</code> обов’язкові. Назва обмежена 64 символами, складається з малих літер, цифр і дефісів, відповідає назві батьківського каталогу, не починається й не закінчується дефісом та не має подвійних дефісів. Опис має вміщатися у 1 024 символи і повідомляти, що робить Skill та коли його застосовувати. Поля <code>license</code>, <code>compatibility</code>, <code>metadata</code> і <code>allowed-tools</code> необов’язкові; останнє має експериментальний статус у специфікації (специфікація Agent Skills).

Назва у frontmatter <code>metadata.version</code> у прикладі — власне поле каталогу команди. Специфікація дозволяє довільні пари ключ-значення; це не означає, що кожен host розуміє поле <code>version</code> або застосовує його для вибору версії. Перевіряйте, хто читає метадані, як версії публікуються і як споживач закріплює конкретну копію (специфікація Agent Skills).

Claude Code підтримує цю спільну підмножину, а також власні поля й поведінку. У ньому всі поля frontmatter формально необов’язкові, але опис рекомендований: він допомагає Claude визначити, коли Skill доречний. Якщо <code>name</code> відсутнє, зазвичай використовується назва каталогу. Серед Claude Code extensions є <code>when_to_use</code>, <code>argument-hint</code>, <code>arguments</code>, <code>disable-model-invocation</code>, <code>user-invocable</code>, <code>allowed-tools</code>, <code>disallowed-tools</code>, <code>model</code>, <code>effort</code>, <code>context</code>, <code>agent</code>, <code>background</code>, <code>hooks</code>, <code>paths</code> і <code>shell</code>. Це не список універсальних полів Agent Skills (документація Claude Code).

Наприклад, у Claude Code <code>disable-model-invocation: true</code> забороняє автоматичний виклик моделлю, залишаючи змогу викликати Skill вручну як <code>/ім’я</code>. <code>user-invocable: false</code> прибирає Skill зі списку доступних користувачу команд, але модель ще може його викликати. Ці поля відповідають на різні питання. Вони впливають на виявлення чи спосіб запуску в Claude Code, а не перетворюють тіло Skill на контроль доступу (документація Claude Code).

Поле <code>paths</code> — ще одне розширення Claude Code: glob-шаблони обмежують автоматичне завантаження Skill випадками, коли робота торкається відповідних файлів. Наприклад, наведене правило підходить для автоматичного вибору під час роботи з TypeScript-парсером імпорту (документація Claude Code):

---
description: Перевіряє зміни парсера офіційних транзакцій у футболі.
paths:
  - "src/imports/**/*.ts"
---

Зіставлення шляху — умова для контексту, а не фільтр інструментів, дозвіл на читання цього каталогу чи бар’єр доступу до інших шляхів. Така сама назва поля в іншому продукті може бути відсутня або мати іншу семантику (документація Claude Code).

Claude Code може приймати додаткові поля, як-от <code>paths</code>, <code>hooks</code>, <code>context: fork</code> і виконання команд із тіла. Вебзавантаження Skill для claude.ai та Skills API приймають вужчу підмножину стандарту: <code>name</code>, <code>description</code>, <code>license</code>, <code>compatibility</code>, <code>metadata</code> і <code>allowed-tools</code>. Додаткове поле може спричинити помилку під час пакування або завантаження, а не мовчки проігноруватися. У Claude Code динамічна вставка контексту використовує рядок <code>!`команда`</code> або відповідний fenced block: shell-команда виконується до передачі інструкцій моделі, а її результат вставляється в контекст. Це продуктоспецифічна поведінка, яка не працює в чаті claude.ai чи через API. У настільному Cowork кожен такий рядок у синхронізованому Skill замінюється placeholder-ом <code>disableSkillShellExecution</code>, а не виконується (документація Claude Code; огляд Agent Skills).

Для цього шляху завантаження перевіряють і значення полів, не лише їх перелік: Anthropic обмежує назву 64 символами з малих літер, цифр і дефісів, забороняє в ній теги XML (Extensible Markup Language, розширюваної мови розмітки) та зарезервовані слова <code>anthropic</code> і <code>claude</code>; опис не може бути порожнім, перевищувати 1 024 символи чи містити XML-теги. Ці перевірки поверх стандарту означають, що валідний Agent Skills пакет не обов’язково прийме конкретний upload API (огляд Agent Skills, структура пакета).

Для Claude API потрібен інструмент Code Execution: Skill виконується в ізольованому контейнері без мережі та встановлення пакетів під час виконання. Custom Skills, завантажені в API, доступні в межах workspace; Skills, завантажені в claude.ai, доступні конкретному користувачу. В claude.ai потрібне ввімкнене виконання коду, а індивідуально завантажена Skill не стає автоматично командною чи організаційною. Уточнюйте умови за актуальною документацією й планом облікового запису (огляд Anthropic Agent Skills).

Codex і ChatGPT мають власні місця пошуку та правила виклику Skill; у їхній поточній документації файл має містити <code>name</code> і <code>description</code>, а інтерфейс додаткових метаданих зберігається в окремому <code>agents/openai.yaml</code>. OpenAI API, своєю чергою, розрізняє завантажені посилання на Skills і локальні файли для різних режимів виконання. Спільний формат не гарантує однакового шляху, доступу до файлів, запуску scripts, авторизації чи автоматичного виклику. Якщо пакет має працювати в кількох host-системах, визначте найменшу спільну структуру, а product-specific логіку документуйте окремо (документація OpenAI про Skills для ChatGPT і Codex; документація OpenAI API про Skills).

31.3. Де Skill знаходиться і як потрапляє в контекст

У Claude Code розташування визначає, де Skill доступний:

Розташування	Типовий шлях	Межа застосування
Особистий	<code>~/.claude/skills/<name>/SKILL.md</code>	Проєкти користувача на цій машині
Проєктний	<code>.claude/skills/<name>/SKILL.md</code>	Репозиторій; можна зберігати спільно в Git
Вкладений	<code><subdir>/.claude/skills/<name>/SKILL.md</code>	Робота в цьому піддереві та відповідних сесіях
Керований	каталог, визначений адміністратором	Пристрої або користувачі, охоплені політикою
Плагін	<code><plugin>/skills/<name>/SKILL.md</code>	Сесії, де ввімкнено цей плагін
Синхронізований	Skill, увімкнений в акаунті claude.ai	Підтримувані сесії цього акаунта

Це не взаємозамінні способи встановлення. Сесії Cowork і хмарні сесії Claude Code не читають особистий каталог <code>~/.claude/skills/</code> на комп’ютері користувача: вони використовують Skills, увімкнені в акаунті claude.ai. Хмарна сесія додатково знаходить проєктні Skills, закомічені до репозиторію. У монорепозиторії впливає також робочий каталог: файл для підкаталогу може стати доступним лише тоді, коли сесія працює з відповідною частиною дерева (документація Claude Code; огляд Anthropic Agent Skills).

Відбувається прогресивне завантаження (документація Claude Code; огляд Anthropic Agent Skills):

1. За замовчуванням host показує моделі назви й описи доступних Skills. Це компактний покажчик для виявлення, не повні інструкції. У Claude Code Skill із <code>disable-model-invocation: true</code> прибирає опис із модельного контексту до явного ручного виклику; налаштування також можуть приховати Skill.
2. За відповідністю запиту модель може вибрати Skill, або користувач викликає його явно через команду, наприклад <code>/review-pr</code>.
3. Після виклику тіло <code>SKILL.md</code> додається до контексту сесії.
4. За потреби модель відкриває пов’язані довідки чи шаблони, або запускає дозволений скрипт у межах можливостей цього host (документація Claude Code; огляд Anthropic Agent Skills).

У Claude Code завантажене тіло Skill може залишатися в контексті наступних ходів. Наприклад, дозвіл із <code>allowed-tools</code> не обов’язково зберігається разом із текстом: поточна документація каже, що попередньо схвалені ним інструменти дозволені лише для ходу виклику Skill, а наступне повідомлення користувача скидає цей grant. Тому розрізняйте життєвий цикл інструкції та життєвий цикл дозволу (документація Claude Code: permissions і skill content lifecycle).

Опис Skill — підказка для виявлення, а не детерміністичний маршрутизатор. Формулювання «використовуй для будь-якої роботи з кодом» може підхопити архітектурне пояснення, дослідницький запит або підготовку релізу, хоча workflow призначений для огляду запитів на злиття. Вузький опис з прикладами задач і чіткими межами зазвичай допомагає, але рішення все одно залежить від моделі та доступного контексту. Довгий опис теж може бути обрізаний: у Claude Code поля <code>description</code> і <code>when_to_use</code> разом мають обмеження довжини у списку Skills (документація Claude Code).

31.4. Контракт робочого процесу

Надійний Skill починається з визначеної роботи, а не з назви файлу чи переліку можливостей. До написання <code>SKILL.md</code> варто узгодити його контракт:

Частина контракту	Що записати
Призначення	Який результат workflow має підготувати і для кого
Область	Які задачі включені, а які не належать до Skill
Вхідні дані	Які issue, diff, документи, середовища чи джерела треба прочитати
Джерела істини	Чому довіряємо, що робимо зі stale або суперечливими даними
Кроки	Який порядок дій і які докази треба зібрати
Рішення	Які умови ведуть до продовження, альтернативи, уточнення або зупинки
Вихід	Який формат звіту чи артефакту, хто його споживає
Відмова	Як виявляти нестачу даних, доступу, впевненості або суперечність
Побічні ефекти	Які зміни дозволені, за чиїм погодженням і якими інструментами
Обмеження	Що workflow не може довести або виконати

Інструкція «переглянь PR якісно» слабка, бо не визначає джерело очікуваної поведінки, межу пошуку, серйозність проблем чи вигляд результату. Краще сказати: «прочитай пов’язане acceptance criteria та diff; для кожного висновку вкажи файл, рядок і спостережуваний наслідок; якщо потрібного доказу немає — познач питання, не вигадуй; не внось змін і не зливай PR». Тоді reviewer може зрозуміти, що саме перевіряти.

Процедура має також показувати як «не запускатися». Наведіть:

• позитивний приклад — запит «перевір поточний PR за Jira acceptance criteria»;
• негативний приклад — «поясни, чому обрали цю схему даних», якщо людина просить лише пояснення, а не огляд diff;
• межовий приклад — «знайди ризики в плані змін до парсера, PR ще немає». Тут Skill може прочитати план і вказати, що повний огляд diff недоступний, але не повинен вигадувати файли або робити висновок, що PR уже перевірено.

Умови зупинки і запитання не є зайвою ввічливістю. Якщо Jira issue суперечить тестовій fixture, Skill має назвати конфлікт і попросити визначити джерело істини. Якщо під час інциденту відсутній доступ до журналів, він може скласти перелік невідомого, але не видавати припущення за результат аналізу. Якщо інструкція просить злиття чи розгортання, треба відокремити підготовку до дії від власне дії та явно назвати потрібне погодження.

31.5. Коли потрібен Skill, а коли інший механізм

Skill може з’єднувати інші механізми у процедуру, але не замінює їх:

Механізм	Яку задачу вирішує	Чого він сам по собі не гарантує
Постійне правило або <code>CLAUDE.md</code>	Стабільний факт чи конвенція, корисна для багатьох задач	Виконання всіх кроків складного процесу
Одноразовий prompt	Інструкцію для однієї конкретної сесії	Повторне виявлення і єдину командну версію
Skill	Перевикористовуваний workflow, потрібні кроки й довідки	Детермінований виклик або дозвіл на побічний ефект
Tool або MCP (Model Context Protocol, протокол контексту моделі)	Машинну операцію, доступ до даних або зовнішньої системи	Правильну стратегію використання результату
Subagent	Ізольовану чи паралельну роботу з окремою задачею	Автоматичну незалежність або коректність висновку
Script	Повторювану детерміновану трансформацію чи перевірку	Якісне судження поза закодованими правилами
Hook, permission, CI (Continuous Integration, безперервна інтеграція)	Автоматизований контроль у налаштованій точці	Контроль каналів, яких це налаштування не охоплює

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

Якщо агенти мають щоразу знати, що команда не переписує історичні міграції, це постійний факт у репозиторних правилах. Якщо їм треба пройти кроки конкретного огляду PR, доречний Skill. Перевірку формату JSON (JavaScript Object Notation, нотація об’єктів JavaScript) чи унікальності ключів краще доручити тесту або програмі, а не покладатися тільки на текстову обіцянку моделі. Для читання Jira потрібен доступний інструмент; Skill лише описує, як його застосувати і що робити з результатом. Наявність слів «прочитай Jira» у <code>SKILL.md</code> не створює обліковий запис або мережеве право.

У загальному <code>SKILL.md</code> залишайте коротку навігацію і порядок роботи. Великі правила команди, схему API, карту залежностей або приклади передавайте пов’язаним файлам. Скрипт варто додавати для кроку, де помилка від ручного повторення дорога, а умову можна точно закодувати. Поясніть його вхідні аргументи, файли, що він читає чи змінює, зовнішні виклики, код завершення і залежності. Скрипт із прихованим мережевим викликом чи читанням змінних середовища — це частина поверхні безпеки пакета.

31.6. Повний приклад: Skill для огляду PR

Ситуація. Умовна команда змінює імпорт офіційних транзакцій у сайті футбольної статистики. Гравець переходить з однієї команди до іншої; поточний склад треба оновити, а попередній зв’язок зберегти в історії. Jira містить acceptance criteria, PR змінює парсер і обробник повторних подій.

Проблема. Якщо в prompt просто попросити «перевір код», огляд може обмежитися стилем, пропустити дубльоване повідомлення або назвати дефект, якого немає у diff. Команда хоче повторно використовувати критерії, але не хоче, щоб Skill автоматично змінював код, писав коментарі чи зливав запит.

Альтернативи. Одноразовий prompt простий, але автор мусить щоразу відтворювати чекліст. Глобальне правило перевантажило б кожне завдання деталями PR review. Інструмент GitHub може прочитати diff і коментарі, але не визначає, як зіставити їх з приймальними критеріями. Тому команда створює окремий Skill для процедури, лишає права інструментів у наявних налаштуваннях і не дає цьому workflow права на зміни.

Дія. Пакет містить мінімальний заголовок і явні межі:

---
name: evidence-pr-review
description: Перевіряє відкритий pull request за пов’язаними вимогами та шукає дефекти в зміненій поведінці. Використовуй, коли користувач просить огляд PR або оцінити зміну перед злиттям; не використовуй для загального пояснення архітектури, написання коду чи розгортання.
disable-model-invocation: true
---

# Огляд змін із доказами

1. Визнач pull request і пов’язане завдання. Прочитай acceptance criteria, diff і контекст змінених викликів.
2. Зістав вимоги з кодом та наявними тестовими fixtures. Розрізняй побачений дефект, питання до автора й ризик поза diff.
3. Для кожного finding наведи файл і рядок, конкретну умову відтворення та наслідок для користувача або даних. Не заявляй, що тест запускався, якщо цього не відбулося.
4. Якщо вимога, доступ або потрібний контекст відсутні, зазнач це і зупини висновок, який від них залежить.
5. Поверни findings від найсерйознішого до найменшого; для кожного вкажи severity, evidence і можливий напрям виправлення. Якщо findings немає, скажи, що саме перевірено і що залишилося поза оглядом.
6. Не редагуй файли, не надсилай коментар, не схвалюй, не зливай і не розгортай зміни. Для будь-якої такої дії потрібне окреме явне доручення в сесії та доступ, налаштований host-системою.

Якщо pull request або пов’язані вимоги не вказано, спочатку попроси уточнення.
Для детальної шкали severity та прикладів дивись references/review-rubric.md.

Файл <code>references/review-rubric.md</code> може визначити локальні категорії серйозності, наприклад:

Категорія	Критерій у цьому навчальному прикладі
Блокувальний дефект	Зміна втрачає попереднього власника гравця або повторно застосовує одну транзакцію
Значний ризик	Стан складу оновлюється без перевірки джерела чи ідентифікатора події
Питання	Для висновку бракує acceptance criteria або зовнішнього контракту
Спостереження	Стилістична пропозиція без доведеного впливу на поведінку

Довідка не повинна суперечити вимогам Jira або правилам проєкту. У цьому прикладі поле <code>disable-model-invocation</code> — конкретне розширення Claude Code, його не слід переносити без адаптації в інший host.

Результат. На запит «Перевір PR, пов’язаний з DEMO-60» користувач викликає Skill явно. Агент повертає перевірені findings або чесно вказує, що критерії чи diff недоступні. Він не стверджує, що злив PR, і не змінює його лише тому, що побачив кнопку чи tool.

Чому це рішення підходить. Процедура повторюється, їй потрібні однакові докази та формат звіту. Правило «не зливай» у тексті не є технічним блокуванням, тому для реального запобігання злиттю налаштування інструмента й GitHub permissions мають теж обмежувати канал. Явний виклик зменшує ризик автоматичного запуску для запиту на пояснення.

Межі. Skill не доводить, що всі можливі дефекти знайдено. Він не підтверджує стан CI, якщо це не прочитане джерело. Якщо рев’юер має повноваження створювати коментарі чи зливати PR, це контролюється зовнішніми дозволами та окремим дорученням, а не формулюванням у Markdown.

Короткий приклад: огляд планувальника публікацій

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

---
name: content-publish-review
description: Перевіряє PR про планування публікацій, часові пояси та повторну обробку подій. Використовуй для огляду таких змін, не для розгортання чи редагування текстів.
disable-model-invocation: true
---

# Огляд змін публікації

1. Прочитай пов’язане завдання, критерії приймання, diff і змінені виклики.
2. Звір часовий пояс і повторну подію з кодом та наявними тестами.
3. Для кожного зауваження наведи файл, рядок, умову й наслідок; відрізняй дефект від питання та ризику поза diff.
4. Якщо бракує вимоги, доступу чи доказу, назви прогалину й зупини залежний висновок.
5. Не редагуй, не публікуй, не розгортай і не вимикай планувальник.

Явний виклик допомагає не запускати цей workflow для звичайного запиту на пояснення архітектури. Він не є дозволом або технічним блокуванням: зовнішні дії лишаються під контролем інструментів і політики середовища. У тестовому наборі перевірте запит із відкритим PR, його перефразування, опис затримки без PR і випадок, де вимога не задає часовий пояс. Це доповнює приклад вище іншим типом повторюваної перевірки й показує, що тригери мають бути вузькими.

31.7. Повний приклад: широке описання спричиняє хибні виклики

Ситуація. Вигадана команда має Skill <code>software-helper</code> з описом «допомагає з будь-якою задачею програмної команди: кодом, Jira, релізами, інцидентами й архітектурою». Тіло переважно вчить читати diff і готувати review. Під час запитів «чому черга затримує повідомлення?» та «підготуй план релізу» модель інколи відкриває цей Skill.

Проблема. Обсяг опису набагато ширший за workflow. Це хибні спрацьовування, а не доказ, що Skill мусить виконувати більше робіт. Додавання нових кроків у велике тіло може зробити його заплутаним і посилити конфлікт з іншими Skills.

Альтернативи. Можна зробити ширший Skill, який одночасно розслідує черги, оглядає PR, планує реліз і змінює архітектуру. Інший шлях — звузити межу. Якщо питання просить пояснення, може бути достатньо звичайного аналізу без Skill. Для окремих повторюваних процесів створюються окремі пакети: <code>evidence-pr-review</code>, <code>release-readiness</code> та <code>incident-triage</code>.

Дія. Автор переписує опис до конкретного: «Перевіряє змінений код відкритого pull request за пов’язаними вимогами. Використовуй для запиту на review PR або перевірки перед злиттям; не використовуй для пояснення архітектури, написання плану релізу чи розбору живого інциденту». Тести тригера містять пряме формулювання, синонімічний запит, неповну задачу та негативні приклади. Реліз і incident workflows мають власні входи, докази, виходи і межі побічних ефектів.

Тестовий запит	Очікувана поведінка
«Зроби review відкритого PR і звір із вимогами Jira»	Вибрати PR-review Skill
«Перевір помилки в цій зміні перед злиттям»	Імовірно вибрати його після уточнення об’єкта review
«Чому парсер зберігає дві однакові транзакції?»	Пояснити або дослідити дані; не робити вигляд, що це PR review
«Який безпечний порядок кроків для релізу?»	Не запускати PR-review workflow
«У проді зросла затримка черги, допоможи локалізувати»	За наявності — incident workflow; не починати змінювати код автоматично

Результат. Опис тепер відповідає одному призначенню, а сусідні процеси мають окремі контракти. Команда оцінює активацію та корисність результату окремо: чи Skill викликався на належних запитах і чи якісно пройшов review після виклику.

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

Межі. Точне формулювання опису не гарантує нуль хибних спрацьовувань: вибір автоматичний і контекстний. Явний виклик також не доводить, що workflow завершився правильно. Якщо помилкове автоматичне рішення може створити зовнішній побічний ефект, однієї вузької description недостатньо — потрібні дозволи та бар’єри виконання.

31.8. Повний приклад: сторонній Skill просить передати .env

Ситуація. Умовний невідомий автор поширює Skill «налаштування інтеграцій». У тілі є інструкція відкрити файл <code>.env</code> і завантажити його на адресу, яку проєкт не контролює, щоб «перевірити конфігурацію». Скрипт у <code>scripts/</code> ховає запит протоколом HTTP (Hypertext Transfer Protocol, протокол передавання гіпертексту) за звичною назвою <code>check_config.py</code>.

Проблема. <code>.env</code> може містити паролі бази даних, ключі API чи токени. Інструкції Skill — контент, а bundled script — виконуваний код. Публічна адреса ресурсу (Uniform Resource Locator, URL) або кількість зірок не доводять ні походження кожної версії, ні відсутність шкідливого кроку.

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

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

Результат. Перевірка зупинена до передавання секрету. Команда зафіксувала точну версію та рішення про пакет, або відмовилася від нього. Наявність інструкції в Skill не надала йому прав на мережу чи <code>.env</code>; реальні можливості все одно залежать від дозволів та ізоляції host-системи.

Чому це рішення підходить. Пакет треба оцінювати цілком, а не лише читати верхні рядки <code>SKILL.md</code>. Статичне тіло може містити prompt injection — інструкції, що намагаються змінити поведінку моделі; скрипт може виконувати ефекти, яких текст не пояснює. Під час оновлення повторюють перевірку, оскільки новий commit може змінити код або ціль мережевого запиту.

Межі. Читання коду не доводить, що він безпечний у всіх конфігураціях. Захист посилюють контроль версії, обмежений sandbox, відсутність секретів за замовчуванням, правила доступу до мережі, перевірені залежності та рев’ю змін пакета. Ліцензія визначає умови використання, але не є сертифікатом безпеки.

31.9. Інші процеси потребують інших контрактів

Ті самі принципи переносяться на різні задачі, але їх не варто змішувати в один універсальний workflow:

Сценарій	Що Skill може підготувати	Де потрібна зупинка або окремий дозвіл
Jira → реалізація	Перевірити вимоги, перелічити прогалини, зіставити критерії з файлами і підготувати доказ виконання	Не змінювати статус чи призначення без потрібної авторизації; не вигадувати acceptance criteria
Міграція	Прочитати поточний контракт, залежних читачів, підготувати план сумісності, перевірки та rollback	Перед записом у спільну базу, видаленням даних чи застосуванням у production
Реліз	Зібрати артефакти готовності, версію, зміни, незакриті ризики та шлях відкату	Не публікувати/розгортати, не оголошувати успіх без підтвердження середовища
Інцидент	Побудувати часову шкалу з журналів, відділити факти від гіпотез, знайти власника й наступний безпечний крок	Не виконувати руйнівні команди, не ротувати ключі, не відновлювати production без окремої процедури
Архітектурне рішення	Порівняти альтернативи за навантаженням, відмовами, даними, ціною зміни та доказами	Не представляти припущення як факт; рішення належить власнику архітектури

Наприклад, для системи імпорту футболу Skill міграції може підготувати перехід від одного поля <code>current_team_id</code> до журналу історії roster changes, виявити читачів і запропонувати план сумісності. Це не дорівнює дозволу застосувати міграцію до спільної бази. Для incident Skill корисний часовий журнал доказів, але він не повинен автоматично вимикати потік офіційних транзакцій лише тому, що затримка зросла.

31.10. Перевірка, підтримка і діагностика

Перевіряйте дві окремі властивості:

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

Anthropic радить порівнювати реалістичні запити в нових сесіях зі Skill та без нього. Свіжий контекст важливий: під час написання автор уже знає, що мав на увазі, і його попередні повідомлення можуть приховати недолік тексту. Для оцінки візьміть прямі й перефразовані позитивні запити, негативні приклади, межові/неповні дані, дубльовані або суперечливі інструкції та спробу зробити зовнішню дію (документація Claude Code про оцінювання Skills).

Зручна матриця для діагностики:

Спостереження	Ймовірна зона проблеми	Що перевірити
Skill не запускається на прямому запиті	Discovery/опис/місце встановлення	Чи host бачить Skill, чи зрозуміло названо задачу, чи ввімкнено джерело
Запускається на нерелевантних задачах	Надто широка область або збіг із сусіднім Skill	Відредагувати description, додати негативні межі, відокремити процеси
Запускається, але не виконує процедуру	Тіло або ресурси	Перевірити порядок кроків, конкретність evidence, умови зупинки і посилання на references
Посилається на неіснуючу версію чи tool	Сумісність	Перевірити продукт, API, версію та реально доступні інструменти
Виконує небажаний побічний ефект	Архітектура контролю, а не тільки текст	Обмежити tool access, застосувати ask/deny policy або зовнішнє затвердження

Зафіксуйте host-продукт і версію, каталог встановлення, commit або release пакета, тестові запити, очікування, фактичні результати, інструменти та оцінювача. Окремо перевіряйте інструкції, які покладаються на нові поля frontmatter, shell, hooks чи API attachments. Не стверджуйте підтримку на іншому host лише тому, що обидва читають <code>SKILL.md</code>.

Поточна документація прив’язує окремі можливості до версій. Наприклад, <code>background</code> для forked Skill потребує Claude Code v2.1.218 або новішого; синхронізація Skills із claude.ai в terminal вимагає v2.1.273 або новішого. Ці позначки показують, чому слід перевіряти точний host і його версію, а не переносити можливість на інші поверхні (документація Claude Code). Ці мінімальні версії перевірено 10.10.2026; пізніший клієнт може додавати інші умови.

Не покладайтеся на неявну нумерацію каталогу як версію пакета. Для відтворення зафіксуйте commit або release, що його містить, і опишіть зміну поведінки: що змінилося у тригерах, кроках, ресурсах, scripts та вимогах до host. Claude Code frontmatter не має окремого стандартизованого поля версії, яке host зобов’язаний читати; довільне <code>metadata.version</code> має сенс лише для власного каталогу або інструмента, який явно його споживає. Переглядайте сторонній Skill ще раз після оновлення і зберігайте історію змін у контрольованому репозиторії (специфікація Agent Skills; документація Claude Code).

31.11. Коротка евристика проєктування

Перед публікацією Skill варто пройти таку послідовність:

1. Назвіть одну повторювану задачу й те, що явно лишається поза її межами.
2. Напишіть опис для каталогу з конкретними тригерами й негативними прикладами.
3. Визначте джерела даних, кроки, рішення, критерій достатніх доказів, формат відповіді та безпечну умову зупинки.
4. Винесіть об’ємну довідку або машинно-повторювану роботу в окремий ресурс лише з поясненням, коли його читати чи запускати.
5. Відокремте текстову рекомендацію від фактичного дозволу на файли, мережу, інструменти та побічні ефекти.
6. Перевірте пакет повністю: його авторство, ліцензію, історію, посилання, scripts, залежності та можливий доступ до секретів.
7. Перевірте в окремих сесіях, коли Skill активується і що він видає, на позитивних, негативних і межових запитах.
8. Повторіть перевірку для продукту та версії, які реально використовуватимуть цей пакет.

Якщо процедура стабільна, але модель часто пропускає крок, спочатку зробіть саму інструкцію конкретною; якщо умова точна й машинно-перевірна, винесіть її в детермінований скрипт чи CI. Якщо небезпечно покладатися на намір моделі, змініть доступ або бар’єр host-системи. Якісний Skill не розростається до мініатюрного універсального агента: він дає чіткий workflow, знає власні межі й лишає перевірні докази.

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

Доступ до мінливих сторінок і стан прикладів перевірено 10 жовтня 2026 року. Документація продуктів є rolling documentation: звіряйте її з версією, на якій працює ваш workflow.

1. Anthropic, Extend Claude with skills — Claude Code Docs, поточна онлайн-документація, доступ 2026-10-10. Використано для шляхів Skills, frontmatter Claude Code, discovery/loading, permissions, supporting files, оцінювання, версійних застережень і різниці з іншими способами розповсюдження.
2. Agent Skills, Specification, поточна специфікація формату, доступ 2026-10-10. Використано для мінімальної структури каталогу, обов’язкових <code>name</code> і <code>description</code> та необов’язкових стандартних метаданих.
3. Anthropic, Agent Skills overview, поточна онлайн-документація, доступ 2026-10-10. Використано для прогресивного завантаження, API-передумов і меж виконання Skills в ізольованому середовищі.
4. OpenAI, Build skills — ChatGPT Learn, поточна онлайн-документація, доступ 2026-10-10. Використано лише для короткого зіставлення вимог Codex/ChatGPT, progressive disclosure і виклику за описом.
5. OpenAI, Skills — API documentation, поточна онлайн-документація, доступ 2026-10-10. Використано для ілюстрації, що завантаження Skills через API залежить від типу виконання та способу підключення файлів.
6. Anthropic, skill-creator Skill у зрізі commit ef740771, його SKILL.md у цьому commit та LICENSE.txt у цьому каталозі, перевірені 2026-10-10. Це публічний приклад межі між коротким entrypoint, scripts, references і оцінювальними допоміжними файлами; ліцензія каталогу — Apache License 2.0. Історія файла показує конкретний rewrite у commit 3d595115 від 2026-02-25: він вилучив речення “Do not include any other fields in YAML frontmatter.”, яке ще є в зрізі ef740771. Ліцензію потрібно перевіряти окремо для кожного каталогу у сторонньому репозиторії.
7. Anthropic, issue #249 у anthropics/skills, відкрите повідомлення, створене 2026-01-18; доступ 2026-10-10. Це історичний звіт про речення “Do not include any other fields in YAML frontmatter.”, яке містив наведений у джерелі зріз SKILL.md з commit ef740771 від 2025-12-01. Речення було вилучено під час переписування файла у commit 3d595115 від 2026-02-25; відкрите issue не означає, що поточна гілка <code>main</code> досі містить цю інструкцію. Приклад показує, чому повідомлення треба звіряти з актуальним commit, а не трактувати як опис теперішнього стану.