Як написати власну навичку агента

Напишіть власну навичку агента на основі однієї реальної помилки

Найкращий спосіб написати власну навичку агента — виокремити її з однієї реальної помилки. Знайдіть завдання, яке ваш coding agent двічі виконав неправильно, запишіть виправлення, яке ви вводили в обох випадках, і збережіть це виправлення у файлі SKILL.md, який агент зможе завантажувати самостійно. Після цього все зводиться до механіки: структури файлу та одного рядка, від якого залежить, чи буде навичка взагалі активована.

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

Почніть із завдання, яке агент двічі виконав неправильно

Одна помилка може бути випадковістю. Дві однакові помилки — це закономірність, яку варто оформити в окремий файл.

Ось типова помилка, що повторюється на реальних серверах. Ви просите агента додати блок reverse proxy до nginx. Він змінює /etc/nginx/conf.d/app.conf, а потім запускає sudo systemctl restart nginx. У зміні є синтаксична помилка, тому nginx відмовляється запускатися, і сайт не працює, доки ви не виправите конфігурацію:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

Ви виправляєте помилку в чаті. Перед взаємодією із сервісом перевіряєте конфігурацію за допомогою sudo nginx -t, а потім застосовуєте зміни командою reload замість restart. Через тиждень, під час іншого завдання, повторюється та сама помилка. Саме друга помилка є сигналом.

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

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

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

Структура skill

Skill — це каталог з одним обов’язковим файлом.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md починається з блоку frontmatter: кількох параметрів у форматі YAML (такому самому форматі конфігурації, який використовують файли Docker Compose) між маркерами ---. Після нього розміщено інструкції у форматі Markdown. Нижче наведено весь skill для попередньої помилки.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

Цей файл містить менш як 20 рядків і є повноцінним skill. Його частини:

• name: до 64 символів; дозволені лише малі літери, цифри та дефіси. Рядок не може містити слова claude або anthropic. У personal skill або project skill це лише display label. Команда, яку ви вводите, визначається назвою каталогу, тому цей skill викликається командою /nginx-config-changes.
• description: опис того, що робить skill і коли його потрібно використовувати; до 1,024 символів. Цей рядок виконує основну роботу, і наступний розділ присвячено саме цьому.
• Тіло: інструкції, які завантажуються лише після фактичного запуску skill.
• reference/: додаткові файли, які agent читає за потреби. Посилайтеся на них із SKILL.md і залишайте посилання однорівневими, оскільки файл, на який посилається інший referenced file, часто читається лише частково.
• scripts/: файли, які agent виконує, а не читає. До контексту додається лише їхній вивід, тому скрипт на 300 рядків майже не збільшує його обсяг.

Розташування каталогу визначає, хто матиме доступ до skill.

• .claude/skills/<name>/SKILL.md у repository: лише цей project; skill також отримають усі, хто клонує repository.
• ~/.claude/skills/<name>/SKILL.md: усі project на вашому комп’ютері, але не на комп’ютерах інших користувачів.
• <plugin>/skills/<name>/SKILL.md: постачається всередині plugin і доступний усюди, де цей plugin увімкнено.

Створіть skill за допомогою mkdir -p .claude/skills/nginx-config-changes і запишіть файл. Claude Code відстежує ці каталоги, тому зміни наявного skill набувають чинності в поточній сесії. Якщо під час запуску сесії каталогу skills верхнього рівня ще не існувало, для його створення потрібен перезапуск: на момент початку сесії не було каталогу, за яким можна було б стежити.

Поле description — найважливіший рядок у файлі

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

Пишіть опис у третій особі. Варіант "Tests and reloads nginx safely" підходить. Варіант "I can help you with nginx" — ні, оскільки цей текст вставляється в системний промпт, де форма від першої особи сприймається як висловлювання моделі про себе.

Зазначте в ньому дві речі: що робить навичка та за якої умови вона застосовується. Спочатку вкажіть найважливіший варіант використання, оскільки Claude Code обрізає запис у переліку на позначці 1,536 символів. Є необов’язкове поле when_to_use для додаткових фраз-тригерів і прикладів запитів. Воно додається до опису в межах того самого обмеження.

Потім використовуйте слова, які ви справді вводитимете. description: Helps with nginx нічого не зіставляє, оскільки ніхто не вводить фразу "helps with". Наведена вище версія містить /etc/nginx, server block, reverse proxy і TLS (transport layer security) certificate path — приблизно той словник, який буде в будь-якому запиті, що має активувати цю навичку.

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

Зберігайте тіло коротким, оскільки воно залишається в контексті

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

Anthropic рекомендує обмежувати SKILL.md 500 рядками та переносити деталі в окремі файли. Компресія контексту пояснює, чому це число не випадкове. Коли діалог стискається для звільнення контексту, Claude Code повторно додає останній виклик кожного skill, зберігає лише перші 5,000 токенів кожного та заповнює спільний бюджет у 25,000 токенів, починаючи з skill, який викликали останнім. Довгий skill буде обрізано посередині. Кілька довгих skill повністю витісняють один одного.

Тому пишіть лише те, чого модель ще не знає. Вона знає, що таке nginx і що робить reverse proxy. Вона не знає вашого локального правила щодо reload над restart, і саме це правило є єдиною причиною існування цього файлу.

Якщо skill вказує агенту запустити скрипт, що входить до комплекту, зазначте шлях за допомогою ${CLAUDE_SKILL_DIR}, щоб він коректно визначався незалежно від місця встановлення skill, і попередньо дозвольте ту саму команду, щоб виконання не зупинялося через запит дозволу.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

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

Як довести, що skill спрацьовує

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

1. Запустіть нову сесію з claude у проєкті.
2. Сформулюйте запит так, як зробили б у звичайний робочий день, власними словами, не називаючи skill.
3. Перевірте, чи відбулося викликання. Якщо skill не спрацьовує, виправте опис. Вміст поки що не є проблемою.
4. Викличте його вручну за допомогою /nginx-config-changes як контрольну перевірку. Якщо під час ручного викликання поведінка правильна, а під час запиту — неправильна, це підтверджує проблему з тригером, а не з інструкціями.
5. Виконайте той самий запит із вимкненим skill і порівняйте дві відповіді. У меню /skills виділіть skill, натискайте Space, щоб перемкнути його стан на off, а потім натисніть Enter для збереження. Це додає запис skillOverrides до .claude/settings.local.json. Після завершення знову натисніть Space, щоб перемкнути стан на on.
6. Напишіть кілька запитів, які не повинні запускати skill, і перевірте, що він не реагує на них.

Щоб автоматизувати цей цикл, встановіть plugin skill-creator з офіційного marketplace.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Якщо у виводі встановлення зазначено Run /reload-plugins to activate., виконайте цю команду. Потім попросіть Claude оцінити skill за його назвою. Plugin зберігає тестові випадки в evals/evals.json у каталозі skill і запускає кожен випадок у власному subagent, тому кожен запуск починається з чистого контексту. Після цього plugin записує порівняння with-skill і without-skill. Саме це є коректним показником: покращення відсотка успішних проходжень, виміряне з урахуванням кількості токенів і часу, які витрачає skill.

Режим відмови: skill не запускається

Ви вводите запит, агент виконує стару неправильну дію, а рядок skill не з’являється. Перевірте наведені нижче причини по черзі.

• В описі зазначено, що робить skill, але не вказано, коли його потрібно використовувати. Тому жодна частина вашого запиту з ним не збігається.
• В описі не використовуються слова, які ви вводите. Якщо ви пишете «nginx», в описі має бути слово nginx.
• У frontmatter задано disable-model-invocation: true. Це повністю вилучає опис із контексту моделі, тому викликати skill можете лише ви за допомогою /name.
• Glob-вираз paths у frontmatter обмежує активацію файлами, що відповідають цьому шаблону, а файл, з яким ви працюєте, йому не відповідає.
• Skill розташований у вкладеному каталозі .claude/skills/ нижче від початкового каталогу. Такі skill завантажуються лише після того, як агент прочитає або змінить файл у цьому підкаталозі. До цього моменту skill недоступний.

Несправний сценарій: skill запускається постійно

Протилежна проблема виникає, коли опис настільки широкий, що skill запускається для непов’язаних завдань. Умова «Use when working on the server» відповідає майже на будь-який запит у репозиторії сервера. Після цього його вміст завантажується для завдань, у яких він не допоможе, і залишається в контексті до кінця сеансу.

Звузьте опис до умови, яка справді має значення, і вкажіть файли або команди, яких він стосується. Додайте glob paths, якщо skill застосовується лише до певних файлів. Для дій із побічними ефектами, наприклад deploy або commit, задайте disable-model-invocation: true і запускайте його самостійно за допомогою /name, щоб агент не вирішував сам, що настав відповідний момент для deploy.

Режим відмови: навичка має бути у файлі правил

Файл правил, наприклад CLAUDE.md або AGENTS.md, завантажується на початку кожного сеансу й застосовується до кожного завдання. Тіло навички завантажується лише тоді, коли навичка активується. Визначальним є охоплення. Факт, актуальний для кожного завдання в репозиторії, наприклад використовуваний менеджер пакетів, має бути у файлі правил. Процедура, яка застосовується лише до невеликої частини завдань, наприклад наведене вище правило для nginx, має бути в навичці. У дні, коли ніхто не редагує nginx, вона не створює жодних витрат.

Справжня помилка — розмістити інструкцію в обох місцях. Дві копії поступово розходяться, і коли агент виконує неправильну дію, неможливо визначити, за якою саме копією він діяв. Для кожної інструкції оберіть одне місце зберігання. межа між навичками, MCP-серверами та файлами правил допомагає розібрати складніші випадки, зокрема ситуації, коли правильним рішенням є MCP (model context protocol) server, який надає агенту новий інструмент, а не нову інструкцію.

Поширюйте навичку, коли вона себе виправдала

Навичку, яка витримала тиждень реальної роботи, варто додати до репозиторію. Проєктні навички в .claude/skills/ перевіряють так само, як код, і вони надходять разом із репозиторієм. Тому колега, який клонує репозиторій, одразу отримує ваше виправлення без додаткового налаштування. Перенесення навички між репозиторіями без копіювання та вставлення — окреме завдання. Його описано в матеріалі як поширювати навички агента між репозиторіями.

Є важливе зауваження щодо переносимості. Claude Code підтримує довгий список полів frontmatter, але стандарт Agent Skills дозволяє лише шість: name, description, license, compatibility, metadata і allowed-tools. Якщо завантажити навичку до claude.ai або підготувати її для Skills API з будь-яким іншим полем у frontmatter, завантаження завершиться помилкою. Таке поле не буде проігноровано:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Використовуйте лише ці шість полів. Тоді той самий файл завантажуватиметься в Claude Code та в інших системах, які читають цей стандарт. Окреме завдання — написати самі інструкції так, щоб вони працювали з іншою моделлю. Це описано в матеріалі як писати навички, сумісні з будь-якою моделлю.

FAQ

Якої довжини має бути файл SKILL.md?

Обмежте його 500 рядками. Більшість корисних skills мають бути значно коротшими. Текст файлу додається до контексту розмови під час виклику skill і залишається там до кінця сеансу. Тому кожен рядок створює постійні витрати, а не одноразові. Довідкові матеріали великого обсягу перенесіть в окремі файли в каталозі skill і додайте на них посилання з SKILL.md на один рівень вкладеності. Так агент читатиме їх лише за потреби. Вбудовані скрипти виконуються, а не читаються, тому витрати визначаються лише їхнім виводом.

Чому мій skill ніколи не викликається?

Зазвичай причина в описі, оскільки під час ухвалення рішення модель бачить у контексті лише цю частину skill. Переконайтеся, що в описі зазначено, коли потрібно використовувати skill, а не лише що він робить. Також додайте слова, які ви фактично вводите у своїх запитах. Якщо опис правильний, перевірте frontmatter на наявність disable-model-invocation: true, яке повністю приховує skill від моделі, а також glob paths, який обмежує skill файлами, з якими ви не працюєте. Ще одна причина — розміщення skill у вкладеному каталозі .claude/skills/ нижче початкового каталогу. Такий skill завантажується лише після того, як агент прочитає або змінить файл у цьому підкаталозі.

Чи має це бути skill, чи рядок у моєму файлі правил?

Оцініть, для якої кількості завдань це застосовується. Файл правил завантажується в кожному сеансі, тому в ньому мають бути факти, актуальні для кожного завдання, наприклад package manager або правила іменування гілок. Skill завантажується лише після виклику, тому він підходить для процедури, потрібної в невеликій частині завдань. Не записуйте ту саму інструкцію в обидва місця. Дві копії з часом розходяться, і ви втрачаєте можливість визначити, яку саме інструкцію виконав агент.

Як дізнатися, що skill справді допоміг?

Порівняйте результат із базовим варіантом. Зберіть кілька реальних запитів і виконайте кожен у новому сеансі з доступним skill. Потім повторіть їх із вимкненим skill через меню /skills і порівняйте обидві відповіді поруч. Новий сеанс важливий, оскільки розмова, у якій ви писали skill, уже містить ваші пояснення. Через це неповний файл може здаватися завершеним. Plugin skill-creator виконує це порівняння за вас і показує pass rate поруч із вартістю в токенах.

Чи можна використовувати той самий SKILL.md з іншим агентом?

Так, якщо використовувати лише поля, визначені стандартом Agent Skills: name, description, license, compatibility, metadata і allowed-tools. Claude Code приймає набагато більше полів і також підтримує такі можливості тіла файлу, як ін’єкція shell-команд, які інші інструменти не виконують. Завантаження skill із полем, якого немає в стандарті, завершується явною помилкою зі списком дозволених властивостей. Тому заздалегідь визначте, чи skill використовуватиметься лише в Claude Code, чи його потрібно переносити.