SKILL.md без магії: збираємо власну навичку Claude Code за інженерними патернами

Коротко (TL;DR)

Навичка (skill) у Claude Code — це тека з файлом SKILL.md, у якому лежить процедура: як виконувати конкретний тип завдання. Claude підхоплює її сам, коли завдання підпадає під опис. Це не плагін і не магія, а інженерна дисципліна: у навички є передбачувана анатомія, ліміти й повторювані патерни організації.

Що ви отримаєте з цього гайда:

• Анатомію SKILL.md — з чого він складається і чому тіло тримають під 500 рядків.
• 5 іменованих патернів організації навички, які реально працюють: високорівневий гід із винесеними деталями, доменне нарізання, умовні гілки, workflow з чек-листом і скрипти замість генерації коду.
• Два способи зібрати власну навичку — через офіційний плагін Skill Creator з вимірюваним eval-циклом і вручну, покроково.
• Дерево рішень «навичка проти субагента проти slash-команди проти CLAUDE.md» — щоб не тягнути в навичку те, чому там не місце.
• Чесний розбір self-improving skills: що з цього заявлене бачення Anthropic, а що — вже робочі саморобки спільноти.

Рівень матеріалу — просунутий: припускаємо, що ви вже ставили готові навички і тепер хочете писати власні. Якщо ще ні — спершу варто розібратися зі встановленням, а сюди повернутися по будову й патерни. Усі версії команд і ліміти наведені станом на липень 2026 року; екосистема Claude Code змінюється швидко, і частина цифр (номери версій, назви прапорців) застаріє першою — звіряйтеся з офіційними доками на дату читання.

Навіщо взагалі писати власні навички

Навичка розв’язує одну проблему: модель за замовчуванням не знає вашу процедуру. Вона вміє писати код, але не знає, що у вашому проєкті деплой іде через конкретний скрипт, звіти збираються у визначеному форматі, а числа звіряються за вашим реєстром. Навичка кодифікує це знання один раз — і Claude дістає його на вимогу, а не щоразу заново з підказок у чаті.

Тут важливо розрізняти два типи користі, бо їх часто плутають.

Хуки Claude Code: як автоматизувати дії агента і не підірватися на власних налаштуваннях

MCP у Claude Code: як підключити сервери, не спалити контекст і коли він не потрібен

Плагіни в Claude Code: як встановити, створити власний маркетплейс і не спіймати шкідливий

Agent Skills у Claude Code: як працюють, де взяти і як не поставити шкідливий скіл

Пам’ять Claude Code: Auto Memory, /memory і чому агент забуває

• Capability uplift (приріст спроможності). Навичка дає моделі те, чого в неї не було: доменну процедуру, рідкісний формат, специфічний API. Це головна причина писати навички — і саме вона піддається вимірюванню.
• Encoded preference (зафіксована перевага). Навичка просто повторює те, що модель і так уміє, але вашим способом («пиши коміти ось так»). Користь є, але вона про зручність, а не про нові можливості.

Що це дає в цифрах. Незалежний бенчмарк SkillsBench (arXiv 2602.12670, лютий 2026) прогнав 87 завдань у 8 доменах на 18 конфігураціях «модель + харнес». Куровані, добре структуровані навички підняли середній pass rate з 33,9% до 50,5% — на +16,6 процентного пункта. Але розкид великий: за різними конфігураціями приріст коливався від +4,1 до +25,7 п.п., а на 13 завданнях із 87 дельта виявилася від’ємною — навичка заважала. Висновок простий: навичка окупається там, де вона несе справжню доменну процедуру, і шкодить, коли нав’язує зайву гілку міркувань.

Тримайте цей висновок у голові до кінця гайда. Він пояснює, чому структура й тестування навички важливіші, ніж сам факт її існування.

Анатомія SKILL.md: з чого реально складається навичка

Навичка — це директорія, а не один файл. Мінімум усередині — SKILL.md з YAML-шапкою (frontmatter) і тілом у Markdown. Поряд можуть лежати винесені файли-довідники й виконувані скрипти. Claude Code читає навички з чотирьох місць із чітким пріоритетом: enterprise (керовані налаштування) перекриває personal (~/.claude/skills/), personal перекриває project (.claude/skills/), а plugin-навички (<plugin>/skills/) ідуть окремо. За збігу імен перемагає вищий рівень.

Ключовий механізм, який треба зрозуміти до написання першого рядка, — прогресивне розкриття (progressive disclosure). Контекст завантажується у три рівні, і це прямо впливає на те, як ви розкладаєте матеріал:

1. Метадані (name + description) — завжди в контексті, приблизно сотня слів на навичку. За ними модель вирішує, брати навичку чи ні.
2. Тіло SKILL.md — вантажиться цілком, коли навичка спрацювала. Звідси ліміт: тримайте його коротшим за 500 рядків.
3. Пов’язані файли та скрипти — підтягуються лише в міру потреби. Скрипт при цьому виконується без завантаження свого тексту в контекст: у діалог потрапляє тільки його вивід.

Сенс цієї трирівневості — економія контексту. Метадані всіх навичок висять у пам’яті постійно, тому вони мають бути крихітними. Усе важке (приклади, таблиці, рідкісні гілки) від’їжджає на рівні 2 і 3 та вантажиться лише тоді, коли справді потрібне. Добре написана навичка — це не «великий файл із усім одразу», а тонкий вхід із покажчиками вглиб.

Саме тут проходить межа між «поставити готову навичку» і «написати власну». Користувачу готової навички досить знати, що вона робить. Автору — треба свідомо керувати тим, що потрапить у контекст на кожному з трьох рівнів. Далі — про те, як цим керувати.

Синтаксис frontmatter, який вирішує

Frontmatter — це YAML-шапка SKILL.md. Більшість полів необов’язкові, але кілька визначають, спрацює навичка чи ні і як саме вона виконається. Розберемо ті, що важливі на практиці.

Пара нюансів, на яких спотикаються.

Ліміт description — це про Platform API, а не про лістинг Claude Code. У завантажуваних пакетах Platform/API поле description обмежене 1024 символами. Усередині самого Claude Code механіка інша: зв’язка description + when_to_use обрізається на 1536 символах у лістингу, а загальний бюджет на перелік усіх навичок — 1% контекстного вікна моделі (налаштовується). Це різні продукти й різні ліміти — не змішуйте їх в одну цифру.

name у Claude Code можна не писати. Команда навички визначається розташуванням файлу: навичка в .claude/skills/deploy/SKILL.md дає /deploy незалежно від вмісту frontmatter. Ба більше, кастомні команди злиті з навичками: файл .claude/commands/deploy.md і навичка .claude/skills/deploy/SKILL.md створюють одну й ту саму /deploy і працюють однаково. Старий шлях commands/ живий як legacy, але канонічний тепер — skills/.

description пишуть у третій особі й навмисно «наполегливо». Офіційна інструкція самого Skill Creator прямо попереджає: у моделі є тенденція недотригерювати навички — не використовувати їх там, де вони були б корисні. Ліки — явно перелічувати в описі контексти спрацювання, навіть якщо користувач не називає навичку прямо. Формулювання на кшталт «Use when the user asks about X, mentions Y, or needs Z» надійніше, ніж сухе «Handles X».

5 патернів організації навички

Далі — ядро гайда: п’ять відтворюваних способів розкласти навичку. Це не взаємовиключні варіанти — в одній навичці їх зазвичай комбінують. Усі приклади спираються на офіційні best practices і на вихідники skill-creator.

Патерн 1. Високорівневий гід + винесені references

Базовий патерн прогресивного розкриття. У SKILL.md лишається тільки карта процесу й рішення «коли що», а важкі деталі (повні специфікації, довгі таблиці, довідники API) переїжджають в окремі файли поряд. Тіло тримають під 500 рядків; при наближенні до ліміту офіційна порада — не втискати текст, а додати ще один рівень ієрархії, тобто винести шматок у новий файл-довідник.

Коли застосовувати: навичка покриває велику тему, але в кожному конкретному завданні потрібен лише її зріз. Модель спершу читає тонкий гід, а вглиб іде тільки за потрібним посиланням.

Патерн 2. Доменна організація

Коли навичка обслуговує кілька незалежних піддоменів (наприклад, три різні формати звітів або три підсистеми), їх розносять по окремих reference-файлах, а в SKILL.md лишають диспетчер: «працюєш з A — відкрий a.md, з B — b.md». Так контекст не роздувається сумою всіх доменів одразу — вантажиться лише релевантний.

Ключове обмеження тут — глибина посилань. Тримайте винесені файли на один рівень від SKILL.md. Якщо файл посилається на файл, який посилається на третій, Claude може прочитати проміжні лише частково (аж до head -100), і частина інструкцій загубиться.

Патерн 3. Умовні деталі (гілки за завданням)

Різновид, де SKILL.md містить дерево умов: «якщо завдання таке — зроби так; якщо немає даних — ось запасний шлях; для рідкісного випадку X — дивись edge-cases.md». Часті гілки описані прямо в тілі, рідкісні винесені. Це той самий принцип економії контексту, але застосований до логіки, а не до довідкових даних: звичайний шлях читається завжди, екзотика підвантажується на вимогу.

Патерн 4. Workflow з чек-листом і петлею зворотного зв’язку

Для багатокрокових процесів навичка задає явну послідовність із перевіркою на виході: зібрати → виконати → звіритися з чек-листом → у разі провалу повернутися і полагодити. Петля зворотного зв’язку (feedback loop) — те, що відрізняє надійну workflow-навичку від простої інструкції: вона не просто перелічує кроки, а вимагає підтвердження результату перед завершенням.

Цей патерн особливо доречний там, де помилку легко не помітити: генерація за суворим форматом, міграції, публікація. Чек-лист у кінці навички працює як гейт — модель зобов’язана пройтися по ньому, а не відрапортувати «готово» на око.

Патерн 5. Скрипти замість генерації коду

Найнедооціненіший патерн. Якщо операція детермінована (розпарсити PDF, порахувати метрику, переформатувати дані) — не просіть Claude писати код заново щоразу. Покладіть готовий скрипт у scripts/ і в тілі навички скажіть моделі його запустити.

Виграш подвійний. По-перше, економія контексту: скрипт виконується через bash, його джерельний код не вантажиться в діалог — токени витрачає лише вивід. По-друге, детермінованість: код дає той самий результат щоразу, а генерація коду на льоту — ні. Офіційний приклад Anthropic — видобування даних із PDF: навичка запускає скрипт, не завантажуючи ні його текст, ні сам PDF у контекст.

Як створити навичку: Skill Creator і вручну

Є два шляхи. Офіційний — через плагін, який автоматизує не лише чернетку, а й перевірку, що навичка взагалі допомагає. Ручний — коли потрібне повне розуміння або навичка зовсім маленька.

Шлях 1. Skill Creator (офіційний плагін)

Skill Creator — це офіційна мета-навичка Anthropic: навичка, яка створює навички. Ставиться з офіційного маркетплейсу:

/plugin install skill-creator@claude-plugins-official

Він веде вас циклом draft → test → eval → iterate і — це головне — автоматизує порівняння з baseline. Схематично кроки такі:

1. Інтерв’ю. Плагін розпитує, яке саме завдання розв’язує навичка і в яких контекстах має спрацьовувати.
2. Чернетка. Генерує SKILL.md з frontmatter і тілом, розкладений за патернами вище.
3. Тест-кейси. Складає набір запитів, на яких навичка має допомагати.
4. Eval-loop. Проганяє ці запити з увімкненою навичкою і без неї — і порівнює результат. Це відповідь на питання, яке більшість авторів взагалі не ставлять: «а моя навичка реально щось покращує?»
5. Оптимізація description. Якщо навичка недотригерюється, плагін докручує опис, щоб модель брала її в потрібних випадках.

Саме цей вимірюваний цикл, а не «просто напишіть SKILL.md руками», — те, що перетворює написання навички з ворожіння на інженерію. Для порівняння: екосистема Claude — це вже родина продуктів і поверхонь, від асистента в Slack до Claude Code; навички переносять вашу процедуру між ними, але тільки якщо процедура справді перевірена.

Шлях 2. Вручну, за кроками

Якщо хочете зібрати навичку самі, мінімальний маршрут такий:

1. Створіть теку — .claude/skills/<ім'я>/ у проєкті (спільна для команди) або ~/.claude/skills/<ім'я>/ (особиста).
2. Напишіть frontmatter — щонайменше виразне description у третій особі з переліком тригерів. Ім’я команди прийде з імені теки.
3. Тіло — тонкий гід. Викладіть процедуру кроками. Усе важке одразу виносьте в reference-файли поряд (патерн 1), тримайтеся під 500 рядків.
4. Детерміноване — у скрипти (патерн 5), рідкісне — в умовні гілки (патерн 3).
5. Протестуйте на свіжому екземплярі. Контрінтуїтивна, але офіційна порада: навичку, написану в одній сесії Claude, перевіряйте в іншій, чистій сесії. Автор-інстанс уже «знає» контекст і затригерить навичку навіть за кривим описом — свіжий інстанс покаже, чи спрацює вона в реального користувача.

Ручний шлях дешевший за встановленням, але позбавляє вас eval-петлі. Як показав SkillsBench, «на око» навичка може здаватися корисною і при цьому не давати приросту. Тому навіть за ручного збирання має сенс прогнати хоча б пару завдань із навичкою і без.

Self-improving skills: бачення й реальність

Тема «самовдосконалюваних навичок» звучить гучно, тому розкладемо її на заявлене Anthropic і реально відвантажене спільнотою.

Що каже Anthropic. У статті-анонсі Agent Skills (жовтень 2025) сформульовано так: «ми сподіваємося дати агентам можливість самим створювати, редагувати й оцінювати навички». Ключове слово — сподіваємося. Це форвард-лукінг бачення, ціль на майбутнє, а не поточна функція. Станом на липень 2026 року вбудованої автономної фічі, у якій Claude Code сам без людини генерує і впроваджує собі навички, в офіційній документації немає. Skill Creator — інструмент з людиною в циклі: він асистує, але не діє автономно.

Що реально існує. «Self-improving skills», про які пишуть у блогах, — це саморобні пайплайни спільноти поверх звичайних механізмів. Показовий розбір (dev.to, авторка Lily, 10 липня 2026) описує робочу систему з трьох частин:

• Генерація в сесії — навичка, яка за кількома тригерами пропонує оформити нову процедуру.
• Нічний збір — headless-прогін (claude -p) по логах за день, який витягує повторювані патерни.
• Щотижневий Curator — і ось це найважливіше: він не видаляє навички. Невикористані 30 днів позначаються як stale, 90 днів — від’їжджають у .archive/. За кілька місяців так накопичилося 64 авто-навички в ізольованому просторі ~/.claude/skills/auto/.

Те, що цей патерн незалежно відтворено в кількох GitHub-репозиторіях, каже про те, що підхід робочий. Але подавати його як «фічу Claude Code» не можна — це інженерне рішення конкретних людей, зібране зі звичайних цеглин: skill-creator, headless-режим і планувальник.

І головна протверезлива деталь. Той самий SkillsBench показав: навички, які модель згенерувала собі сама, у середньому працюють гірше, ніж узагалі без навичок (на всіх трьох перевірених зв’язках модель+харнес дельта була від’ємною). Модель надійно користується готовим процедурним знанням, але надійно писати його собі — поки що не вміє. Звідси правило для будь-якого self-improving пайплайну: автогенерація без зовнішньої оцінки — це накопичення шуму. Потрібен eval, а не відчуття прогресу.

Що обрати: навичку, субагента, slash-команду чи CLAUDE.md

Перш ніж писати навичку, варто перевірити, що завдання взагалі про навичку. Розвилка розв’язується за двома осями: хто викликає механізм і чи потрібна ізоляція контексту.

Як читати цю таблицю на практиці:

• Потрібне постійне правило («завжди пиши українською», «не чіпай прод») — це CLAUDE.md, а не навичка. Навичка вантажиться за ситуацією, а CLAUDE.md — завжди.
• Потрібна процедура на вимогу — навичка. Якщо вона має спрацьовувати сама — звичайна; якщо лише за вашою командою — додайте disable-model-invocation: true.
• Завдання важке й автономне, його не треба тягнути в основний діалог — субагент або навичка з context: fork. Різниця: субагента Claude обирає як окремого виконавця, а context: fork — це спосіб ізолювати саму навичку.

Помилка вибору дорого коштує: постійне правило, засунуте в навичку, не спрацює, коли треба; а важкий ресерч без ізоляції заб’є контекст і завалить якість решти діалогу. Гарний приклад межі автономності — особисті ІІ-агенти на кшталт OpenClaw: там видно, наскільки швидко неізольована автономна робота з’їдає і бюджет, і увагу.

Антипатерни, які вбивають навичку

Систематизованого списку помилок українською майже немає, тому зберемо головні. Усі — з офіційних best practices.

Зарезервовані слова теж сюди: імена на кшталт anthropic-helper або claude-tools заборонені правилами поля name.

Чи працюють навички взагалі: дані, а не віра

Раз уже ми спираємося на вимірюваність, варто подивитися на навички скептично — за незалежними бенчмарками.

Перший висновок ми вже навели: куровані навички дають +16,6 п.п. pass rate, а згенеровані моделлю — нижче рівня «взагалі без навичок» (SkillsBench, лютий 2026). Тобто цінність не в самому факті навички, а в якості процедури всередині.

Другий висновок жорсткіший. Робота «How Well Do Agentic Skills Work in the Wild» (arXiv 2604.04323, квітень 2026) перевірила, що буде, коли навичку потрібно знайти серед великої колекції — 34 тисячі реальних навичок, — а не підставити вручну ідеальну під завдання. Результат: у міру наближення умов до реалістичних виграш деградує майже до рівня без навичок узагалі. Рятує не кількість, а стратегія: зв’язка «пошук + доопрацювання» (retrieval + refinement) частково відновлює результат — наприклад, на Terminal-Bench 2.0 підняла pass rate Claude Opus 4.6 з 57,7% до 65,5%.

Практичний сенс для вас як автора: «накопичити побільше навичок» — не стратегія. Десять точних, перевірених, добре описаних навичок корисніші за сотню згенерованих «про всяк випадок», бо другі модель або не знайде, або візьме не ті. Це рівно та розвилка, де self-improving пайплайн без Curator і eval перетворюється з помічника на звалище.

Ризики й безпека: навичка — це виконуваний код

Навичка з чужого репозиторію містить інструкції, а часто й скрипти, які Claude виконає у вашому оточенні. Це вектор атаки, і Anthropic каже про це прямо (попередження від 16 жовтня 2025): шкідлива навичка може внести вразливості або скерувати Claude на крадіжку даних і небажані дії. Офіційна рекомендація — ставити навички лише з довірених джерел і переглядати код і скрипти перед увімкненням неперевіреного. Не хардкодьте в навичку секрети (API-ключі, паролі) — вони втечуть разом із навичкою.

Те, що це не абстракція, видно зі свіжого тла навколо довіри до агентів. На початку липня 2026 року пройшла новина про те, що Alibaba обмежує використання Claude Code на робочих місцях через ймовірні ризики (3 липня 2026), а на Hacker News зібрав велике обговорення тред про недекларовану поведінку агента. Тема довіри до того, що агент робить під капотом, — гаряча, і на навички з неперевірених джерел вона поширюється безпосередньо. Правило просте: ставтеся до встановлення навички як до запуску чужого скрипта з вашими правами, бо це рівно воно і є.

FAQ

Чим навичка відрізняється від CLAUDE.md? CLAUDE.md завжди в контексті — це постійні правила проєкту, які потрібні в кожній відповіді. Навичка вантажиться за ситуацією, коли завдання підпадає під її description. Постійне правило в навичці не спрацює в потрібний момент, а разову процедуру немає сенсу тримати в CLAUDE.md постійно.

Чи обов’язкове поле name у SKILL.md? У Claude Code — ні: ім’я команди береться з імені теки навички. У завантажуваних пакетах Platform/API name обов’язковий і підкоряється правилам: до 64 символів, лише малі літери, цифри й дефіси, без слів anthropic і claude.

Чому моя навичка не спрацьовує? Найчастіше річ у description — модель схильна недотригерювати навички. Перепишіть опис у третій особі, явно переліченими контекстами спрацювання, і зробіть його навмисно «наполегливим». Офіційний Skill Creator уміє оптимізувати опис автоматично через eval-петлю.

Чи існує вбудована функція self-improving skills? Станом на липень 2026 року — ні. Anthropic формулює це як бачення на майбутнє («сподіваємося дати агентам можливість самим створювати й оцінювати навички»). Те, що називають self-improving skills сьогодні, — саморобні пайплайни спільноти поверх звичайного Skill Creator, headless-режиму й планувальника.

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

Коли замість навички потрібен субагент? Коли підзавдання важке й автономне (об’ємний ресерч, ревʼю) і його не треба тягнути в основний контекст. Субагент має своє контекстне вікно й інструменти. Якщо хочеться ізолювати саме навичку, є проміжний варіант — context: fork, який виконує навичку у форкнутому субагенті.