# claude-skills

> English version: [README.md](README.md).

Совместное хранилище и мастерская навыков для Claude.

## About

Здесь мы с Claude вместе разрабатываем, отлаживаем и храним скиллы:

- **`skills/`** — редактируемые исходники (markdown + ассеты), source of truth
- **`dist/`** — собранные `.skill` архивы, закоммичены в репо
- **`scripts/`** — утилиты: `build.sh` (исходник → `.skill`), `install.sh` (исходник → `~/.claude/skills/`)
- **`.wiki/`**, **`.tasks/`** — рабочие материалы и доска задач

## Quick start

### Установить скиллы на новом компе

```bash
git clone <repo> claude-skills
cd claude-skills
bash scripts/install.sh           # копирует все skills/* в ~/.claude/skills/
# или конкретные (mappa-* скилы ставятся из репо `mappa` — см. mappa-bootstrap):
bash scripts/install.sh caveman tdd-criteria
```

Цель установки можно переопределить переменной `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh`.

### Использование в проектах

Когда скиллы установлены, проще всего раскатить их на новый (или
существующий) проект через скилл [`project-bootstrap`](skills/project-bootstrap/).
Скажи агенту **«bootstrap»** или **«настрой проект»** в папке проекта — он
за один проход:

- инициализирует `git` (если ещё нет) и положит вменяемый `.gitignore`
- создаст стартовый `README.md`
- зарегистрирует мету проекта в **mappa** (wiki/task-сущности; файловые `.wiki/`/`.tasks/` закрыты 2026-08-25)
- запишет `AGENTS.md` (канон) со скилл-триггерами + `CLAUDE.md`-указатель (`use project wiki`, `use task management system`, `check across all projects`, `we're on Windows`)
- зафиксирует версии использованных скиллов в mappa wiki-сущности `concepts/bootstrap-manifest`, чтобы дрифт раскладки оставался отлаживаемым

Два режима, выбирается автоматически: **init** для пустой папки и **upgrade**
для существующего проекта (скилл только дозаполняет пробелы и ничего не
перезаписывает без явного подтверждения). В режиме upgrade `AGENTS.md`
сливается идемпотентно — только канонические триггер-строки, которых ещё
нет в файле, дописываются после явного подтверждения, поэтому повторный
запуск `project-bootstrap` после обновления шаблона подтягивает новые
триггеры, не дублируя старые.

### Отредактировать скилл

```bash
# 1. Правишь skills/<name>/SKILL.md (или ассеты)
# 2. Раскатываешь правки в живые скиллы:
bash scripts/install.sh <name>
# 3. Пересобираешь архив (опц., но удобно делать перед коммитом):
bash scripts/build.sh <name>
```

### Собрать `.skill` архивы

```bash
bash scripts/build.sh                 # все
bash scripts/build.sh caveman          # один
```

`build.sh` использует `zip` если он есть (Linux/macOS) или делегирует в
`scripts/build.ps1` через PowerShell (Windows без `zip`). На Windows
можно сразу запускать `powershell scripts/build.ps1`.

## Layout

## Суверенитет / провенанс

Каталог суверенный: каждый скилл либо **нашего авторства**, либо
**адаптированная вендорская копия**, которую поддерживаем сами. Никаких
сырых вендорских плагинов как зависимостей — всё заимствованное вендорится
в этот репо с явным маркером `adapted-from` во frontmatter.

| скилл | провенанс |
|---|---|
| `caveman`, `caveman-commit`, `caveman-compress`, `caveman-help`, `caveman-review` | `adapted-from: JuliusBrussee/caveman @ 0993277` (MIT) — вендорная копия |
| `find-skills` | `adapted-from: vercel-labs/skills @ c6f69c6` (MIT) — вендорная копия |
| `grilling` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — семейство схлопнуто в один скил (pi прячет `disable-model-invocation` обёртки) |
| `brainstorming` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — расходящаяся фаза, visual-companion выброшен |
| `diagnosing-bugs` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) + superpowers 6.2.0 (Iron Law, red flags) |
| `loop-me` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — дизайн-гейт workflow-спец |
| `review-kit-pi-method` | `author: ours` — pi-спавн чистых review-субагентов |
| `command-index` | `author: ours` — конвенция just/Makefile command-index (стандартные таргеты, авто-док; идея 3/18) |
| `code-search` | `author: ours` — rg-first код-поиск (замер: 15 мин → 0 сек; роутинг: rg / git grep / interns repo_read / grep_audit) |
| `code-review` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — двухосевость + Fowler-база; формат вывода: caveman-review |
| `writing-skills` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — TDD-for-skills ядро + идея 8 self-skill-authoring |
| `ops-browser` | `author: ours` — свой скрытый браузер агента (профиль + CDP + `handoff` человеку, замок `ops.lock`) |
| `browser-operator` | `author: ours` — браузер ОПЕРАТОРА (его Chrome/логины): канал по харнессу (Hermes `browser_exec` / pi тул `browser` / CC `chrome-devtools`), аренда «один водитель за раз», границы «человек vs агент»; анонимные прогоны — `browser-cdp` |
| остальные `skills/*` | `author: ours` |

Политика адаптации: клон переписывается под наши конвенции (доски `.tasks/`,
спеки `.wiki/concepts/`, имена скиллов `using-*`), вендорский мусор не
перетягивается, версионируется под нашим semver. Пины апстрима
пересматривает владелец каталога при обновлении; автосинка нет.

```
skills/
├── skills/                 ← исходники (по папке на скилл)
├── dist/                   ← .skill архивы (коммитятся)
├── scripts/
│   ├── build.sh / build.ps1
│   └── install.sh
├── .wiki/                  ← дизайн-доки, заметки
├── .tasks/                 ← STATUS.md
├── AGENTS.md              ← канон (CLAUDE.md — legacy-указатель)
└── README.md
```

Подробнее про принципы и решения — в [`.wiki/concepts/repo-layout.md`](.wiki/concepts/repo-layout.md).