Skills: як надіти на агента готове вміння

Є прохання, яке ви повторюєте: подивись зміни, перевір ці файли, оформи ось так, а сюди не лізь. Щоразу ви пояснюєте процедуру заново і трохи інакше.

Результат гуляє разом із формулюванням. Сьогодні вийшло чудово, завтра ви забули половину умов, і агент чесно зробив те, що почув.

Лікує це не пам'ять агента, а тека з інструкцією. Skill - це записана один раз процедура, яку Claude Code може підключити сам або за вашою командою. Розберемо, де ця тека лежить, як переконатися, що skill підхопився, і що перевірити до першого запуску.

Що таке skill

Перш ніж розбирати файли й поля, вловимо інтуїцію.

Уявіть столяра. Він один раз записав звичний порядок роботи, підготував пам'ятки, шаблони і програму для верстата. Тепер коротко: "прибери все, нагостри свердло, далі стілець для кота - запусти ЧПК-шаблон". Запустив - і поїхали.

Записана процедура тримає всю роботу разом:

• Наводить лад за вашими правилами. Прибирає верстак, розкладає інструмент - щоразу однаково, точно так, як ви звикли.
• Дотримується записаних меж. Пила ще крутиться - не лізе. Безпечну частину роботи робить одразу, без зайвих запитань.
• Зазирає в пам'ятки, коли треба. Треба нагострити свердло - відкрив правило про гостріння. Не тримає його в голові заздалегідь, дістає на місці.
• Тримає шаблони для різних робіт. Перейшли зі столу на стільці - бере готову схему підготовки.
• Запускає складне однією командою. Програма повторюваних розпилів уже лежить поруч. Досить сказати: "знайди шаблон Стілець для кота і пусти на ЧПК" - верстат дотримається зазорів і порядку операцій.

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

Сам формат skill нічого не ізолює. Інструкція може обмежити роботу оформленням, але технічної стіни між CSS і логікою немає. Хороший skill прямо називає свою ділянку роботи; після запуску ви дивитеся змінені файли і перевіряєте поведінку сторінки. "Працює" і "виглядає" - різні шари, а гарантію дає перевірка, не формат.

Де живе skill

Жодної магії в хмарі тут немає. Skill - це тека на диску, у вашому ж проєкті:

.claude/skills/web-design/SKILL.md

Шлях розбирається за сегментами: службова тека .claude, усередині неї skills, усередині - тека самого skill (ім'я вигадуєте ви), а в ній файл SKILL.md. Звичайний текстовий файл, відкривається будь-чим.

Для skill у проєкті й домашній теці ім'я каталогу стає іменем команди зі слешем, якщо в самому файлі не задано інше ім'я (про це нижче). Тож вигадуйте його одразу з прицілом на те, який вигляд воно матиме в чаті.

Тепер уточнення до найчастішої картинки в голові: skill це не один файл, а тека. Поруч із SKILL.md може лежати що завгодно.

.claude/
└── skills/
    └── web-design/
        ├── SKILL.md      # головний файл: опис та інструкція
        ├── palettes.md   # довідник, агент відкриє його, якщо знадобиться
        └── scripts/
            └── check.py  # скрипт, який можна запустити

Для автоматичного вибору агенту доступні ім'я і короткий опис skill, а не все тіло. SKILL.md завантажується під час запуску, сусідні довідники - за потреби. Тому довга пам'ятка не заповнює контекст заздалегідь.

Для звичайної локальної роботи важливі три джерела skills:

Значок ~ означає домашню теку користувача. У командах його лишають як є; якщо відкриваєте теку вручну, переходьте у свій домашній каталог.

Різниця між першими двома місцями проста, і розібратися з нею варто одразу.

Поклали теку в проєкт - skill працює тільки в цьому проєкті. Відкрили сусідній, а там його немає.

Skill у домашній теці доступний у всіх проєктах. Це зручно для спільної процедури, але вона може увімкнутися там, де ви на неї не чекали. Універсальне кладуть додому, проєктне лишають у проєкті.

Якщо Claude Code запущено з окремим навчальним профілем ~/.claude-javarush/, особисті skills лежать у його теці skills/. Проєктний шлях .claude/skills/ від профілю не змінюється.

Description вирішує, коли skill спрацює

Типова історія: теку поклали, файл на місці, а агент поводиться точно як раніше. Нічого не зламано - просто він не зрозумів, що цей skill сюди підходить.

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

Зберемо мінімальний skill для проєкту від початку до кінця. Він має ім'я web-design - так називається тека, і звідси ж береться команда /web-design. Окремо у файлі ім'я не пишемо, тека його вже задала:

.claude/skills/web-design/SKILL.md

А всередині ось що, і більше нічого не потрібно:

---
description: Приводить вебінтерфейс до ладу - сучасний CSS, плавні переходи,
  узгоджена палітра. Застосовувати, коли просять зробити красиво або стильно.
---

# Вебдизайн

Використовуй м'які тіні, плавні переходи і продуману типографіку.
Палітру тримай узгодженою, анімації - на наведення і появу елементів.

Зверху, між потрійними дефісами, службовий блок, знизу звичайний текст інструкції. Обов'язкових полів немає, але description варто писати завжди: без нього агент вгадує призначення skill за першим абзацом тіла, а це лотерея.

Хороший опис відповідає на два запитання: що skill робить і коли його брати. Причому тими словами, якими ви реально пишете запити.

# мовчить: незрозуміло, коли застосовувати
description: Допомагає з оформленням

# спрацьовує: сказано і що робить, і коли
description: Приводить інтерфейс до ладу - CSS, типографіка, палітра.
  Застосовувати, коли просять зробити красиво, стильно або поправити верстку.

Опис відповідає за те, коли skill підніметься сам. Але це не єдиний вхід: skill має ім'я, і за ним його можна покликати вручну. Набрали /web-design - і опис узагалі ні до чого, файл читається і виконується.

У готових skills часто трапляється поле name. У skills у проєкті й домашній теці воно задає команду, яку показує меню за /: тека deploy-staging з name: deploy викликається як /deploy. Ім'я каталогу при цьому теж працює. У плагіні name може задати останню частину команди після імені плагіна.

Шляхів запуску, отже, два, а все, що після них, однакове.

Ліва гілка - автоматична: запит збігся з описом, агент узяв skill. Права - ручна: набрали /web-design, і skill запустився незалежно від опису.

Skills потрапляють у те саме меню, що й вбудовані команди, - воно відкривається через /. Файл .claude/commands/deploy.md і skill .claude/skills/deploy/SKILL.md створюють одну команду /deploy; якщо лежать обидва, виграє skill.

Встановити й перевірити

Теку поклали. Як зрозуміти, що агент її побачив, а не просто файл лежить на диску?

/skills

Команда відкриває список skills і показує їхнє джерело. Наберіть пару літер - список відфільтрується. Знайшли ім'я своєї теки і стан on - Claude Code бачить skill і дозволяє його запуск.

Ім'я, джерело і стан on підтверджують, що skill доступний

Зазвичай Claude Code підхоплює новий або змінений SKILL.md на льоту. Якщо імені в списку немає, перебирайте по черзі:

Skill є в списку, але не вмикається сам? Перезавантаження тут ні до чого. Перевірте description і поле disable-model-invocation: true - воно лишає тільки ручний запуск. Переформулюйте прохання або викличте skill за іменем. Ручний виклик працює - отже, встановлення справне.

Що перевірити до того, як довіряти

Тут доведеться притамувати захват. Skill це не тема оформлення і не картинка, яку можна поставити і зняти. Це інструкції, які ваш агент виконає у вашому проєкті.

Перевіряти треба не тільки головний файл, а всю теку. Почніть із чотирьох речей:

• опис - чи збігається він з тим, чого ви від skill чекаєте, і чи не спрацьовує надто широко;
• тіло і посилання з нього - що skill велить робити і які сусідні файли просить відкрити;
• тека scripts/, якщо вона є, - які команди там запускаються, які файли й мережеві адреси вони чіпають;
• поле allowed-tools - які інструменти skill заздалегідь дозволяє використовувати без окремого запитання.

---
name: pre-commit-style
description: Приводить проєкт до спільного стилю перед комітом
allowed-tools: Read, Write, Edit, Glob
---

Тут allowed-tools не описує план роботи і не обмежує повний набір можливостей агента. Поле лише попередньо схвалює перелічені інструменти на той хід, у якому викликано skill. Імена розшифровуються просто:

• Read - читати файли;
• Write - створювати нові файли й перезаписувати наявні цілком;
• Edit - вносити правки всередину наявного файлу;
• Glob - шукати файли за маскою, тобто ходити проєктом і дивитися, що в ньому взагалі є.

Перший і останній тільки дивляться. Write і Edit вміють змінювати файли: якщо інструкція приведе до такої дії, окремого запитання на цьому ході може не бути. Але наявність дозволу не означає, що агент обов'язково ним скористається. Загальні правила доступу проєкту діють і далі.

Саме по собі поле не зло: воно прибирає зайві підтвердження там, де ви саме цього й хочете. Але набір вибирав автор skill, тому дивитися його варто до першого запуску.

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

Де брати готові

Писати SKILL.md з нуля, щоб спробувати, зовсім не обов'язково. Найчастіше готові skills знаходять у відкритих репозиторіях або отримують разом із плагінами.

Найкоротший шлях - попросити агента знайти відповідний варіант, але не встановлювати його наосліп. Формулювання може бути таким:

Знайди skill для оформлення інтерфейсів. Покажи джерело, SKILL.md і скрипти,
поясни, які файли й інструменти він використовує. До мого підтвердження
нічого не встановлюй.

Подивилися джерело і вміст - тоді просіть покласти теку в .claude/skills/ проєкту і перевіряйте результат через /skills.

Для самостійного пошуку підійде запит Claude skills marketplace. Каталог допомагає знайти варіанти, але не є гарантією безпеки: вміст усе одно читають до встановлення.

SKILL.md дотримується відкритого стандарту Agent Skills, тому базова структура переноситься між різними агентами. Але Claude Code додає власні поля і способи запуску. Перенесли skill в інший інструмент - перевірте, які можливості він там справді підтримує.

Свій skill можна зібрати з агентом

Момент, коли час заводити свій skill, видно без жодної теорії: одну й ту саму процедуру ви пояснюєте втретє. Не завдання, а саме порядок дій - подивись те, перевір це, оформи ось так, сюди не лізь. Повторюється - отже, дозріла.

І тут хороша новина. Писати SKILL.md з чистого аркуша не обов'язково. Агент може зібрати чернетку, а від вас потрібне одне - пояснити, яка це процедура і чого ви від неї хочете. Це схоже на звичайну розмову:

Зроби skill для підготовки коміту. Він має дивитися, що змінилося,
перевіряти, чи не потрапили в коміт зайві файли, і писати повідомлення
за нашим шаблоном. Запускати буду руками, коли сам захочу.
Якщо вимог не вистачає, спочатку постав запитання.

Зверніть увагу, жодного поля ви не назвали і в будову файлу не полізли. Вимоги ви описали словами, перевести їх у поля - робота агента.

Якщо даних не вистачає, агент поставить запитання. Без такого прохання він може одразу зробити припущення, тому потрібний рядок уже є в прикладі. Отримавши чернетку, перевірте файли, знайдіть skill через /skills і зробіть пробний запуск.

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

Коли SKILL.md розростається

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

Складати все в одне місце не треба, і причина вже називалася вище: тіло вантажиться цілком, щойно skill пішов у діло. Чотири екрани довідника поїдуть у роботу і того разу, коли з них знадобився один рядок.

Тому деталі виносять у сусідні файли, а в SKILL.md лишають відсилання: якщо така-то ситуація - відкрий такий-то файл. Теку з palettes.md і scripts/ ви вже бачили, ось який вона має вигляд зсередини:

## Довідники

- Палітри та поєднання кольорів - у [palettes.md](palettes.md)
- Готові приклади розмітки - у [examples.md](examples.md)
- Перевірити контрастність: запусти scripts/check.py

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

Розкладати зручно за призначенням:

• SKILL.md - сама процедура: що робити, в якому порядку, чого не робити. До виклику агент бачить її опис, а тіло завантажує під час запуску;
• довідники - таблиці, правила, довгі приклади, усе, що потрібне не в кожному запуску;
• scripts/ - те, що простіше виконати, ніж описати словами. У чужому skill ці файли перевіряють до запуску;
• шаблони - файли, які skill бере за основу і пристосовує до завдання.

Звідси ж зворотний висновок, уже про чужі skills. Короткий SKILL.md не означає "простий skill". Зазирніть, що лежить у теці поруч із ним.

Що це змінює в роботі

Якщо зібрати все в кілька рядків:

• повторюване прохання перетворюється на теку. Один раз описали порядок роботи - далі він відтворюється однаково, у будь-якій сесії і в будь-який день;
• свій skill можна не писати з чистого аркуша. Пояснюєте процедуру словами, просите уточнити те, чого бракує, і перевіряєте зібрану чернетку;
• під час автоматичного запуску skill вибирається за description, під час ручного - за іменем зі слешем. Якщо він мовчить, спершу з'ясуйте, чи видно його в списку і чи дозволено автозапуск;
• /skills відповідає на запитання "чи він узагалі підхопився". Півхвилини перевірки заощаджують півгодини здогадок;
• чужий skill читається до встановлення і запуску, разом із пов'язаними файлами і скриптами;
• skill змінює те, як агент робить роботу, але не ізолює ділянку правок і не скасовує перевірку результату.