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

Автор: AI продукт Аїїнг

Подивилася блог Anthropic команди «Lessons from building Claude Code: How we use skills». Це, мабуть, найглибше практичне резюме про навички, яке я наразі бачила.

Навичка насправді не така складна, але щоб справді зробити її хорошою, я вважаю, це не так просто.

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

Але потім я сама спробувала і зрозуміла, що багато разів це просто не працює.

Бо один стиль навички може містити кілька тисяч або навіть десятки тисяч слів. Як тільки навичка завантажується, контекст займає дуже багато місця. Коли контекст великий, здатність моделі мислити знижується.

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

Ще одна поширена ситуація.

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

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

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

Суть навички — у контекст-інженерії. Коли потрібно вставляти знання у навичку, коли краще розбити на посилання (References), коли писати скрипти, коли використовувати «Gotchas» для обмеження моделі — у цьому є багато досвіду.

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

Якщо хтось хоче глибше вивчити навички, дуже рекомендую прочитати дві статті:

#01 Не писати нісенітниць

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

В Anthropic часто наголошують, що у навичках потрібно писати саме «Gotchas», тобто поширені помилки.

Наприклад:

1. Цю таблицю не можна сортувати за created_at

2. Відповідь staging 200 не означає успіх

3. request_id і trace_id — це одне й те саме

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

Skill = запис досвіду майстрів.

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

#02 Навичка — це насправді контекст-інженерія

Це, мабуть, один із найглибших висновків Anthropic.

Навичка — це не markdown-файл, а папка. Для тих, хто користується навичками, це звучить як дурниця.

Але я останні дні багато думала і зрозуміла: вони саме цим і намагаються передати ідею контекст-інженерії через структуру папки.

Давайте ще раз подивимося на типову структуру навички:

skill/ ├── SKILL.md ├── references/ — детальні описи, API, межі ├── scripts/ — виконувані скрипти ├── examples/ — приклади ├── assets/ — шаблони, зображення, фіксовані матеріали

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

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

Якщо все це звалити у SKILL.md, кожного разу при виклику навички Claude має знову читати цей файл.

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

Альтернатива від Anthropic — зовсім інший підхід.

SKILL.md — це швидше навігаційна сторінка. Її завдання — підказати моделі, що при помилках Stripe потрібно звернутися до references.

Якщо потрібно подивитися історичні кейси — у examples. Якщо потрібно виконати діагностику — запустити скрипти з папки scripts. А для генерації звіту — використати шаблони з assets.

Цей процес поступовий і поступово відкриває всю інформацію.

Нижче наведена ілюстрація, яку дуже рекомендую зберегти.

#03 Використовуйте скрипти якомога більше

Не варто витрачати обмежений контекст і здатність мислити моделі на повторну роботу. Це краще делегувати скриптам.

Наприклад. Багато хто при створенні навичок пише так:

1. Запит даних реєстрації; 2. Запит платіжних даних; 3. Обчислення конверсії; 4. Аналіз причин аномалій.

Такий підхід цілком прийнятний. Модель може виконати, але кожного разу вона має повторювати весь процес з нуля.

Запити, обробка даних, врахування крайніх випадків — усе це повторювані задачі.

Оскільки ці можливості вже багато разів підтверджені, навіщо знову винаходити колесо? Краще надати конкретний скрипт.

Крім того, використання скриптів робить виконання навички більш точним і економить токени.

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

Закріпивши ці можливості, Claude зможе працювати на основі досвіду, а не з нуля щоразу.

Тому я все більше переконуюсь, що Instructions і Scripts у навичках вирішують різні рівні задач.

Instructions — це досвід і судження, Scripts — це здатність і виконання.

Наприклад, у навичці для вирішення проблем із платежами може бути таке:

Якщо Stripe повернув 200, не слід автоматично вважати платіж успішним, потрібно додатково перевірити таблицю payment_events.

Це — Instructions, бо це досвід. А функція check_payment_events() — Script, бо це здатність виконати дію.

Якщо є лише Script, модель знає, як зробити запит, але не знає, чому саме.

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

#04 Опис — це швидше правила маршрутизації

Багато хто неправильно пише опис навички.

Бо зазвичай описують функціональні можливості. Наприклад: PR Management Skill допомагає слідкувати за статусом PR, вирішувати проблеми з CI, автоматично зливати.

Але проблема в тому, що модель не шукає навичку за функцією. При запуску Claude Code він спершу сканує назви та описи всіх навичок.

І вже на основі цього визначає, яку навичку потрібно завантажити.

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

Опис виконує роль маршрутизатора для навички.

У реальному світі дуже мало хто просить допомоги у виклику інструменту управління PR. Більше ймовірно, що скажуть: «Зверни увагу на цей PR, або CI зламався».

Тому хороший опис має передавати саме намір користувача, а не просто перераховувати функції.

Я навіть пропоную простий спосіб перевірки.

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

Якщо ні — потрібно ще доопрацювати.

#05 Управління та розповсюдження навичок

Ще один важливий аспект — управління навичками.

Коли один користувач створює кілька навичок, це просто. Написати кілька, підтримувати, оновлювати — і все.

Але я впевнена, що більшість команд з часом стикнуться з питанням.

Коли навичок стає десятки або сотні, як їх правильно керувати? Як оновлювати? Як розподіляти між членами команди?

Досвід Anthropic у цьому дуже цінний.

У маленьких командах навички зазвичай йдуть разом із кодом. В папці проекту .claude/skills. Всі ділять одну колекцію навичок і один підхід до роботи.

Але з ростом кількості навичок виникає нова проблема.

При запуску Claude Code він сканує всі назви та описи навичок і визначає, яку викликати. Чим більше навичок, тим дорожче маршрутизація.

Саме тому Anthropic почали створювати Marketplace. Але цікаво, що вони роблять із управлінням Marketplace.

Багато компаній у такій ситуації створюють процес затвердження. Хто створив навичку — подає заявку; після перевірки вона потрапляє до офіційної бібліотеки.

Ми теж так робили, але дуже обмежено. Просто для управління.

Anthropic ж підходять інакше.

Нові навички спочатку поширюють у вузькому колі. Колеги самі встановлюють, тестують.

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

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