Практичний посібник · 23 вересня 2026

Як створювати Agent Skills: інструменти, тести й встановлення

Створити перший Agent Skill легко. Достатньо зробити папку, покласти в неї SKILL.md і написати кілька інструкцій.

Складніше зрозуміти, чи цей Skill справді працює.

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

Нижче — інструменти для всього циклу: створення, покращення, валідації, тестування, встановлення і підтримки.

Що таке Skill на практиці

Agent Skill — це папка з інструкціями, довідковими матеріалами й, за потреби, виконуваними скриптами. Обов'язковий файл лише один: SKILL.md.

Мінімальний Skill виглядає так:

review-migration/
└── SKILL.md

---
name: review-migration
description: Reviews database migrations for compatibility and rollback risks. Use when a user creates or changes a database migration.
---

Review the migration:

1. Check backward compatibility.
2. Identify locks or long-running operations.
3. Verify the rollback or roll-forward path.
4. Report only risks introduced by this migration.

Відкритий стандарт Agent Skills вимагає полів name і description. Поле Description визначає, коли агенту варто читати повний Skill для поточної задачі.

Це важливо через те, як завантажуються Skills:

1. Агент бачить службові дані всіх доступних Skills.
2. Description підказує агенту, чи читати конкретний Skill.
3. Після активації читає повний SKILL.md.
4. Додаткові references/, scripts/ та assets/ відкриває лише за потреби.

Anthropic називає це поступовим розкриттям (progressive disclosure). Це механізм керування контекстом: агенту не потрібно тримати повний текст усіх Skills у кожному запиті. Він читає інструкції для потрібної задачі, а великі довідкові матеріали відкриває, коли вони знадобляться.

Skill, AGENTS.md чи Plugin

Не кожну інструкцію варто перетворювати на Skill.

Хороший сигнал для нового Skill: ви втретє вставляєте в чат той самий контрольний список або пояснюєте той самий процес новій сесії.

Чим створювати Skills

1. Сам агент

Окремий генератор не обов'язковий. Офіційний посібник Anthropic радить спочатку виконати реальну задачу від початку до кінця у звичайній сесії з агентом, а потім попросити витягнути з неї повторюваний процес у Skill.

Це кращий старт, ніж вигадувати універсальний Skill на порожньому місці. У реальній роботі швидко видно:

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

Початковий запит може бути простим:

Перетвори процес, який ми щойно виконали, на Agent Skill.
Залиши в SKILL.md лише обов'язковий процес.
Довгі довідкові матеріали винеси в references/.
Додай приклади запитів, які мають і не мають викликати Skill.

2. skill-creator або superpowers:writing-skills

Коли чернетка вже є, можна використати офіційний skill-creator. Він допомагає створювати й редагувати Skills, формувати тестові сценарії, порівнювати результат із початковим прогоном без Skill та робити сліпе A/B-порівняння двох версій.

Встановлення з офіційного Marketplace:

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

Після встановлення можна попросити агента:

Оціни мій Skill review-migration за допомогою skill-creator.

Для створення Skills я рекомендую Codex і superpowers:writing-skills. Його принцип жорсткіший: спочатку дати агенту реальний сценарій без Skill і зафіксувати конкретний провал; потім написати мінімальний Skill, повторити той самий сценарій і перевірити, чи поведінка змінилася. Якщо агент і без Skill стабільно виконує задачу правильно, новий Skill може взагалі не мати сенсу.

Для ранньої версії цього достатньо. Не треба будувати CI-систему для інструкції, якою ви ще не скористалися двічі.

Три різні види перевірки

Слово "валідація" часто приховує три різні питання.

Superpowers:writing-skills додає перед ними нульовий етап: запустити без Skill сценарій, у якому агент працює під тиском, і подивитися, як він поводиться без додаткових інструкцій. Це перевіряє саму гіпотезу. Якщо початковий прогін уже успішний, Skill нічого не додає; якщо ні — ви бачите конкретну поведінку, яку треба змінити.

1. Чи правильна структура

Для переносимого Skill використовуйте валідатор відкритого стандарту:

$skills-ref validate ./review-migration

Він перевіряє службові поля на початку файла (frontmatter) і правила назв.

У Claude Code можна перевірити skills проєкту так:

$claude plugin validate .claude/skills

Або всі user-level customizations:

$claude plugin validate ~/.claude

За документацією Claude Code, валідатор знаходить проблеми в YAML, службових полях та структурі Plugin. Це перевірка синтаксису й схеми. Успішний результат не означає, що агент вибере Skill у правильний момент.

2. Чи Skill спрацьовує

Доручіть цю перевірку superpowers:writing-skills ще під час створення Skill. Попросіть включити до тестових сценаріїв реальні запити, які мають його викликати, і схожі за словами запити, на які він не повинен реагувати. superpowers:writing-skills проведе прогони й покаже, чи агент знаходить інструкцію в потрібний момент.

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

3. Чи результат став кращим

Для Skill, упакованого як Plugin, Claude Code має окремий засіб перевірки:

$claude plugin eval init$claude plugin eval .

Claude plugin eval запускає кожен сценарій в ізольованій сесії кілька разів із Plugin і без нього. Оцінювачі можуть перевіряти текст, виклики інструментів, порядок дій, створені файли або застосовувати критерії, які перевіряє LLM. Різниця між WITH і W/OUT показує внесок Plugin, а не просто здатність базової моделі виконати задачу.

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

Важлива деталь: skill-creator і claude plugin eval використовують різні формати перевірок. Перший зручний для послідовного вдосконалення одного Skill у розмові. Другий краще підходить для Plugin, набору регресійних перевірок та CI.

Що дає /skill-doctor

/skill-doctor відповідає на інше питання: які Skills забирають контекст, але майже не використовуються.

Він показує, скільки контексту займають описи, які Skills ще не викликалися та які Plugins давно не використовувалися. Це допомагає прибрати шум із великої бібліотеки. Але /skill-doctor не оцінює якість інструкцій і не замінює перевірок поведінки.

Як встановити Skill у проєкт

Найпростіший варіант — додати його вручну:

$mkdir -p .claude/skills/review-migration

Потім створити .claude/skills/review-migration/SKILL.md і закомітити папку. Skill завантажиться в сесіях цього репозиторію.

Для особистого Skill, потрібного в усіх локальних проєктах:

~/.claude/skills/review-migration/SKILL.md

Для монорепозиторію можна покласти Skill у <package>/.claude/skills/. Він застосовуватиметься до роботи в цьому піддереві.

Якщо Skill опублікований у Git-репозиторії й підтримує відкриту екосистему:

$npx skills add owner/repository --skill review-migration -a claude-code

Додайте -g, щоб встановити його глобально, а не в поточний проєкт.

Коли потрібні Plugin і Marketplace

Окремий Skill добре працює всередині одного репозиторію. Plugin потрібен, коли ви хочете:

• поширювати кілька Skills одним пакетом;
• додати агентів, Hooks або налаштування MCP;
• мати простір імен на кшталт /database-tools:review-migration;
• версіонувати й оновлювати пакет;
• підключити формальний набір перевірок.

Мінімальна структура Plugin:

database-tools/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review-migration/
        └── SKILL.md

Локально Plugin можна перевірити так:

$claude --plugin-dir ./database-tools$claude plugin validate ./database-tools

Для поширення команда може створити приватний Marketplace, додати його на рівні проєкту і встановлювати Plugin звідти. Офіційна документація Marketplace підтримує репозиторій GitHub, Git URL, віддалений marketplace.json і локальний шлях.

›/plugin marketplace add acme/database-plugins›/plugin install database-tools@acme-database-plugins

CLI-еквівалент підтримує рівні user, project і local. На рівні project конфігурація записується в репозиторій, щоб команда бачила одне джерело Plugin.

Перевіряйте сторонній Skill до встановлення

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

Skill — це інструкції для агента, який має доступ до файлів та інструментів. Plugin може додатково містити Hooks, MCP servers і виконувані скрипти. Популярність у каталозі не робить цей код автоматично безпечним.

Для командної бібліотеки краще зафіксувати перевірену версію, запускати валідацію в CI й оновлювати Skills так само свідомо, як інші залежності.

Рекомендований процес без зайвої інфраструктури

Для першого Skill:

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

Для Skill, яким користується команда:

1. Додайте більше реальних сценаріїв.
2. Перенесіть нестабільні кроки у детерміновані скрипти.
3. Запакуйте Skill як Plugin.
4. Додайте claude plugin eval.
5. Запускайте набір перевірок після змін Skill і після переходу на нову модель.
6. Періодично дивіться /skill-doctor і вимикайте те, що не використовується.

Головна помилка: тестувати файл, а не зміну поведінки

Найслабший критерій успіху звучить так: «Агент прочитав Skill, і відповідь виглядає нормально».

Корисніші питання:

• Чи викликався Skill без згадки його назви?
• Чи промовчав він на схожий, але нерелевантний запит?
• Чи покращив результат порівняно з початковим прогоном?
• Чи зменшив кількість повторних пояснень?
• Чи можна повторити результат у новій сесії?
• Чи виправляє нова версія конкретний провал, не ламаючи старі сценарії?

Skill — це не документ, який треба один раз красиво написати. Це виконувана частина агентного процесу. Ставтеся до нього як до коду: тримайте коротким, перевіряйте на реальних сценаріях, версіонуйте й не плутайте валідний синтаксис із правильною поведінкою.