Dynamic context і якість skill

1. Skill живе не тільки в тексті

Навіть акуратний SKILL.md легко почати сприймати надто спрощено: ніби це просто prompt, який переїхав у файл. Ззовні виглядає пристойно, але по суті ви все так само залежите від того, чи вдало сформулювали завдання, чи додали файли, чи не забули половину контексту. Такий skill — папірець на моніторі: «не забудьте перевірити тести». Корисно, але це не інженерна система.

Проблема в тому, що звичайний prompt майже завжди статичний: він працює з тим, що ви вручну поклали в повідомлення. Забули додати issue, приклад TASK_SPEC.md, план перевірки — модель імпровізує. А імпровізація в інженерній роботі романтична лише до першого дивного diff.

Skill сильніший не тому, що він «довший», а тому, що в нього зʼявляється структура. Prompt каже: «зроби щось схоже на правильне». Skill: «ось процедура, ось шаблон, ось приклади, ось обмеження, ось очікуваний артефакт». Різниця — як між «звари щось смачне» і «ось рецепт, ось продукти, ось форма подачі, і, будь ласка, не підірвіть кухню».

Нижче різницю видно наочніше:

У контексті нашого Workflow Kit це особливо помітно на skill issue-analysis. Поки він живе лише як текст усередині SKILL.md, він слабкий: заплутається, коли issue зміниться, проєкт підросте, прийде новий розробник — або коли через два тижні ви самі глянете й подумаєте: «а що я мав на увазі під “зібрати evidence”?» Тому хороший skill майже ніколи не замикається на одному файлі. Він живе як маленька система: коротка інструкція плюс джерела правди поруч.

2. Dynamic context: skill працює за сигналами

Ось тут і зʼявляється головний герой лекції — dynamic context. Якщо зовсім просто, це контекст, який skill бере з поточного завдання та стану проєкту, а не з «фонового знання» моделі. Текст issue, список файлів, фрагмент коду, результат grep, поточний diff, вивід тестів, шаблон артефакту. Не «згадай, як зазвичай буває», а «подивись, що відбувається просто зараз».

Це дуже важливий перехід. Коли skill працює тільки за інструкцією, він залишається красивим, але глухим. Коли він працює за динамічними сигналами — стає адаптивним. Тому один і той самий issue-analysis придатний і для бага з сортуванням refund-запитів у Commerce OS, і для дубльованої пагінації, і для локального refactor: змінюється вхід і evidence, а не процедура. Для новачка це найлегше уявити так: skill — не заготовлена відповідь, а спосіб ставити правильні запитання до поточного завдання.

Розгляньмо це на прикладі issue з Commerce OS. Припустімо, у підтримку прилітає проблема: запити на повернення в inbox ідуть у неправильному порядку. На голому prompt «прочитай issue і напиши task spec» модель вигадає половину деталей. А skill бере issue як аргумент, дивиться на шаблон TASK_SPEC.template.md, через пошук у проєкті витягує кілька релевантних файлів — і в нього зʼявляється опора.

Схема такого потоку виглядає так:

flowchart TD
    A[Текст issue] --> B[Аргументи skill]
    B --> C[Пошук релевантних файлів]
    C --> D[Збір evidence]
    D --> E[Шаблон TASK_SPEC]
    E --> F[Готовий TASK_SPEC.md]

У живому skill це можна зафіксувати дуже коротко. Наприклад, так:

## Вхід
- issue: $ARGUMENTS

## Дії
1. Прочитай issue.
2. Знайди 2–5 найрелевантніших файлів.
3. Заповни templates/TASK_SPEC.template.md.
4. Відокрем факти від припущень.
5. Поверни TASK_SPEC.md без початку реалізації.

Тут важлива не конкретна службова змінна — її імʼя залежно від версії може відрізнятися. Важливий сам принцип: skill не висить у повітрі, а отримує явний вхід.

Припустімо, він додатково запускає пошук у коді. Навіть такий маленький сигнал уже цінніший за здогад:

$ grep -R "refund" support/ orders/
support/inbox/RefundRequestSorter.java
support/inbox/RefundQueueService.java
orders/api/RefundController.java

Ось це й є dynamic context у хорошому сенсі слова: не «модель знає, що refund зазвичай поруч із orders», а «ми побачили конкретні файли, ймовірно повʼязані з проблемою». Далі skill або посилається на них в артефакті, або позначає як candidate files для перевірки.

Тут же спливає ще одна важлива думка: dynamic context не означає «засунемо в skill весь репозиторій на всяк випадок». Зайвий контекст не робить модель мудрішою — він швидше її втомлює. Увесь codebase на старті, логи за тиждень, три старі обговорення з чату — не dynamic context, а контекстна каша. Хороший skill підіймає тільки той сигнал, який потрібен зараз: для issue-analysis це зазвичай issue, 2–5 файлів, шаблон і, можливо, один схожий example.

3. Допоміжні файли і поганий SKILL.md

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

Допоміжні файли потрібні саме для того, щоб відокремити процедуру від матеріалів. Сам SKILL.md короткий: коли використовувати, що подати на вхід, що робити, що видати, чого не робити. Решта — поруч, як у issue-analysis:

workflow-kit/.claude/skills/issue-analysis/
  SKILL.md
  templates/
    TASK_SPEC.template.md
    EVIDENCE_LOG.template.md
  examples/
    refund-sorting-bugfix.md
    pagination-duplicates.md
  references/
    commerce-risk-notes.md

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

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

# TASK SPEC

## Мета
...

## Обсяг змін
...

## Нецілі
...

## Критерії приймання
...

## Перевірка
...

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

Приклади теж корисніше тримати поруч, ніж вставляти всередину. Один показує хороший bugfix-спек для refund sorting, другий — як оформити issue про дублювання в пагінації. Завдяки цьому skill перестає бути абстрактним: він не каже «робіть добре», він показує «ось так виглядає хороший вихідний артефакт у нашій команді».

Якщо вам потрібен додатковий збір сигналу, додайте невеликий допоміжний скрипт: наприклад, він збирає кандидатів на файли за ключовим словом issue. Але тут важливо не захопитися: якщо допоміжні файли розрослися так, що без археолога й лупи skill не відкрити, — ви знову пішли в надмірність. Є хороше практичне правило: роздутий SKILL.md рідко означає, що skill став розумнішим. Зазвичай — що матеріали не розкладені по місцях.

4. Як посилити issue-analysis для Commerce OS

Візьмімо мінімальний issue-analysis: він уже вміє прийняти issue, зібрати TASK_SPEC.md і не лізти в реалізацію. Цього досить, щоб skill запрацював. Але в живому проєкті швидко зʼясовується: однієї інструкції замало — без шаблону, прикладів і явних сигналів skill знову імпровізує.

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

Використовуй templates/TASK_SPEC.template.md.
Візьми issue з аргументів.
Знайди лише релевантні файли, а не весь проєкт.
Посилайся на evidence, а assumptions позначай явно.
Поверни заповнений TASK_SPEC.md і список відкритих запитань.

Зверніть увагу, як змінюється характер skill: сила не в зайвому тексті, а в тому, що навичка знає, де лежить шаблон, які файли перевірити, як не переплутати факт із здогадкою. Сьогодні issue про RefundRequestSorter — підтягнеться один набір кандидатів. Завтра дублювання в пагінації orders — інший. Процедура та сама, змінюється контекст. Саме цим reusable workflow і відрізняється від довгого красивого prompt: prompt тримає занадто багато у вашій голові, skill фіксує це поруч із собою.

Тут же корисно памʼятати про версійну стійкість — те саме застереження про версії, що й у попередній лекції: змінюються поля й формат виклику, але влаштування skill не змінюється — аргументи, допоміжні файли, dynamic context, контракт результату та обмеження. Опора — у цьому, а не в імені YAML-ключа.

5. Якість skill: робочий артефакт

Останнє важливе запитання цієї лекції звучить досить приземлено: як зрозуміти, що skill справді хороший? Написати впевнений SKILL.md швидко, але хороший skill визначається не інтонацією, а тим, наскільки він повторюваний, зрозумілий і ощадний до контексту. На якість корисно дивитися як на інженерне ревʼю, а не як на літературну оцінку: не «чи гарно написано», а «чи отримає інша людина і інша сесія передбачуваний результат».

Нижче — компактна таблиця для перевірки, яка добре працює перед комітом skill у Workflow Kit:

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

Дуже часта помилка — переплутати «багатий skill» із «роздутим skill». Багатий skill короткий в інструкції, але сильний опорною системою довкола себе. Роздутий skill — це коли все звалено в один файл, а потім автор гордо каже, що він «самодостатній». Самодостатність добра рівно до того моменту, поки друга людина не спробує це ревʼюити. Якщо SKILL.md важить як невеликий роман для відпустки, ревʼю швидко перетворюється на археологічну експедицію.

Ще один хороший тест якості звучить майже побутово: якщо ви повернетеся до skill за місяць, чи зрозумієте ви за хвилину, що він робить, звідки бере дані і що зобовʼязаний повернути? Якщо відповідь «ну, приблизно», skill ще сирий. Якщо відповідь «так, ось вхід, ось шаблон, ось приклади, ось очікуваний результат», значить, у вас уже не просто текст, а підтримуваний артефакт.

Саме в цей момент skill перестає бути красивим іменованим prompt і стає частиною Workflow Kit по-справжньому. Він уже не живе за рахунок вашої памʼяті. Він живе за рахунок структури, актуального контексту й акуратно розкладених допоміжних файлів. А це, якщо говорити без пафосу, і є та точка, де Claude Code перестає бути «чатиком, якому ви в сотий раз пояснюєте одне й те саме», і починає працювати як інженерне середовище, у якому хороші практики можна закріпити, повторити й передати далі.

А коли такий skill перестає бути локальною штукою однієї людини або одного репозиторію, наступне інженерне питання вже не про ще один абзац у SKILL.md, а про упакування, версіонування та поширення. Там reusable workflow стає командним артефактом уже на іншому рівні.