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. Отдели facts от assumptions.
5. Верни TASK_SPEC.md без начала implementation.

Здесь важна не конкретная служебная переменная — её имя в зависимости от версии может отличаться. Важен сам принцип: 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. Supporting files и плохой SKILL.md

У многих на этом этапе возникает очень понятный соблазн: раз skill должен быть умным — запихнём в SKILL.md всё. Шаблон, два примера, справочные заметки, пояснение архитектуры, пол-энциклопедии по проекту. И файл превращается в роман, который страшно открывать без перекуса. Это не сила, а сигнал: skill спроектирован неаккуратно.

Supporting files нужны ровно для того, чтобы отделить процедуру от материалов. Сам 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. Но тут важно не заиграться: если supporting files разрослись так, что без археолога и лупы skill не открыть, — вы снова ушли в избыточность. Есть хорошее практическое правило: раздувшийся SKILL.md редко значит, что skill поумнел. Обычно — что материалы не разложены по местам.

4. Как усилить issue-analysis для Commerce OS

Возьмём минимальный issue-analysis: он уже умеет принять issue, собрать TASK_SPEC.md и не лезть в реализацию. Этого достаточно, чтобы навык заработал. Но в живом проекте быстро выясняется: одной инструкции мало — без шаблона, примеров и явных сигналов 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 quality: рабочий артефакт

Последний важный вопрос этой лекции звучит довольно приземлённо: как понять, что skill действительно хороший? Написать уверенный SKILL.md быстро, но хороший skill определяется не интонацией, а тем, насколько он повторяемый, понятный и экономный по контексту. На качество полезно смотреть как на инженерный review, а не как на литературную оценку: не «красиво ли написано», а «получит ли другой человек и другая сессия предсказуемый результат».

Ниже — компактная таблица для проверки, которая хорошо работает перед коммитом 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 становится командным артефактом уже на другом слое.