Як написати власну agent skill на основі помилки

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

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

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

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

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

Ось типова помилка на реальних серверах. Ви просите агента додати блок 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

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 символів, лише lowercase-літери, цифри та дефіси; слова claude або anthropic використовувати не можна. У personal або project skill це лише display label. Команда, яку ви вводите, походить із назви каталогу, тому цей skill викликається командою /nginx-config-changes.
• description: опис призначення skill і умов його використання, до 1,024 символів. Цей рядок виконує основну роботу, а наступний розділ присвячено лише цьому.
• Тіло: інструкції, які завантажуються лише після фактичного запуску skill.
• reference/: додаткові файли, які агент читає на вимогу. Посилайтеся на них із SKILL.md і обмежуйте вкладеність посилань одним рівнем, оскільки файл, на який посилається інший підключений файл, часто читається лише частково.
• scripts/: файли, які агент виконує, а не читає. У контексті враховується лише їхній вивід, тому script на 300 рядків майже не збільшує витрати.

Skill розширюється до повної структури, коли поведінку, яку він має виправити, складно змінити без додаткових правил. unlazy skill використовує цей простір для Depth Tree, набору gate-файлів і контракту PLAN.md, щоб агент не оголошував роботу завершеною, поки цілі гілки залишаються необробленими.

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

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

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

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

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

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

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

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

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

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

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

Anthropic рекомендує обмежувати SKILL.md обсягом до 500 рядків і переносити докладну інформацію в окремі файли. Механізм compaction показує, чому це число не випадкове. Коли розмову стискають, щоб звільнити контекст, 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 не спрацьовує, виправте опис. Тіло 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, тому кожен запуск починається з чистого контексту. Потім він записує порівняння with-skill і without-skill. Це показник, якому можна довіряти: покращення частки успішних тестів, виміряне з урахуванням кількості токенів і часу, які потребує skill.

Skill також може містити власне підтвердження, а не передавати його окремому запуску eval. Саме так працює skill Old Coder: він змушує агента повертати звіт із доказами, який ви можете самостійно запустити повторно.

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

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

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

Режим відмови: навичка спрацьовує постійно

Протилежна проблема виникає, коли опис надто широкий, і навичка спрацьовує для завдань, які з нею не пов’язані. «Використовуйте під час роботи із сервером» відповідає майже будь-якому запиту в репозиторії сервера. Після цього її вміст завантажується для завдань, яким вона не може допомогти, і залишається в контексті до кінця сеансу.

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

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

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

Справжня проблема виникає, коли інструкцію розміщують в обох місцях. Дві копії поступово розходяться, і коли агент виконує неправильну дію, неможливо визначити, якої саме копії він дотримувався. Для кожної інструкції потрібно вибрати одне місце. Якщо правило вже розміщене рівно в одному місці, але агент усе одно його ігнорує, це інша проблема. Перед перенесенням правила у skill варто перевірити механізм ігнорування інструкції, а не сподіватися, що перенесення усуне проблему. Межа між skills, MCP servers і файлами правил охоплює складніші випадки, зокрема ситуацію, коли правильним рішенням є 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 та в інших системах, які читають цей стандарт. Можливості навички все одно залежать від середовища, у якому завантажується файл, оскільки Cowork працює в ізольованому середовищі Anthropic, а Claude Code — на вашому комп’ютері або VPS, тому навичку для nginx із наведеного вище прикладу варто передати колезі для його робочої копії репозиторію, але вона не має сенсу в sandbox, який не може підключитися до сервера. Написання самих інструкцій так, щоб вони працювали з іншою моделлю, — окреме завдання. Його розглянуто в матеріалі як писати навички, сумісні з будь-якою моделлю.

FAQ

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

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

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

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

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

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

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

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

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

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