У любого агента, которому даёшь большую задачу, есть общая болезнь: чем длиннее контекст, тем хуже он держит собственные правила. В начале сессии он аккуратен, к середине забывает половину ограничений, к концу выдаёт то, что в первом сообщении сам обещал не делать. Для одноразового вопроса это неважно. Для задачи, которая идёт через десяток шагов и на каждом должна соблюдать одни и те же требования, это стена.

Я потратил некоторое время на то, чтобы собрать систему скиллов для Claude Code, которая эту стену обходит. Не более умным агентом, а раскладкой: что грузится в контекст и когда, кто проверяет результат и как эта проверка сообщает о своих пределах. Получился плагин из девяти скиллов, набора всегда активных правил и сабагента-ревьюера. Статья про внутреннюю механику. Что именно система знает о предметной области, пересказывать не буду — начинка тут менее интересна, чем организация.

Репозиторий, если хочется сразу в код: github.com/ShyDamn/synapsea-web-skills.

Что такое скилл в Claude Code и в чём была проблема

Скилл в Claude Code — это папка с файлом SKILL.md, у которого во фронтматтере есть name и description. Агент видит только description всех доступных скиллов, и когда задача под него подходит — подгружает тело скилла в контекст. Идея та же, что у справочника: не держать всё в голове, а открывать нужную главу в нужный момент.

Проблема начинается, когда справочник большой. Если сложить всё, что система должна знать о сборке сайта — типографику, работу с цветом, сетку, моушн, оптимизацию, SEO, бэкенд, безопасность — в один гигантский скилл, получится файл на тысячи строк. Он либо не влезет в разумный бюджет контекста, либо влезет и вытеснит собой саму задачу: агент будет помнить все правила и забывать, что вообще делает.

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

Три уровня: правила, скиллы, ссылки

Я разложил систему на три слоя по частоте использования.

Всегда активный слой — правила. Есть вещи, которые должны действовать на каждом шаге независимо от того, какой скилл сейчас в работе. Это rules/website-quality.md, файл с жёсткими ограничениями на всю работу в проекте. Не «прочитай, когда дойдёт», а «держи в голове всегда». Плюс CLAUDE.md в корне — короткая точка входа, которая говорит агенту: для любой задачи «собери сайт» начинай с оркестрирующего скилла, иди по фазам, не пропускай, делегируй финальный аудит ревьюеру. Буквально несколько строк, вся тяжесть вынесена в скиллы.

Слой по требованию — сами скиллы. Девять штук, каждый под свою область: оркестратор, дизайн-основы, моушн, полиш-контроль, вертикальные плейбуки, SEO, бэкенд-интеграции, генерация ассетов, security-проход. Каждый грузится, только когда его description совпал с текущей задачей. Пишешь анимацию — подтянулся моушн-скилл; трогаешь бэкенд — подтянулся бэкенд-скилл; до тех пор их в контексте нет.

И слой глубокой детали — ссылки. Тут ключевой приём. Сам SKILL.md я держу тонким: он описывает подход, решения, порядок действий, но не вываливает всю конкретику. Глубина лежит в папке references/ рядом со скиллом, отдельными файлами. Скилл лишь указывает: за подробностями по такому-то вопросу — в такой-то файл. Агент открывает reference, только если реально дошёл до этого вопроса.

На практике это выглядит так. Моушн-скилл — это SKILL.md плюс семь файлов в references/: паттерны на CSS, скролл-эффекты, сложные приёмы, 3D, оптимизация и так далее. Когда агент просто добавляет hover-эффект, ему хватает тонкого SKILL.md. Когда доходит до тяжёлой скролл-сцены — тогда и открывает соответствующий reference. Файл про 3D не попадает в контекст, пока в брифе не появилась 3D-сцена. Дизайн-скилл устроен так же: тонкий верхний файл и отдельные references по типографике, цвету, сетке.

Это то, что называют progressive disclosure: контекст наполняется послойно, по мере того как задача требует деталей, а не грузится целиком авансом. За счёт этого система остаётся работоспособной на длинной дистанции. В каждый момент в контексте лежат общие правила (немного), один-два активных скилла и, может быть, один открытый reference. Не весь справочник разом.

Чтобы всё это не осталось абстракцией — вот что система собирает на выходе. Прогнал пайплайн на нейтральном брифе: лендинг вымышленного домашнего бэкап-бокса под сбор листа ожидания. Три слова брифа — инженерно, спокойно, надёжно; из них вывелись петролевая палитра, характерный display-шрифт и сигнатура — живая панель статуса бэкапа вместо дежурной «большой цифры».

Исходники целиком (tokens.css, компоненты, скрипт) — в репозитории, в папке examples/.

Оркестратор: как задача идёт через фазы

Один из девяти скиллов — центральный, website-build-workflow. Он не делает работу сам, а ведёт задачу по фазам и в нужные моменты передаёт управление другим скиллам.

Механика простая. Оркестратор описывает последовательность фаз от разбора задачи до финальной сдачи. На каждой фазе он явно указывает, какой скилл прочитать перед тем, как что-то делать: перед вёрсткой — дизайн-основы, перед анимацией — моушн, перед объявлением работы законченной — полиш-контроль. И ставит ворота между фазами: с известными провалами в текущей фазе в следующую не входить.

По сути это диспетчеризация, а не линейный скрипт. Оркестратор ничего не знает про типографику или моушн — он знает порядок и кому делегировать. Предметное знание живёт в маленьких сфокусированных скиллах, а логика последовательности в одном месте, а не размазана по всем девяти.

Отдельно оркестратор в самом начале запускает то, что я назвал capability-check — проверку доступных инструментов. О ней ниже, это кусок, которым я доволен.

Сабагент-ревьюер, который честно говорит «не проверял»

Самая интересная, на мой взгляд, часть — сабагент design-reviewer.

Claude Code позволяет описать отдельного агента: своя инструкция, свой ограниченный набор инструментов. Мой ревьюер имеет доступ только к чтению файлов и поиску (Read, Grep, Glob, Bash). Править он не может ничего, только смотреть и выносить вердикт. Его задача — после сборки пройтись по результату и оценить его по осям качества, с указанием конкретных мест в коде.

Но самое ценное в нём не оценка, а честность про её пределы.

Часть осей ревьюер проверяет чтением кода: есть ли единый источник токенов, не превышено ли число шрифтов, соблюдены ли ограничения. А производительность и визуальный результат из кода не проверяются в принципе — нужен настоящий браузер, скриншоты, замеры. И здесь заложено правило, которое я считаю принципиальным: если браузерного инструмента в окружении нет, ревьюер обязан пометить такие оси как unverified (no browser tool) и не имеет права выставлять по ним оценку из чтения кода.

Ровно на этой развилке агентные системы обычно и врут. Агенту свойственно выдавать правдоподобную оценку там, где он ничего не измерял. «Производительность хорошая» — на основании чего? Если замеров не было, это выдумка, которая звучит уверенно. Мой ревьюер в такой ситуации обязан написать «не проверял, потому что нечем».

Поэтому его вердикту можно доверять. Когда он говорит «производительность в порядке», значит замеры через подключённый браузер реально прогонялись. Когда инструмента нет — ты видишь честное unverified и знаешь, что этот участок надо смотреть руками. Ложного ощущения проверенности система не создаёт.

Конкретнее, как это собрано. Ревьюер описан отдельным файлом с фронтматтером, где явно ограничен набор инструментов:

---
name: design-reviewer
description: Reviews a built website against the quality system —
  tokens, typography, grid, hierarchy, motion restraint, polish,
  performance gates. Delegate after any build phase or before delivery.
tools: ["Read", "Grep", "Glob", "Bash"]
---

tools без права записи — сознательное решение: ревьюер физически не может по-тихому подправить код и поставить себе галочку. Дальше в его инструкции зашита развилка по верификации:

Если браузерный инструмент или dev-сервер доступен — сделай скриншоты ключевых секций и прогони замеры: оси производительности и визуала считаются ПРОВЕРЕННЫМИ. Если недоступен — помечай эти оси как unverified (no browser tool), никогда не оценивай их из чтения кода, и порекомендуй подключить браузерный инструмент.

На выходе не «выглядит хорошо», а таблица-скоркард: ось, оценка, главная проблема, ссылка на конкретное место файл:строка. Отдельно список блокеров, отдельно «список на вырезание» (senior-ревью убирает больше, чем добавляет), отдельно три улучшения с наибольшим рычагом. И вердикт по трёхбалльной шкале: SHIP / FIX-THEN-SHIP / REWORK, причём сборка на 95% готовности — это всегда FIX-THEN-SHIP, никогда SHIP.

Каждое из трёх ограничений закрывает свой обходной путь: исправить самому нельзя (нет прав на запись), соврать про непроверенное нельзя (обязан пометить unverified), округлить «почти готово» вверх нельзя (95% ≠ SHIP по правилу).

Capability-check: агент инвентаризирует инструменты до начала работы

Второй кусок, которым доволен, — протокол проверки возможностей в скилле генерации ассетов.

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

У меня протокол устроен иначе. В самом начале, до того как что-то строить, агент инвентаризирует, что ему реально доступно: какие внешние сервисы подключены, какие ключи есть. Сопоставляет с тем, что нужно для задачи. И одним сообщением докладывает пробелы вместе с тем, чем закроет каждый. На практике сообщение выглядит примерно так:

Для этого брифа нужны: hero-изображение (есть генератор картинок ✓), 3D-модель (нет инструмента для 3D — подключи или беру примитивы движка), видео-луп (нет ключа видео-генерации — дай ключ или заменю CSS-анимацией).

Три пункта, по каждому — что нужно, есть ли оно, и чем закрою, если нет. Пользователь читает это до того, как система начала строить, и может либо подключить недостающее, либо осознанно согласиться на запасной путь.

Ключевое правило — деградировать явно, никогда молча. Каждая недостающая возможность превращается в задокументированный запасной вариант и пометку в передаточной записке. Не «шаг тихо пропущен», а «шага не было, вот причина, вот чем заменил». Механически это зашито в правила: в матрице ассетов у каждой потребности есть основной путь и явный фолбэк. Hero-картинка деградирует до CSS-градиента с зерном, 3D-модель до примитивов движка, видео до скролл-анимации на канвасе, озвучка просто опускается — звук никогда не несёт критической нагрузки. Пользователь всегда видит реальную картину возможностей, а не отполированный результат, за которым скрыто, что половину задуманного система сделать не смогла и умолчала.

Рядом лежит docs/TOOLING.md — манифест того, какие внешние инструменты система умеет использовать и что каждый даёт, разложенный по приоритету. Ни один не обязателен: протокол проверки как раз для того, чтобы система работала и в урезанном окружении, честно сообщая, чего в нём не хватает.

Верификация технических деталей против устаревания

Последнее, на чём остановлюсь, — дисциплина проверки самих технических рецептов.

Любая система, которая держит в себе конкретные фрагменты работы с внешними библиотеками, обречена устаревать. API меняются, вчерашний правильный вызов сегодня выдаёт предупреждение, а послезавтра ошибку. Модель, которая помнит библиотеку по состоянию на свой срез обучения, легко выдаёт синтаксис, который уже не актуален.

Поэтому в манифесте инструментов отдельно заложена опора на Context7 — доступ к актуальной документации библиотек прямо во время работы. Технические детали, которые попадали в скиллы, я сверял с текущими источниками, а не оставлял по памяти. Там, где рецепт завязан на библиотеку с подвижным API, важно не «помнить, как было», а иметь способ проверить, как есть сейчас. Устаревание это не убирает полностью, но переводит систему из режима «доверяй памяти модели» в режим «проверяй по актуальному источнику», и разница в надёжности между ними ощутимая.

Что из этого можно забрать себе

Если убрать конкретику моей системы, остаётся немного, но каждое из этого переносится в любой набор скиллов для Claude Code.

Резать знание на три слоя по частоте: всегда активные правила, скиллы по требованию и глубокая детализация в references, которая грузится только при реальной необходимости. Именно эта раскладка держит систему рабочей на длинной задаче, а не какой-то особо умный промпт.

Держать SKILL.md тонким. Тело скилла — подход и ссылки, детали открываются послойно. Оркестратор при этом — диспетчер, а не исполнитель: один скилл знает порядок и кому делегировать, предметное знание живёт в маленьких сфокусированных скиллах.

И главное для меня — честная деградация вместо тихого провала, в обоих местах сразу: unverified у ревьюера вместо выдуманной оценки и явный отчёт о пробелах в capability-check вместо молчаливого пропуска шага. Агент, который умеет сказать «я этого не проверял» и «этого инструмента у меня нет», надёжнее агента, который всегда выдаёт уверенный результат. Первому можно верить там, где он уверенность всё-таки выражает.

Это первая из двух статей. Здесь я разбирал, как система организована. В следующей возьму одну узкую техническую область — 3D на вебе — и разберу её вглубь: движки, реальную оптимизацию сцен, где именно упирается производительность на слабых устройствах. Уже не про архитектуру, а про то, что под капотом самой тяжёлой части фронтенда.