Семь навыков для Claude Code: изоляция в worktree, сервисный слой, доказательства и ревью

Репозиторий michaelshimeles/skills — это семь навыков для Claude Code и один файл AGENTS.md, который связывает их в рабочий процесс. Кода в репозитории почти нет: внутри папок лежат файлы SKILL.md с инструкциями, которые агент подгружает сам, когда описание навыка совпадает с задачей. Плюс несколько вспомогательных скриптов на Python и shell.

Главная идея автор простая. Работа агента без правил превращается в поток правок и обещаний: «я проверил, всё работает». Здесь каждая фаза привязана к своему навыку. Задача начинается в отдельном worktree, код пишется по правилам сервисного слоя, проверка оставляет после себя видео, а выпуск начинается со скриншотов «до и после» и заканчивается чистым ревью.

Что внутри

Как устроен один навык

Каждый навык лежит в своей папке и начинается с SKILL.md. В начале файла — служебный блок с именем и описанием:

---
name: code-structure
description: Use when multiple workflows duplicate the same operational logic,
  when deciding what belongs in actions vs shared services, or when refactoring
  repeated operational blocks across domain flows.
---

Описание — самая важная часть. Именно его агент читает, чтобы решить, подходит ли навык под текущую задачу. Поэтому автор советует писать его от срабатывания: «Use when…», а не с описания того, что внутри. Длинные инструкции выносят в отдельные файлы и ссылаются на них из SKILL.md, чтобы основной файл оставался коротким.

Изоляция: new-feature

Навык new-feature начинается до написания кода. Он требует создать для задачи отдельный worktree и ветку от свежего origin/main и запрещает работать прямо в main:

git fetch origin
git worktree add <worktrees-dir>/<task-name> \
  -b <branch-prefix>/<task-name> origin/main

Папку с worktree нужно держать в .gitignore, чтобы её случайно не закоммитили. Имя задачи — строчные слова через дефис плюс короткий уникальный суффикс, например user-auth-0816a. Если такое имя уже занято, берут другое, а не переиспользуют существующее.

Перед началом навык просит проверить, не заняты ли нужные файлы в других открытых PR: gh pr list и gh pr diff <n> --name-only. Если пересечение есть, агент должен остановиться и спросить, а не начинать работу. Заодно стоит глянуть на незакоммиченные изменения в общих рабочих копиях: там может сидеть другой агент посреди задачи.

Есть важная оговорка. Worktree изолирует только файлы. Порты dev-сервера, общая база данных и lock-файлы остаются общими, поэтому перед доверием ответу с локального порта стоит проверить, что его отдаёт именно ваш процесс (lsof -i :<port>). Конфликты в lock-файлах решают перегенерацией, а не ручным слиянием. Удаляют worktree после мержа PR, и ветку приходится удалять с -D, потому что после squash- или rebase-мержжа обычный -d откажется удалять уже смерженную ветку.

У Claude Code и Cursor есть собственное управление worktree, поэтому для них шаги с ручным git worktree add и remove пропускаются.

Структура кода: code-structure

Навык code-structure отвечает на вопрос, что куда класть. Он требует развести код на два слоя. Actions занимаются доменными правилами: когда что-то делать, проверками прав, переходами состояний и классификацией ошибок. Сервисный слой собирает повторяемую технику: как надёжно выполнить операцию, как поговорить с провайдером, как запустить команду, как проверить готовность.

Правило звучит так: «что этот сценарий значит» остаётся в actions, «как выполнить операцию надёжно» уезжает в сервисный слой.

Функции сервисного слоя пишут как небольшие переиспользуемые блоки, а не как один гигантский метод. Каждая принимает нужные данные явными параметрами, возвращает структурированный результат, не лезет напрямую в базу и не прячет ошибки:

export async function sendWelcomeEmail(params: { to: string; name: string }) {
  const html = `<h1>Welcome ${params.name}</h1>`;
  await emailProvider.send(params.to, "Welcome", html);
}

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

Есть чек-лист переноса: сначала написать сценарий как есть, отметить повторяющиеся куски, вынести только их, заменить одного вызывающего, проверить, и только потом менять остальных. Одновременный рефакторинг всего сразу навык запрещает. Отдельно перечислены анти-паттерны: god service прячет всё управление в одной функции, «дырявый» сервис правит таблицы напрямую, разнобой в API смешивает стиль аргументов и ошибок, а излишнее обобщение вытаскивает логику, которая нужна ровно одному вызывающему.

Доказательства: evidence-driven-testing

Навык evidence-driven-testing заменяет фразу «я проверил» видеозаписью. Агент запускает вложенный скрипт scripts/evidence.py, открывает приложение и проверяет его вручную: кликает, печатает, переходит между экранами. Всё, что видно на записи, и есть сам тест. Скрипт ставит на видео метки времени по ходу проверки, а после остановки вшивает их в evidence.mp4 и собирает report.md с manifest.json.

Сначала навык просит запустить python3 scripts/evidence.py doctor. Команда проверяет, что ffmpeg и ffprobe собраны с libx264 и фильтром ass, и отдельно показывает, какой источник захвата экрана работает на этой машине. Дальше всё зависит от системы:

Wayland на GNOME и KDE таким способом не записывается, и doctor об этом предупреждает. Сырой файл пишется в MPEG-TS, поэтому даже если процесс упал, запись остаётся пригодной.

Без графического окружения навык переключается на другой путь: скриптованные скриншоты и Playwright. Для изменений без интерфейса доказательством становятся измеренные числа, пары вывода и выдержки из логов. Отправка доказательств в PR и тикет идёт через gh, а сам рекордер покрыт смоук-тестом: python3 -m pytest tests/ -q.

Выпуск: before-and-after, greploop и greploop-apps

Навык before-and-after снимает две картинки и превращает их в таблицу | До | После |, готовую для вставки в описание PR. Он управляет CLI-пакетом @vercel/before-and-after и умеет брать на входе два адреса, два готовых файла или смесь обоих вариантов. Флаг --markdown загружает пару снимков и печатает таблицу. Если в контейнере Chrome падает с ошибкой про песочницу, навык предлагает задать AGENT_BROWSER_ARGS="--no-sandbox". Отдельно предупреждено, что сервис загрузки по умолчанию публичный, и для чувствительных снимков нужно указывать свой адрес.

greploop доводит PR до идеального ревью Greptile. Он определяет платформу (GitHub, GitLab или Perforce), находит PR текущей ветки, запускает ревью, разбирает actionable-комментарии, отвечает на них, отправляет правки и запускает ревью снова. По умолчанию цикл повторяется до десяти раз, лимит меняется флагом --max-iterations. Условие успеха жёсткое: оценка 5/5 и ноль нерешённых комментариев.

greploop-apps делает ровно то же самое, но запускает ревью тегом @greptile-apps. Нужен он ровно тогда, когда обычный тег @greptile отвечает отказом из-за размера PR. Если проверка так и не появилась, навык переключается на опрос сводного комментария Greptile.

Текст для человека: unslop

Навык unslop — единственный, который не про код. Он правит текст, который прочитает человек: сообщения коммитов, заголовки и описания PR, документацию, комментарии в коде, ответы в чате. Работает в четыре шага: найти паттерны, переписать, добавить живого голоса, затем задать себе вопрос «что здесь выдаёт машинную генерацию» и убрать остатки.

Паттернов в списке 31, и они разложены по группам. Рекламные формулировки вроде «революционный прорыв» и «открывает новые горизонты». Пустые обороты на «-ing»: «демонстрируя…», «обеспечивая…». Слова, заменяющие обычное «есть»: «служит как», «отличается наличием». Модальные канцеляризмы: «может потенциально». Абстрактные метафоры вместо конкретных слов: «основа», «вектор», «рычаг», «фундамент», «эндшпиль». Заголовки с титульным регистром, декоративные эмодзи, «умные» кавычки, избыток полужирного начертания и двоеточий как связки между частями предложения.

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

Рабочий процесс из AGENTS.md

Файл AGENTS.md в репозитории собирает навыки в цикл из четырёх тактов: изолировать, собрать, доказать, выпустить. Его копируют в свой проект и дописывают своё: команды проверок, жёсткие правила безопасности и архитектуры, краткую справку по окружению, локальные заглушки и фикстуры, а также то, что нельзя проверить на месте.

1. Изолировать — new-feature: свежий worktree от origin/main, код в main не пишется.
2. Собрать — code-structure: actions решают когда и зачем, сервисный слой — как.
3. Доказать — evidence-driven-testing: снимок «до» снимается при воспроизведении проблемы, то есть до исправления, пока это дёшево, «после» — когда изменение заработало.
4. Выпустить — before-and-after, затем greploop или greploop-apps для больших PR: PR открывается с доказательствами внутри и доводится до 5/5.

unslop проходит по всему тексту для человека на каждом шаге.

Отдельный раздел файла про несколько агентов. Коммитить в main запрещено. На задачу и на агента приходится ровно один worktree и одна ветка, чужие ветки и незакоммиченные изменения не трогают. Форс-пуш в main запрещён, а где форс-пуш допустим, он делается только через --force-with-lease и только на своей ветке. Worktree не изолирует общие ресурсы, поэтому база под эксперимент и порт сервера проверяются на «это моё». Если конфликт нельзя разрешить уверенно, агент останавливается и сообщает об этом, а не угадывает.

Порядок завершения задачи тоже задан: оставить изменения в рамках задачи, прогнать проверки проекта, собрать доказательства в пары «до и после», закоммитить, перебазироваться на свежий origin/main и прогнать проверки ещё раз, отправить ветку, открыть PR, пропустить заголовок и описание через unslop, довести ревью Greptile до 5/5 и закончить ссылкой на PR. Мержить без прямой команды агент не берётся, а worktree живёт до закрытия PR.

Установка

Ставится набор одной командой через npx skills:

npx skills add michaelshimeles/skills

Команда работает с большинством агентов для написания кода. В Claude Code навык подхватывается сам и срабатывает, когда совпадает описание; вызвать его вручную можно через /code-structure или /evidence-driven-testing. Для before-and-after отдельно нужен сам инструмент: npm i -g @vercel/before-and-after agent-browser.

Что нужно каждому навыку

• new-feature — только git. В Claude Code и Cursor worktree создаёт сам харнесс.
• code-structure — ничего, это правила и чек-листы.
• evidence-driven-testing — Python 3, ffmpeg и ffprobe с libx264 и фильтром ass, доступный экран, а для отправки в PR — gh. Без графики достаточно запущенного приложения и Playwright через npx.
• before-and-after — npm i -g @vercel/before-and-after agent-browser.
• greploop и greploop-apps — git, авторизованный gh, glab или p4, и установленный на репозитории Greptile.
• unslop — ничего.

Как добавить свой навык

Инструкция в README короткая. Создаёте папку с именем в kebab-case, кладёте в неё SKILL.md с блоком name и description во frontmatter, пишете инструкции коротко и по делу, а если текст разрастается, выносите подробности в отдельные файлы рядом и ссылаетесь на них. Всё.

Что взято из других репозиториев

Три навыка перенесены из чужих проектов, и лицензии лежат рядом с ними в тех же папках. before-and-after пришёл из vercel-labs/before-and-after под PolyForm Shield 1.0.0. greploop — из greptileai/skills под MIT. unslop — из набора pstack в cursor/plugins, тоже MIT, причём тело файла совпадает с исходным, а во frontmatter автор убрал строку disable-model-invocation и переписал описание, чтобы навык срабатывал сам. greploop-apps — локальная версия greploop, отдельного источника у неё нет.