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 є інженерним артефактом, а не звичайним текстом

Версіонування та модульність: Навичка складається зі стандартних файлів репозиторію, зберігається в git і розвивається за тими ж законами, що й прикладний код.
Розподіл інтерфейсу та реалізації: Поле description у frontmatter виступає публічним інтерфейсом навички, тоді як тіло SKILL.md та вкладені скрипти є її внутрішньою реалізацією.
Композиційність: Навичка може викликати зовнішні інструменти через MCP, запускати консольні утиліти та делегувати підзадачі іншим навичкам чи субагентам.
Вразливість до регресій: Неграмотно змінений опис може призвести до "мовчазної відмови" (skill перестає активуватися) або до галюцинацій при виконанні кроків.

Примітка

Специфікація Agent Skills, запропонована Anthropic, є відкритим форматом. Навички, оформлені відповідно до цього стандарту, сумісні не лише з Claude Code, а й з іншими передовими інструментами автоматизації розробки.

2. Структура файлів і директорій: SKILL.md, скрипти та довідкові ресурси

Навичка являє собою структуровану папку у файловій системі, обов'язковим ядром якої є файл SKILL.md. Залежно від складності завдання навичка може доповнюватися допоміжними скриптами, довідниками та шаблонами.

Архітектура навички: інтерфейс, реалізація, ресурси в комплекті та зовнішні інструменти Збільшити

Архітектура навички: інтерфейс, реалізація, ресурси в комплекті та зовнішні інструменти

Рівні зберігання навичок у Claude Code

Глобальні навички (~/.claude/skills/): Доступні розробнику в усіх проєктах на поточній машині. Ідеально для персональних утиліт, персональних шаблонів комітів чи аналітичних скриптів.
Проєктні навички (.claude/skills/): Зберігаються безпосередньо в репозиторії проєкту та комітяться в git. Доступні всім членам команди, гарантуючи єдині стандарти архітектури та тестування.

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_<staging>`	Заборонені символи підкреслення та кутові дужки
`description`	`Generates API documentation from Express routes. Use when updating docs.`	`A tool for API`	Занадто короткий і неконкретний опис, відсутні тригери запуску

Увага

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

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 — Метадані (Metadata): Імена та описи всіх доступних навичок завантажуються в системний контекст на початку сесії. Витрати становлять близько 100 токенів на навичку. Це дозволяє підключати десятки навичок до проєкту без ризику вичерпати ліміт контексту.
Рівень 2 — Тіло файлу (Body): Коли модель вирішує, що запит користувача відповідає опису навички, вона зчитує вміст SKILL.md. Рекомендований розмір тіла — до 500 рядків, щоб не витісняти робочу історію діалогу.
Рівень 3 — Вкладені файли та скрипти (Resources): Довідкові файли (references/) зчитуються лише тоді, коли інструкція безпосередньо посилається на них. Скрипти здебільшого запускаються через bash-інтерпретатор: їхній код взагалі не потрапляє в контекстне вікно, повертається лише фінальний результат виконання.

5. Формулювання description: створення надійних тригерів активації

Оскільки description є головним тригером ймовірнісного спрацювання, його формулюванню слід приділяти особливу увагу.

Правила побудови ефективного опису

Тільки третя особа: Пишіть опис від третьої особи (Generates, Performs, Audits). Модель сприймає опис як системну специфікацію інструменту; займенники першої чи другої особи (I will, You can) погіршують якість зіставлення.
Формула «Що + Коли»: Опис повинен чітко відповідати на два питання: що саме робить навичка і в яких ситуаціях її необхідно застосовувати.
Реальні ключові слова: Включайте специфічні технічні терміни, назви файлів або команд, які користувач гарантовано згадає у своєму запиті.

6. Анатомія еталонного Skill: покроковий розбір пайплайну release-notes

Розглянемо практичну архітектуру навички автоматизації релізної документації release-notes.

Покроковий пайплайн виконання навички 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 та стисле повідомлення для команди.

Архітектурні правила для тіла файлу

Не повторюйте загальновідомі речі: Вважайте, що Claude вже є кваліфікованим інженером. Описуйте лише специфіку вашого проєкту та суворі корпоративні вимоги.
Глибина посилань — лише один рівень: Довідкові файли не повинні посилатися ланцюжком на інші файли. Всі матеріали мають бути безпосередньо прив'язані до SKILL.md.
Кросплатформні шляхи: Завжди використовуйте прямі слеші (/) у всіх шляхах до файлів та конфігурацій.

7. Ландшафт кастомізацій: Skills, CLAUDE.md, Slash-команди, MCP, хуки та плагіни

У Claude Code існує кілька інструментів керування поведінкою агента. Помилковий вибір механізму — найпоширеніша причина ненадійності системи.

Матриця механізмів кастомізації Claude Code: хто визначає запуск проти сили впливу Збільшити

Матриця механізмів кастомізації Claude Code: хто визначає запуск проти сили впливу

Механізм	Хто ініціює запуск	Сила впливу	Оптимальний сценарій використання
CLAUDE.md (Memory)	Рантайм (завжди в контексті)	Рекомендаційна	Короткі загальні правила проєкту, стек технологій, базові команди
Skill	Модель (семантично) або людина	Рекомендаційна	Складні доменні процедури, робочі процеси з вкладеними скриптами
Slash-команда	Користувач (через `/команда`)	Рекомендаційна	Збережені інтерактивні шаблони промптів, які викликаються вручну
Subagent	Модель або користувач	Ізольована	Делегування незалежної об'ємної задачі в окреме контекстне вікно
MCP Tool	Модель (через Tool Call)	Виконавча	Пряма взаємодія із зовнішніми базами даних та хмарними API
Hook	Рантайм (детерміновано)	Блокувальна	Жорсткі перевірки безпеки, лінтери перед комітом, валідація дій
Plugin	Користувач (інсталяція)	Комплексна	Пакетне поширення набору навичок, MCP-серверів та хуків для команди

Важливо

Лише механізми, керовані безпосередньо рантаймом (наприклад, хуки), здатні надати абсолютну гарантію виконання та блокування небажаних дій. Текстова інструкція всередині Skill залишається рекомендацією, якої модель дотримується ймовірнісно.

8. Skills проти Hooks: баланс між рекомендаціями та гарантіями рантайму

Початківці часто намагаються використати Skills для завдань безпеки чи примусового форматування коду. Це концептуальна помилка: навичка не гарантує виконання, вона лише навчає модель правильному підходу.

Життєвий цикл виконання сесії Claude Code та точки інтеграції хуків і навичок Збільшити

Життєвий цикл виконання сесії Claude Code та точки інтеграції хуків і навичок

Точки життєвого циклу виконання

SessionStart (Хук): Спрацьовує під час відкриття сесії. Гарантує ініціалізацію змінних середовища чи попередню перевірку гілки git.
Розмірковування моделі (Можливе читання Skill): Модель аналізує завдання та приймає рішення щодо завантаження тіла SKILL.md.
PreToolUse (Хук, блокувальний): Виконується безпосередньо перед викликом будь-якого інструменту. Може перевірити команду bash і заблокувати її виконання (код повернення 2), якщо вона порушує правила безпеки.
PostToolUse (Хук): Аналізує результат виконання команди або модифікації файлу (наприклад, автоматично запускає Prettier після запису файлу).
Stop (Хук): Спрацьовує після завершення генерації відповіді моделлю.

text

Золоте правило вибору: - Якщо дія вимагає гнучкого інженерного мислення та контексту ──► Створюйте SKILL - Якщо дія повинна виконуватися безумовно і без винятків ──► Налаштовуйте HOOK

9. Процес розробки через оцінку (Evaluation-Driven Development)

Створення надійної навички вимагає ітеративного тестування на реальних сценаріях ще до написання фінального тексту інструкцій.

Чотири етапи створення навички

Фіксація базового рівня (Baseline): Запустіть Claude Code на типових робочих завданнях без навички. Зафіксуйте, де саме модель помиляється, пропускає кроки або вимагає додаткових роз'яснень.
Створення тестових кейсів (Eval Suite): Перетворіть зафіксовані помилки на перелік контрольних завдань із чітко визначеними очікуваними результатами.
Написання мінімального тексту (MVP): Сформулюйте мінімальний набір інструкцій у SKILL.md, достатній для успішного проходження тестів.
Ітеративне шліфування: Додавайте правила та винятки лише у відповідь на конкретні провали тестових кейсів, уникаючи роздування контексту.

Робочий процес із двома екземплярами моделі

Під час проєктування навички рекомендується використовувати два паралельні термінали:

Екземпляр-редактор: Сесія, де ви спільно з 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: Зверніть увагу на будь-які посилання на завантаження зовнішніх бінарних файлів або динамічних конфігурацій.
Ізольоване тестування: Перший запуск сторонньої навички завжди здійснюйте у тестовому репозиторії або пісочниці без доступу до продакшн-секретів.

Як правильно створювати Skills для Claude Code: від архітектури до тестування