# Як правильно створювати Skills для Claude Code: від архітектури до тестування
> Вичерпне інженерне керівництво зі створення Skills для Claude Code: анатомія папок і SKILL.md, поетапне завантаження (progressive disclosure), відмінності від хуків та evaluation-driven підхід.
## 1. Що таке Skill і чому це повноцінний програмний артефакт
**Skill (навичка)** у Claude Code — це стандартизований модульний пакет знань, що містить опис робочого процесу (workflow), набір доменних правил, процедур або виконуваних скриптів, які ШІ-агент автоматично підвантажує для вирішення конкретного класу завдань. Замість того щоб інженер щоразу вручну копіював довгі інструкції у кожну нову сесію, агент самостійно розпізнає намір користувача та активує відповідний Skill.
Головна відмінність Skill від традиційного програмного коду полягає в тому, що рішення про його активацію приймає сама мовна модель на основі семантичного зіставлення опису навички із запитом користувача. Це рішення є **ймовірнісним**: тут немає компілятора чи строгої типізації, тому точність формулювання метаданих безпосередньо визначає, чи буде навичка активована в потрібний момент.
```mermaid
flowchart TD
subgraph Invocation ["Активація навички"]
Prompt["Запит користувача"] --> Matcher{"Семантичне зіставлення (LLM)"}
Meta["Frontmatter name + description
(~100 токенів на старті)"] --> Matcher
Matcher -->|Збіг наміру| Load["Підвантаження SKILL.md у контекст"]
Matcher -->|Немає збігу| Normal["Стандартне виконання без навички"]
end
subgraph Execution ["Пайплайн виконання"]
Load --> Steps["Виконання покрокових інструкцій"]
Steps --> Scripts["Запуск локальних скриптів (bash/python)"]
Steps --> Refs["Читання довідкових файлів (references/)"]
Scripts & Refs --> Result["Фінальний артефакт / код"]
end
```
### Чому Skill є інженерним артефактом, а не звичайним текстом
1. **Версіонування та модульність:** Навичка складається зі стандартних файлів репозиторію, зберігається в git і розвивається за тими ж законами, що й прикладний код.
2. **Розподіл інтерфейсу та реалізації:** Поле `description` у frontmatter виступає публічним інтерфейсом навички, тоді як тіло `SKILL.md` та вкладені скрипти є її внутрішньою реалізацією.
3. **Композиційність:** Навичка може викликати зовнішні інструменти через MCP, запускати консольні утиліти та делегувати підзадачі іншим навичкам чи субагентам.
4. **Вразливість до регресій:** Неграмотно змінений опис може призвести до "мовчазної відмови" (skill перестає активуватися) або до галюцинацій при виконанні кроків.
> [!NOTE]
> Специфікація **Agent Skills**, запропонована Anthropic, є відкритим форматом. Навички, оформлені відповідно до цього стандарту, сумісні не лише з Claude Code, а й з іншими передовими інструментами автоматизації розробки.
---
## 2. Структура файлів і директорій: SKILL.md, скрипти та довідкові ресурси
Навичка являє собою структуровану папку у файловій системі, обов'язковим ядром якої є файл `SKILL.md`. Залежно від складності завдання навичка може доповнюватися допоміжними скриптами, довідниками та шаблонами.
### Рівні зберігання навичок у Claude Code
- **Глобальні навички (`~/.claude/skills/`):** Доступні розробнику в усіх проєктах на поточній машині. Ідеально для персональних утиліт, персональних шаблонів комітів чи аналітичних скриптів.
- **Проєктні навички (`.claude/skills/`):** Зберігаються безпосередньо в репозиторії проєкту та комітяться в git. Доступні всім членам команди, гарантуючи єдині стандарти архітектури та тестування.
### Рекомендована структура складної навички
```text
.claude/skills/release-notes/
├── SKILL.md # Обов'язковий: метадані та інструкції
├── changelog-style.md # Ресурс: правила оформлення списку змін
└── scripts/
└── gather-prs.py # Виконуваний скрипт: збір злитих PR через API
```
Мінімальна навичка може складатися лише з одного файлу `SKILL.md`. Більші системи упаковують у директорію навички власні скрипти автоматизації та документацію, що дозволяє тримати логіку компактною та самодостатньою.
---
## 3. Правила оформлення Frontmatter: name та description
Файл `SKILL.md` обов'язково починається з блоку метаданих у форматі YAML Frontmatter. Це єдина частина навички, яку Claude зчитує під час ініціалізації сесії для побудови каталогу доступних дій.
```yaml
---
name: release-notes
description: Drafts release notes from merged pull requests between two git tags. Use when cutting a release or updating the changelog.
---
```
### Формальні обмеження на ім'я (name)
- Довжина не більше **64 символів**.
- Дозволені лише малі латинські літери, цифри та дефіси (`[a-z0-9-]`).
- Заборонено використання будь-яких XML/HTML-тегів.
- Заборонено використовувати зарезервовані назви компанії (`claude`, `anthropic`).
### Формальні обмеження на опис (description)
- Обов'язкове непорожнє поле.
- Довжина не більше **1024 символів**.
- Заборонено використання XML-тегів.
- Має чітко описувати як функціонал навички, так і контекстні тригери для її активації.
| Поле | Допустимий приклад | Неприпустимий приклад | Чому заборонено |
| :--- | :--- | :--- | :--- |
| `name` | `db-migrate-helper` | `Claude-DB-Helper!` | Великі літери, спецсимволи та зарезервоване слово `claude` |
| `name` | `deploy-staging` | `deploy_` | Заборонені символи підкреслення та кутові дужки |
| `description` | `Generates API documentation from Express routes. Use when updating docs.` | `A tool for API` | Занадто короткий і неконкретний опис, відсутні тригери запуску |
> [!WARNING]
> Якщо навичка повинна запускатися виключно за явною командою користувача і не повинна спрацьовувати автоматично, її автоматичний виклик можна обмежити, перетворивши навичку на детерміновану слеш-команду.
---
## 4. Поетапне завантаження (Progressive Disclosure) та контекстне вікно
Skills не завантажуються в контекстне вікно моделі повністю під час запуску сесії. Claude Code використовує принцип **поетапного завантаження (Progressive Disclosure)**, розбитий на три чіткі рівні.
```mermaid
flowchart LR
L1["Рівень 1: Метадані
(~100 токенів, читається завжди)"] -->|Тригер збігу| L2["Рівень 2: Тіло SKILL.md
(~1-3k токенів, читається за потреби)"]
L2 -->|Посилання у кроках| L3["Рівень 3: Ресурси та скрипти
(0 токенів до виклику або запуску)"]
```
### Три рівні завантаження
1. **Рівень 1 — Метадані (Metadata):** Імена та описи всіх доступних навичок завантажуються в системний контекст на початку сесії. Витрати становлять близько 100 токенів на навичку. Це дозволяє підключати десятки навичок до проєкту без ризику вичерпати ліміт контексту.
2. **Рівень 2 — Тіло файлу (Body):** Коли модель вирішує, що запит користувача відповідає опису навички, вона зчитує вміст `SKILL.md`. Рекомендований розмір тіла — до 500 рядків, щоб не витісняти робочу історію діалогу.
3. **Рівень 3 — Вкладені файли та скрипти (Resources):** Довідкові файли (`references/`) зчитуються лише тоді, коли інструкція безпосередньо посилається на них. Скрипти здебільшого запускаються через bash-інтерпретатор: їхній код взагалі не потрапляє в контекстне вікно, повертається лише фінальний результат виконання.
---
## 5. Формулювання description: створення надійних тригерів активації
Оскільки `description` є головним тригером ймовірнісного спрацювання, його формулюванню слід приділяти особливу увагу.
### Правила побудови ефективного опису
- **Тільки третя особа:** Пишіть опис від третьої особи (`Generates`, `Performs`, `Audits`). Модель сприймає опис як системну специфікацію інструменту; займенники першої чи другої особи (`I will`, `You can`) погіршують якість зіставлення.
- **Формула «Що + Коли»:** Опис повинен чітко відповідати на два питання: що саме робить навичка і в яких ситуаціях її необхідно застосовувати.
- **Реальні ключові слова:** Включайте специфічні технічні терміни, назви файлів або команд, які користувач гарантовано згадає у своєму запиті.
:::tabs
@tab Слабкий опис
```yaml
---
name: release-notes
description: Handles project releases and writes updates.
---
```
*Проблема: Відсутні конкретні контекстні тригери. Модель не знає, які файли читати і коли саме активувати навичку.*
@tab Еталонний опис
```yaml
---
name: release-notes
description: Drafts release notes from merged pull requests between two git tags. Use when cutting a release, updating the changelog, or summarizing what changed in a version.
---
```
*Перевага: Чітко визначені вхідні сутності (git tags, pull requests) та сценарії активації (cutting a release, updating changelog).*
:::
---
## 6. Анатомія еталонного Skill: покроковий розбір пайплайну release-notes
Розглянемо практичну архітектуру навички автоматизації релізної документації `release-notes`.
### Складові елементи робочого процесу
- **Вхідні параметри:** Аргументи користувача (діапазон тегів `v1.2.0..v1.3.0`), довідковий посібник зі стилю `changelog-style.md`, допоміжний скрипт `gather-prs.py`.
- **Покрокова послідовність у `SKILL.md`:**
1. Визначити діапазон релізних тегів у git.
2. Запустити скрипт `python scripts/gather-prs.py` для отримання структурованого списку комітів.
3. Згрупувати зміни за категоріями (Features, Fixes, Performance, Breaking Changes).
4. Підготувати драфт відповідно до стилю в `changelog-style.md`.
5. Записати оновлений блок у `CHANGELOG.md` та вивести коротке резюме.
- **Вихідні артефакти:** Оновлений файл `CHANGELOG.md` та стисле повідомлення для команди.
### Архітектурні правила для тіла файлу
1. **Не повторюйте загальновідомі речі:** Вважайте, що Claude вже є кваліфікованим інженером. Описуйте лише специфіку вашого проєкту та суворі корпоративні вимоги.
2. **Глибина посилань — лише один рівень:** Довідкові файли не повинні посилатися ланцюжком на інші файли. Всі матеріали мають бути безпосередньо прив'язані до `SKILL.md`.
3. **Кросплатформні шляхи:** Завжди використовуйте прямі слеші (`/`) у всіх шляхах до файлів та конфігурацій.
---
## 7. Ландшафт кастомізацій: Skills, CLAUDE.md, Slash-команди, MCP, хуки та плагіни
У Claude Code існує кілька інструментів керування поведінкою агента. Помилковий вибір механізму — найпоширеніша причина ненадійності системи.
| Механізм | Хто ініціює запуск | Сила впливу | Оптимальний сценарій використання |
| :--- | :--- | :--- | :--- |
| **CLAUDE.md (Memory)** | Рантайм (завжди в контексті) | Рекомендаційна | Короткі загальні правила проєкту, стек технологій, базові команди |
| **Skill** | Модель (семантично) або людина | Рекомендаційна | Складні доменні процедури, робочі процеси з вкладеними скриптами |
| **Slash-команда** | Користувач (через `/команда`) | Рекомендаційна | Збережені інтерактивні шаблони промптів, які викликаються вручну |
| **Subagent** | Модель або користувач | Ізольована | Делегування незалежної об'ємної задачі в окреме контекстне вікно |
| **MCP Tool** | Модель (через Tool Call) | Виконавча | Пряма взаємодія із зовнішніми базами даних та хмарними API |
| **Hook** | Рантайм (детерміновано) | **Блокувальна** | Жорсткі перевірки безпеки, лінтери перед комітом, валідація дій |
| **Plugin** | Користувач (інсталяція) | Комплексна | Пакетне поширення набору навичок, MCP-серверів та хуків для команди |
> [!IMPORTANT]
> Лише механізми, керовані безпосередньо рантаймом (наприклад, **хуки**), здатні надати абсолютну гарантію виконання та блокування небажаних дій. Текстова інструкція всередині Skill залишається рекомендацією, якої модель дотримується ймовірнісно.
---
## 8. Skills проти Hooks: баланс між рекомендаціями та гарантіями рантайму
Початківці часто намагаються використати Skills для завдань безпеки чи примусового форматування коду. Це концептуальна помилка: навичка не гарантує виконання, вона лише навчає модель правильному підходу.
### Точки життєвого циклу виконання
- **SessionStart (Хук):** Спрацьовує під час відкриття сесії. Гарантує ініціалізацію змінних середовища чи попередню перевірку гілки git.
- **Розмірковування моделі (Можливе читання Skill):** Модель аналізує завдання та приймає рішення щодо завантаження тіла `SKILL.md`.
- **PreToolUse (Хук, блокувальний):** Виконується безпосередньо перед викликом будь-якого інструменту. Може перевірити команду bash і заблокувати її виконання (код повернення 2), якщо вона порушує правила безпеки.
- **PostToolUse (Хук):** Аналізує результат виконання команди або модифікації файлу (наприклад, автоматично запускає Prettier після запису файлу).
- **Stop (Хук):** Спрацьовує після завершення генерації відповіді моделлю.
```text
Золоте правило вибору:
- Якщо дія вимагає гнучкого інженерного мислення та контексту ──► Створюйте SKILL
- Якщо дія повинна виконуватися безумовно і без винятків ──► Налаштовуйте HOOK
```
---
## 9. Процес розробки через оцінку (Evaluation-Driven Development)
Створення надійної навички вимагає ітеративного тестування на реальних сценаріях ще до написання фінального тексту інструкцій.
### Чотири етапи створення навички
1. **Фіксація базового рівня (Baseline):** Запустіть Claude Code на типових робочих завданнях без навички. Зафіксуйте, де саме модель помиляється, пропускає кроки або вимагає додаткових роз'яснень.
2. **Створення тестових кейсів (Eval Suite):** Перетворіть зафіксовані помилки на перелік контрольних завдань із чітко визначеними очікуваними результатами.
3. **Написання мінімального тексту (MVP):** Сформулюйте мінімальний набір інструкцій у `SKILL.md`, достатній для успішного проходження тестів.
4. **Ітеративне шліфування:** Додавайте правила та винятки лише у відповідь на конкретні провали тестових кейсів, уникаючи роздування контексту.
### Робочий процес із двома екземплярами моделі
Під час проєктування навички рекомендується використовувати два паралельні термінали:
- **Екземпляр-редактор:** Сесія, де ви спільно з Claude формулюєте, доповнюєте та структуруєте текст нової навички.
- **Екземпляр-тестувальник:** Чиста сесія, де ви запускаєте тестові запити та перевіряєте: чи підхоплюється навичка автоматично, чи правильно інтерпретуються кроки і чи валідні результуючі файли.
---
## 10. Типові патерни проектування та антипатерни при створенні Skills
Практичний досвід спільноти виділив низку перевірених шаблонів та типових помилок, яких слід уникати.
### Ефективні інженерні патерни
- **Пронумеровані детерміновані послідовності:** Для складних багатоетапних дій завжди структуруйте кроки у вигляді `1. ...`, `2. ...`, `3. ...`.
- **Вбудовані чек-листи валідації:** Для критичних операцій додавайте чек-лист, який модель повинна скопіювати у відповідь та відмічати за мірою виконання.
- **Цикли самоперевірки (Verify & Fix):** Задавайте правило: «Запустити лінтер -> виправити помилки -> перевірити повторно до чистого виводу».
- **Планування перед деструктивними діями:** Для операцій пакетного видалення чи перезапису файлів вимагайте спочатку сформувати план змін у markdown-таблиці та запросити підтвердження.
### Поширені антипатерни
- **Параліч вибору:** Опис надмірної кількості альтернативних бібліотек чи підходів без зазначення варіанту за замовчуванням.
- **Неоголошені системні залежності:** Використання сторонніх CLI-утиліт або npm-пакетів без попередньої інструкції щодо їх встановлення чи перевірки наявності.
- **Зворотні слеші у шляхах:** Використання бекслешів у стилі Windows (`src\utils\`), що спричиняє збої на Linux та macOS.
- **Непояснені магічні числа:** Використання констант або тайм-аутів без коментаря щодо їхньої природи.
---
## 11. Безпека та аудит сторонніх Skills перед встановленням
Будь-яка стороння навичка — це виконуваний код у вашому робочому середовищі. Оскільки Claude Code має доступ до файлової системи, терміналу та мережі, неперевірений Skill несе серйозні ризики безпеки.
### Чек-лист аудиту сторонньої навички перед використанням
- [ ] **Аналіз тіла `SKILL.md`:** Перевірте текст на наявність прихованих інструкцій із prompt injection, спроб викрадення `.env` файлів чи відключення захисних механізмів.
- [ ] **Аудит вкладених скриптів:** Уважно вивчіть усі файли в каталозі `scripts/`. Переконайтеся, що скрипти не здійснюють підозрілих мережевих запитів на сторонні сервери.
- [ ] **Перевірка зовнішніх URL:** Зверніть увагу на будь-які посилання на завантаження зовнішніх бінарних файлів або динамічних конфігурацій.
- [ ] **Ізольоване тестування:** Перший запуск сторонньої навички завжди здійснюйте у тестовому репозиторії або пісочниці без доступу до продакшн-секретів.