Агенти, що самостійно покращуються завдяки навичкам: повторне використання, відбір, ремонт та перевірка.

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

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

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

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

Частину агента, яку можна дійсно покращити

Навичка — це папка. Вона містить файл SKILL.md із інструкціями, а також, за бажанням, скрипти та документацію для посилань. Специфікація Agent Skills визначає стандартну структуру: на початку файлу розміщуються коротка назва та опис. Інженерна команда Anthropic описує навички як спосіб надання універсальним агентам можливості використовувати повторно придатні знання, причому перевагою є те, що процедуру можна покращити без необхідності повної перебудови системи.

У цьому процесі задіяні два окремі етапи. Агент має обрати правильну навичку, а обрана навичка має ефективно керувати виконанням завдань. Виправлення одного етапу не автоматично виправляє інший.

Whetstone надає кожній зі своїх чотирьох навичок одну конкретну функцію:

• dry-promotion зберігає код, придатний для повторного використання.
• skill-audit перевіряє інформацію, яка використовується для вибору навички.

skill-repair пропонує процедурні зміни.

verify-before-return перевіряє результат.

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

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

1. DRY: зберігайте те, що вже спрацювало

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

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

Саме це робить dry-promotion. Він копіює корисний допоміжний скрипт у папку scripts/ функції та переписує інструкції так, щоб скрипт було виконано. Однієї лише збереження файлу недостатньо: хоча функція все ще просить агента написати скрипт, ніщо не вказує йому на вже збережений варіант.

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

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

Це забезпечує стабільну реалізацію, яку можна перевіряти та тестувати. Однак це не робить весь процес написання детермінованим, адже сам субтитр все ще може варіюватися, а програма може вірно повторювати неправильну формулу. Лічильник має визначити, чи враховувати кодові точки Unicode чи видимі символи, а також як ставитися до пробілів та переносів рядків.

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

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

2. Допоможіть агенту обрати правильну навичку

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

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

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

Після аналізу бібліотеки навичок однієї особи, з урахуванням окремого підрахунку дублікатів з однаковою назвою, було отримано таке узагальнення:

383 skills scanned
  missing description           0
  no trigger language         306
  colliding pairs               3
  duplicate names              23
  skills with >=1 defect      306  (79%)

79% — це скорочена версія значення 306 діленого на 383, що дорівнює приблизно 79,9%. Ці описи пройшли невдалу перевірку формулювань, що не є тим самим, що й 306 випадків неправильного використання навички. Сканер перевіряє лише буквальні формулювання-тригери, такі як „використовувати, коли“ чи „коли користувач“. Модель може діяти згідно з описом, у якому відсутні ці слова, а опис із ними все одно може бути занадто загальним для ефективної допомоги. Результат — це список для дослідження, а не показник того, наскільки пошкоджений агент.

Надайте сусіднім навичкам різні завдання

Розгляньмо два реальні описи з двох навичок у тому самому плагіні:

Один з них пропонує себе як експерт зі створення систем генерації з підтримкою пошуку за допомогою векторних баз даних, ембеддингів та складних стратегій пошуку. Інший пропонує себе як експерт з вибору, налаштування та оптимізації векторних баз даних, таких як Pinecone, Weaviate, Chroma, Qdrant та Milvus, для семантичного пошуку та технологій RAG.

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

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

name: vector-database-selection
description: >-
  Compare vector databases against workload, filtering,
  deployment, and operating-cost requirements. Use when
  choosing or replacing a vector store. For retrieval-pipeline
  design with an already chosen store, use rag-pipeline-design.

name: rag-pipeline-design
description: >-
  Design ingestion, chunking, retrieval, reranking, and
  evaluation for a RAG application. Use when building or
  diagnosing a retrieval pipeline. For a standalone vector
  database selection, use vector-database-selection.

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

Складіть проекти запитів до тестування, перш ніж змінювати будь-які формулювання. „Порівняйте сховища векторів для додатку пошуку документів, який працює на власному сервері“ стосується вибору бази даних. „Де мають знаходитися наші ембеддинги? Допоможіть мені вирішити“ — це те саме, сказане іншими словами. „У нас вже є сховище векторів, але пошук не знаходить відповідних абзаців“ належить до діагностики процесу обробки даних.

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

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

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

3. Перетворіть досвід на повторно використовувані інструкції

Виявлення проблеми ставить більш корисне запитання: де має знаходитися виправлення?

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

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

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

Єдине загальне попередження, вставлене у кожен випадок, повністю усуне можливість діагностики.

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

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

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

Коли спільний посібник потребує ремонту

Бібліотека окремої особи — це її власний накопичений безлад, який перевіряється її власним інструментом, тому така сама перевірка була застосована до публічного репозиторію плагінів, яким керує команда з дослідницького програмного забезпечення університету. У цьому знімку було 76 навичок у 12 плагінах.

Прапорці були груповані за плагінами. Сім плагінів отримали прапорці повністю, а один науковий плагін Python мав чотири з п’яти прапорців. Це групування спонукало до пошуку спільних шаблонів та конвенцій, і виявилося, що посібник-джерело є ключовим елементом. У ньому просили «чіткого опису агента та його призначення» та пропонували шаблон-замінник, у якому вказувалося, що робить агент. Там ніколи не запитувалося, коли його використовувати. Тридцять шість елементів були створені відповідно до посібника, проте сам посібник містив помилку.

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

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

4. Перевірка перед передачею

verify-before-return надає навичці критерії прийняття та цикл перегляду. Запис файлу на диск — це лише проміжний крок, і робочий процес все одно має перевірити результат за допомогою доказів, придатних для завдання:

• Для презентації необхідно відтворити її, а потім перевірити на наявність обрізаного тексту, нерозбірливих міток чи елементів, що виходять за межі екрана.
• Для дослідницького звіту потрібно відкрити джерела та перевірити, чи вони підтверджують викладені твердження.
• Для коду слід запустити тести, які перевіряють необхідну поведінку.

Будь-яке твердження про завершення роботи має вказувати на те, що саме було перевірено.

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

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

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

Які тести змінив аудитор

Тести показали, що аудитору довелося розглядати дублікати встановлень та перекриваючіся описи як окремі випадки. Під час першого запуску було виявлено 81 потенційну пару; багато з них стосувалися ідентичних навичок, які знаходилися у різних версіях плагінів у кеші. Аналіз цих пар призвів до виокремлення дублікатів з однаковими назвами з аналізу зіткнень, що зменшило кількість потенційних випадків до 3.

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

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

Оцінка є лише гіпертекстовою методикою: кількість слів, спільних для обох описів, поділена на кількість унікальних слів у кожному з них, причому стандартний поріг становить 0,35. Виключення може виглядати як перекриття, а два описи однієї посади з різною формулюванням можуть пройти непоміченими. Парсер frontmatter також підтримує лише частину формату YAML. Будь-який флаг потребує перевірки людиною перед тим, як його можна буде використати для виправлення.

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

Упаковка не переміщується; знання — так

Метою було зробити whetstone придатним не лише у Claude Code. Розповсюдження формату SKILL.md допомагає досягти частини цієї мети. Проте знання все ще можуть залежати від інструментів, дозволів чи шляхів до файлів, які інший клієнт не надає, а кожен клієнт пакує плагіни по-різному. Стандарт Agent Plugins, документація Claude Code та OpenCode описують ці схеми пакування.

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

Пробування в одному робочому процесі

Не потрібні великі бібліотеки. Виберіть один робочий процес — наприклад, допоміжний елемент, який агент постійно перебудовує, дві навички, які він поєднує, або результат, який ви зазвичай завершуєте вручну. Збережіть одне репрезентативне запитання та його результат для порівняння.

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

Проєкт постачається під ліцензією MIT. Для Claude Code у файлі README наведені команди встановлення:

claude plugin marketplace add cdcore09/whetstone
claude plugin install whetstone@whetstone

Є чотири точки входу: /audit, /promote, /repair та /verify. Використовуйте ту, що підходить для вашого робочого процесу. Під час першої спроби доцільно, щоб він перевірив відповідні файли та запропонував зміни, перш ніж щось буде застосовано.

Щоб дослідити інструмент аудиту без встановлення будь-чого, склонуйте репозиторій та прочитайте файл skills/skill-audit/scripts/audit_skills.py. З верхньої частини репозиторію цей інструмент запускається за допомогою наведеної нижче команди, причому використовується лише стандартна бібліотека Python:

python3 skills/skill-audit/scripts/audit_skills.py ./skills

Замініть ./skills на каталог, який ви хочете перевірити, почавши з невеликої колекції, яку ви розпізнаєте, перш ніж сканувати кеш кожного плагіну на вашому комп’ютері. --json формує структурований звіт, а --threshold 0.25 відображає більш широкий набір перекриваючихся описів.

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

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