Claude Code skills для DevOps: как превратить runbook в скилл по TDD

Runbook-скилл в Claude Code - это ранбук, который агент не читает как подсказку, а исполняет: SKILL.md с порядком шагов и стоп-условиями плюс готовые скрипты под каждый рискованный шаг. Я сделал такой 13 августа 2026, после того как за день легла половина моего VPN-парка. Скилл называется /vpn-new и заводит новый VLESS-узел на голом VPS. Писал его по TDD: сначала смотрел, как агент без скилла ломает прод, и только потом писал инструкцию.

Ниже весь путь: откуда взялся ранбук, из чего состоит скилл, как его тестировать субагентами и где автоматизация DevOps-рутины через агента заканчивается. Сквозной пример один - заведение узла. На нём видно всё.

Что такое runbook и чем скилл Claude Code лучше вики-страницы

Runbook - это пошаговая инструкция для типовой операции: "зайди туда, выполни это, проверь вывод, если видишь X - перезапусти Y". Скилл Claude Code - папка с SKILL.md, скриптами и шаблонами, которую агент подгружает под задачу. Если положить ранбук в скилл, шаги выполняет агент, а опасные места закрыты скриптами, а не честным словом.

В Anthropic скиллы описывают как "организованные папки с инструкциями, скриптами и ресурсами, которые агент находит и подгружает динамически" (Anthropic, октябрь 2025). Там же главный аргумент за скрипты: некоторым задачам нужна "детерминированная надёжность, которую даёт только код". Генерировать токенами команду, которая трогает прод, каждый раз заново - лотерея. Запустить проверенный скрипт - нет.

Гугловые SRE ещё до всяких агентов писали, что ранбук вида "залогинься в X, выполни команду, проверь вывод" - это, по сути, псевдокод для любого, кто умеет программировать (SRE Workbook, глава Eliminating Toil). Скилл как раз и превращает этот псевдокод в код, только исполнитель теперь агент, а не крон.

Мой пример - /vpn-new. Задача: взять пустой VPS и сделать из него узел VPN-сервиса под панелью Remnawave, с подписками для всех юзеров, проверкой трафика и откатом.

Зачем мне понадобился скилл: половина парка за день

12 августа 2026 за день легли сразу несколько арендованных VLESS-узлов: провайдер переезжал панель. Я весь день хотфиксами выводил их из сборки подписки, чтобы у юзеров не висели мёртвые сервера. Вернул он их только 19 августа, на новой инфре, с новыми адресами и ключами.

Выводы получились простые. Арендованные узлы под чужой панелью - это чужая точка отказа, и управлять ею я не могу. А заводить свой узел надо уметь быстро, без героизма и в любое время.

Первый собственный узел (Финляндия) я поднял на голом VPS за день, 13 августа. Reality на TCP/443 плюс Hysteria2 на UDP/443, оба под моей панелью Remnawave. End-to-end замер показал 287 Мбит/с, тест-ребут узел пережил сам, без моего участия. Пральна, подумал я, теперь записать бы, как я это сделал, пока помню.

Процедура вышла на 8 крупных шагов: SSH и docker на VPS, DNS-запись, сертификат Let's Encrypt, nginx-маскировка для Reality, контейнер remnanode, профиль и узел в панели, узел в боте и строки подписок, файрвол. В конспекте я записал, что любой VPS так становится узлом примерно за 40 минут. Но эти 40 минут - если знать все грабли заранее. А граблей было много:

• DNS-провайдер сам добавляет к новому поддомену парковочные A и AAAA записи. Не удалишь обе - Let's Encrypt валидирует домен на чужом хосте.
• Вторичные NS этого провайдера синхронизируются с задержкой до ~30 минут, и до тех пор certbot ловит NXDOMAIN.
• nginx 1.18 не понимает директиву http2 on, только старый синтаксис listen ... ssl http2.
• Актуальный образ remnanode ждёт переменные NODE_PORT и SECRET_KEY, а старые APP_PORT и SSL_CERT молча игнорирует.
• Reality надо проверять UUID юзера, который реально сидит в группе узла, иначе тестовый юзер получит "не работает" при исправном сервере.

Держать всё это в голове к следующему узлу? Ну нет. Следующий раз будет через месяц, и я всё забуду.

Из чего состоит скилл /vpn-new

Скилл /vpn-new - это SKILL.md на 299 строк, 7 скриптов и 3 шаблона, всего 1160 добавленных строк в одном коммите. SKILL.md держит порядок шагов, стоп-условия и откат, а всё, что трогает DNS, панель, бот и базу, делают скрипты. Агент не придумывает команды, он запускает готовые и читает их вывод.

Вот состав, как он лёг в репозиторий (строки - из git-лога коммита):

Самый толстый скрипт - работа с панелью, 264 строки. Логично: там больше всего способов тихо сломать соседние узлы. Скрипт для DNS всего 65 строк, но именно он потом оказался дырявым, об этом ниже.

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

Как тестировать скилл Claude Code: baseline-субагент без скилла

Тестировать скилл по TDD значит сначала запустить субагента на ту же задачу без скилла и записать, где он ошибается (RED), потом написать скилл и прогнать снова (GREEN), а затем закрыть найденные дыры (REFACTOR). Без шага RED непонятно, учит ли скилл вообще чему-то, чего агент не знал сам.

Сам подход я взял из набора скиллов superpowers, там это сформулировано жёстко: "если ты не видел, как агент проваливается без скилла, ты не знаешь, учит ли скилл правильному" (obra/superpowers, writing-skills).

RED: что сделал агент без скилла

Baseline-субагенту без скилла я дал ту же задачу: завести узел. Он строил план из 6-9 ошибочных шагов, в зависимости от прогона. Самый страшный - перезапись продовой группы юзеров в панели. В Remnawave юзеры видят узлы через группы (в панели это "сквад"), и агент уверенно собирался её перезаписать. Все живые подписки при этом отвалились бы разом.

Вот это и есть ответ на вопрос "а нафига тесты для текста". Агент без контекста делает правдоподобные, но разрушительные вещи. Причём делает уверенно. Похожую историю с папкой проекта я уже разбирал в посте про PreToolUse guard, тут тот же класс ошибки, только на проде с юзерами.

GREEN: что сделал агент со скиллом

Со скиллом субагент построил верный план и ответил на все 7 контрольных вопросов. Вопросы - это и есть тесты: каждый бьёт в место, где ошибался baseline, и на каждый есть один правильный ответ.

REFACTOR: дыры, которые нашёл сам GREEN-прогон

Самое полезное случилось дальше. Тот же GREEN-прогон, отвечая на вопросы, наткнулся на места, где скилл врал или недоговаривал:

1. Не было отката. Сломалось на середине - и что, разбирать руками?
2. Скрипт панели был полу-идемпотентным: повторный запуск после сбоя мог создать дубли.
3. DNS-шаг не был защищён: скрипт мог перетереть существующую запись.
4. Скрипт установки ноды не копировался на VPS, хотя SKILL.md на него ссылался.
5. Пункт про мониторинг вводил в заблуждение.

Все пять я закрыл до коммита. Скрипты прогнал на живой системе и добавил к ним флаги --remove и --deactivate, это и есть откат. Заодно ужесточил права на ключ сертификата до 600 и проверил, что e2e после этого не сломался.

Как превратить свой runbook в скилл: пошагово

Короткая версия: сначала пройти процедуру руками и записать её, потом найти, где агент без инструкции ошибается, и только потом писать SKILL.md и скрипты. Писать скилл сразу, из головы, бессмысленно: скилл будет учить тому, что агент и так делает нормально, и промолчит там, где он ломает прод.

1. Пройди процедуру руками один раз до конца и веди конспект прямо по ходу. Каждая грабля - отдельной строкой с симптомом ("certbot ловит NXDOMAIN").
2. Запусти субагента без скилла на ту же задачу и попроси только план, без исполнения. Запиши все ошибочные шаги - это твои тест-кейсы.
3. Из ошибок сделай контрольные вопросы. У меня их было 7.
4. Каждый шаг, который трогает чужое состояние (DNS, панель, база, конфиг бота), вынеси в скрипт с проверкой "уже сделано - пропускаю". Идемпотентность тут важнее красоты.
5. Добавь откат к каждому такому скрипту. Без --remove скилл годится только для идеального дня.
6. В SKILL.md оставь порядок, стоп-условия и ссылки на скрипты и шаблоны. Конфиги - шаблонами, не простынёй внутри.
7. Прогони субагента со скиллом, сверь ответы с контрольными вопросами и отдельно попроси его найти, где скилл недоговаривает.
8. Проверь скрипты на живой системе. Тест на бумаге не ловит "скрипт не скопировался на сервер".

Если у агента есть доступ к проду, шаг 2 делай строго в режиме "только план". Baseline на то и baseline, что он ошибается.

Второй узел по скиллу и /vpn-update: что изменилось

Второй узел, в Швеции, я завёл скиллом уже на следующий день, 14 августа 2026, и это была рутина: панель, конфиги, бот, строки подписки 58 юзерам одной командой backfill. Тест-ребут прошёл, Hysteria2 показала ~148 Мбит/с. Разница с первым узлом не в скорости рук, а в том, что я не вспоминал грабли - они уже были в скрипте.

Одна грабля всё-таки вылезла новая. Проверять Hysteria2 с основного сервера нельзя: у его хостера фильтруется исходящий UDP/443, и e2e показывает ложный timeout на исправном узле. Гонял с другой машины. Узел исправен, а тест кричит "мёртв" - классика :) Теперь это строка в документации проекта рядом со скиллом.

Ещё до шведского узла, вечером 13 августа, стало понятно, что заведение узла - половина беды. При любом изменении парка надо поправить около 10 мест: env бота, тексты бота со списком стран, панель, мониторинг, публичную витрину статусов на sunm8.ru/status, документацию. Пропустил одно - юзер видит в боте страну, которой уже нет.

Под это я в тот же вечер сделал второй скилл, /vpn-update: SKILL.md на 190 строк и скрипт аудита на 340 строк, который сверяет все эти места между собой. Первый же прогон аудита на проде нашёл 4 расхождения. Позже аудит доучил ещё на один случай: он ловит действующий узел, который случайно спрятан из выдачи подписки.

Когда runbook-скилл не нужен и где агенту нужен человек

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

Ещё одна граница - что агенту нельзя отдавать даже со скиллом. В /vpn-new есть два места, где решение остаётся за мной. Рассылка юзерам про новый узел готовится скриптом, тестовое сообщение уходит мне, а отправка на всех - только по моей команде. И проверку с реального мобильного интернета из России скилл не делает вообще, это руками. Скилл сокращает путь до кнопки, но кнопку жму я.

И да, скилл не отменяет того, что модели меняются. Когда я переезжал на Opus 5, половину скиллов пришлось переписывать. Ранбук-скилл со скриптами переживает такое легче: логика в коде, а от модели нужно только читать вывод и не лезть туда, куда SKILL.md не пускает. Звучит скучно? Скучно. Для прода это комплимент.