Руководство

Устройство skaaska

Иерархия работ на диске, которая сама рассказывает о себе агенту при старте сессии, и хранилище скиллов, которые улучшаются по ходу дела — но только через ваше «да».

workspace: ~/work
платформа: ~/skaaska
хранилище: ~/.skaaska
команда: ska

01 — где что лежит

Три дома

Разделение жёсткое и намеренное: работа, инструмент и знание живут отдельно. Путать их не нужно — каждый правится своим способом.

~/work Ваша работа

Не git. Иерархия work → stream → task: направление, долгоживущая линия внутри него, конкретная задача. Клоны репозиториев — внутри задач.

nbs/ work └ backend/ stream └ pr-46061/ task ├ CONTEXT.md цель, состояние ├ DECISIONS.md журнал решений ├ notes/ заметки └ repo/ клон

~/skaaska Инструмент

Git-репозиторий, он же плагин Claude Code. Здесь код ska, хук, шаблоны и пять скиллов самого плагина.

ska/ пакет CLI skills/ скиллы плагина hooks/ SessionStart templates/ скелеты узлов tests/ 241 тест docs/ спека и планы

~/.skaaska Знание

Отдельный git-репозиторий. Уроки, скиллы и их версии. Коммитится сам, при каждой записи.

store/ ├ skills/<имя>/ активная версия ├ lessons/ уроки ├ proposals/ ждут ревью └ теги skill/<имя>/v<N> config.toml locks/

Четвёртое место — ~/.claude/skills/. Туда ska skill sync раскладывает копии активных версий, чтобы их видел Claude Code. Руками там не правят: следующий sync перезапишет.

02 — механика

Что происходит, когда вы запускаете claude

Контекст не надо собирать руками и не надо просить — он приходит сам.

Запуск из любой папки

Даже из глубины клона: ~/work/nbs/backend/pr-46061/repo/cloud/blockstore. Поиск корня идёт вверх по дереву и не останавливается на git-корне.

Срабатывает SessionStart-хук плагина

Он вызывает ska context --brief --hook. Вне workspace молча выходит и ничего не портит.

В сессию впрыскивается контекст цепочки

Цель work, stream и task, ветка репозитория, последние решения, соседние задачи, счётчик открытых уроков. Жёсткий бюджет — 4000 символов; что не влезло, названо явно.

[skaaska] workspace=~/work · nbs/backend/pr-46061 (task, active)

work nbs — NBS 2.0: control plane, PR-ревью, доки [nbs, cpp]
stream backend — C++ backend, ya make, PR в ydb-platform/nbs
task pr-46061 — убрать host-dbg; PR ydb#46061

repo: repo @ remove-host-dbg
Последние решения: 1) Держать host-dbg за флагом до выкатки
Открытых уроков: 3 (ska lesson list --open)

Работа идёт, знание оседает

Решения — в DECISIONS.md задачи, уроки — в хранилище. Позже уроки сворачиваются в новую версию скилла, и её принимаете вы.

Правила и контекст — разные файлы. CLAUDE.md — правила, их грузит сам Claude Code вверх по дереву. CONTEXT.md — состояние узла, его собирает ska. Узел никогда не называют CLAUDE.md: иначе двойная загрузка и неуправляемый бюджет.

03 — инструменты

Команды

Одна утилита ska, тринадцать подкоманд. Везде есть --json; глобальный --url переключает на сервис вместо локального хранилища.

Команда	Что делает
Workspace
`ska init <путь>`	Создать корень workspace. Делается один раз.
`ska where`	Где я: корень, цепочка, тип и статус узла.
`ska new work\|stream\|task <имя>`	Создать узел. У задачи: `--clone URL --branch` — сразу склонировать репозиторий в `repo/`.
`ska status`	Дерево всех работ. Работает из любой папки, закрытые узлы свёрнуты в счётчик.
`ska index --all`	Перегенерировать `INDEX.md` — таблицу содержимого узлов.
`ska context --full`	Полный контекст с телами `CONTEXT.md`. В сессии — скилл `/ctx`.
`ska claude …`	Запустить claude, подмешав контекст через системный промпт. Запасной путь, если хук не работает.
Знание
`ska add decision "…"`	Записать решение в журнал задачи. `--source ревью`, `--body -` читает stdin. С `--lesson --skill X` заодно заводит урок.
`ska add note <слаг>`	Заметка в `notes/`. Слаг можно по-русски.
`ska lesson add\|list\|set`	Уроки напрямую. Без `--skill` урок падает в `_inbox` и привязывается позже.
Скиллы
`ska skill list`	Что есть, какая версия активна, что не синхронизировано.
`ska skill import <каталог>`	Взять готовый каталог со `SKILL.md` как версию 1.
`ska skill get X --with-lessons --out D`	Выгрузить активную версию и открытые уроки — вход для компакшна.
`ska skill propose X --from D`	Предложить новую версию. `--all-open` подхватывает все открытые уроки скилла.
`ska skill review X`	Дифф активная → предложенная, список сворачиваемых уроков, заметка.
`ska skill approve\|reject X`	Принять или отклонить. Принятая версия становится активной, уроки закрываются.
`ska skill versions\|diff\|rollback X`	История. Откат вперёд-только: `rollback 1` создаёт новую версию с содержимым первой.
`ska skill sync --all`	Разложить активные версии в `~/.claude/skills`. После — перезапустить сессию.
Служебное
`ska doctor`	Девять проверок: PATH, workspace, шаблоны, хук, плагин, свежесть плагина, конфиг, сервис. Ничего не чинит — печатает команду-исправление.
`ska store`	Сколько скиллов и уроков, есть ли незакоммиченные правки.
`ska serve`	Сервис и веб-интерфейс на `127.0.0.1`: ревью версий, дерево работ, уроки, история скиллов.

Скиллы плагина

Пять штук, доступны в любой сессии внутри workspace. Первый впрыскивается автоматически, остальные агент подхватывает по описанию.

`using-skaaska`	Что такое workspace и четыре главные команды. Приходит с контекстом.
`/ctx`	Полный контекст текущего узла по требованию.
`recording-lessons`	Когда записывать урок, а когда не стоит.
`managing-workspace`	Как заводить узлы и что где хранить.
`compacting-skills`	Как свернуть уроки в новую версию скилла — и что приём остаётся за человеком.

04 — сценарии

Как пользоваться

Начать задачу

ska new task pr-47012-fix-restore --work nbs --stream backend \
    --summary "починить restore при пустом снапшоте" \
    --clone https://github.com/ydb-platform/nbs --branch fix-restore

cd ~/work/nbs/backend/pr-47012-fix-restore/repo
claude   # контекст уже внутри

Зафиксировать решение и урок

Решение всегда остаётся в задаче. Флаг --lesson добавляет его же в общее хранилище — для того, что пригодится за пределами этой задачи.

ska add decision "Пустой снапшот — не ошибка, а no-op" --source ревью \
    --body "Ревьюер показал, что вызывающий код это уже проверяет."

ska add decision "Проверять restore на пустом снапшоте" --lesson --skill design-doc \
    --body "Класс ошибок, который тесты не ловят: пустой вход."

Улучшить скилл накопленными уроками

Шаги 1–3 делает агент по скиллу compacting-skills, шаг 4 — вы.

1. ska skill get design-doc --with-lessons --out /tmp/dd
2. # агент переписывает файлы в /tmp/dd
3. ska skill propose design-doc --from /tmp/dd --all-open --note "…"
4. ska skill review design-doc     # смотрите дифф
   ska skill approve design-doc    # или reject --reason "…"
   ska skill sync design-doc       # и перезапустить сессию

Откатить неудачную версию

ska skill versions design-doc     # v1 v2 v3
ska skill diff design-doc 2 3     # что изменилось
ska skill rollback design-doc 2   # создаст v4 = содержимое v2
ska skill sync design-doc

История никогда не переписывается: откат — это новая версия со старым содержимым. Всё, что было, остаётся в git-тегах хранилища.

Работать через сервис

Нужен, когда хранилище одно, а машин или агентов несколько. Пока не нужен — не запускайте.

ska serve --port 8787
ska --url http://127.0.0.1:8787 skill list

# постоянно: service.url в ~/.skaaska/config.toml или SKAASKA_URL

05 — правка

Как редактировать

Пять разных вещей правятся пятью разными способами. Ошибиться местом — самая частая причина «я поменял, а ничего не изменилось».

Что правим	Где	Как
Цель или статус задачи	`<узел>/CONTEXT.md`	Обычным редактором. Шапка — блок `ska:` (`status`, `summary`, `tags`), ниже свободный markdown. Статус `done` убирает узел из контекста и дерева.
Скилл из хранилища	`~/.skaaska/store/skills/<имя>/`	Через предложение, не напрямую: `propose --from <каталог>`, либо поправить в хранилище руками и сделать `propose --from-worktree` — правки уедут в предложение, дерево вернётся к последней версии. Дальше `review` → `approve` → `sync`.
Скилл плагина using-skaaska, /ctx и т. д.	`~/skaaska/skills/`	Правите файл → поднимаете `version` в `.claude-plugin/plugin.json` → `claude plugin update skaaska`. Проверить без установки: `claude --plugin-dir ~/skaaska`.
Сам инструмент	`~/skaaska/ska/`	Python 3.12 без зависимостей. Тест сначала, потом код: `python3 -m unittest discover -s tests`. Симлинк в PATH ведёт прямо в репозиторий — правка видна сразу.
Скелеты новых узлов	`~/skaaska/templates/`	Разделы `CONTEXT.md`, форма записи решения, текст `CLAUDE.md` для новых workspace. Действует на узлы, созданные после правки.
Правила для агентов	`~/work/CLAUDE.md`	Общие правила workspace. Правила отдельного направления — `CLAUDE.md` внутри work: Claude Code подхватывает их сам, вверх по дереву.

05a — браузер

Веб-интерфейс

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

ska serve                                  # на машине с workspace
ssh -L 8787:127.0.0.1:8787 <хост>             # с ноутбука
# открыть http://127.0.0.1:8787

Раздел	Что можно
Ревью	Дифф версий, список сворачиваемых уроков, кнопки «Принять» и «Отклонить с причиной».
Работы	Дерево, правка `CONTEXT.md` и шапки, запись решений и заметок, создание узлов с клоном репозитория.
Уроки	Фильтры по статусу, привязка к скиллу, отклонение, готовая команда компакшна.
Скиллы	Версии, дифф любых двух, откат, синхронизация с агентами, changelog.

Порт наружу не открывается. Сервис без авторизации и слушает только петлю — попытка привязаться к внешнему интерфейсу отклоняется. Доступ снаружи — только пробросом через SSH.

Правка не затирает работу агента. Страница присылает отпечаток прочитанного текста; если файл успела изменить сессия Claude, сохранение отклоняется с показом актуального содержимого.

06 — грабли

Что удивит

Плагин — снимок, а не ссылка. Установленный плагин лежит копией в ~/.claude/plugins/cache/. Правки в ~/skaaska до него не доходят без claude plugin update. Расхождение ловит ska doctor.

После sync нужен перезапуск. Claude Code читает список скиллов на старте сессии. Новая версия появится в следующей — или после /reload-plugins.

Чужие правки блокируют хранилище. Если в ~/.skaaska/store есть незакоммиченные изменения, запись откажет: автокоммит выдумал бы историю версий. Разберитесь руками или используйте propose --from-worktree.

Приём не бывает автоматическим. Агент готовит версию, но не принимает свою же: approve — всегда решение человека. Отклонение оставляет уроки открытыми, они попадут в следующее предложение.

Если что-то не работает — начните с ska doctor. Он проверяет всю цепочку от версии Python до доступности сервиса и для каждой поломки печатает готовую команду.