160 lines
8.5 KiB
Markdown
160 lines
8.5 KiB
Markdown
# skills
|
||
|
||
> Russian version: [README.ru.md](README.ru.md).
|
||
|
||
Joint workshop and storage for Claude skills.
|
||
|
||
## About
|
||
|
||
A shared workspace where Claude and I author, debug, and ship skills together:
|
||
|
||
- **`skills/`** — editable sources (markdown + assets), the source of truth
|
||
- **`dist/`** — built `.skill` archives for Claude, committed to the repo
|
||
- **`hermes/`** — Hermes-rollout config: `mapping.yaml` and any `mode: manual` overrides under `hermes/skills/`
|
||
- **`dist-hermes/`** — pre-converted Hermes-flavour skill tree, committed (regenerated by `scripts/build-hermes.py`)
|
||
- **`scripts/`** — utilities: `build.sh` (source → `.skill`), `install.sh` (source → `~/.claude/skills/`), `build-hermes.py` (source → `dist-hermes/`)
|
||
- **`.wiki/`**, **`.tasks/`** — working notes and the task board
|
||
|
||
## Quick start
|
||
|
||
### Install skills on a fresh machine
|
||
|
||
**Windows (PowerShell):**
|
||
|
||
```powershell
|
||
git clone <repo> skills
|
||
cd skills
|
||
bash scripts/install.sh # copies every skills/* into ~/.claude/skills/
|
||
# or only specific ones (mappa-* skills install from the `mappa` repo — see mappa-bootstrap):
|
||
bash scripts/install.sh caveman tdd-criteria
|
||
```
|
||
|
||
**Linux / macOS (bash):**
|
||
|
||
```bash
|
||
git clone <repo> skills
|
||
cd skills
|
||
bash scripts/install.sh # copies every skills/* into ~/.claude/skills/
|
||
# or only specific ones (mappa-* skills install from the `mappa` repo — see mappa-bootstrap):
|
||
bash scripts/install.sh caveman tdd-criteria
|
||
```
|
||
|
||
The install target can be overridden with `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh`.
|
||
|
||
> `install.sh` works on Windows under git-bash; `install.ps1` provides a native PowerShell path.
|
||
|
||
### Using skills in projects
|
||
|
||
Once the skills are installed, the easiest way to wire them into a new
|
||
(or existing) project is the [`project-bootstrap`](skills/project-bootstrap/)
|
||
skill. Tell the agent **"bootstrap"** or **"set everything up"** from the
|
||
project's folder and it will, in one pass:
|
||
|
||
- initialize `git` (if missing) and write a sane `.gitignore`
|
||
- create a starter `README.md`
|
||
- register the project meta in **mappa** (wiki/task-сущности проекта; file-based `.wiki/`/`.tasks/` closed 2026-08-25)
|
||
- write `AGENTS.md` (canon) with skill triggers (`use project wiki`, `use task management system`, `check across all projects`, `we're on Windows`) plus a `CLAUDE.md` legacy pointer
|
||
- record the skill versions used in a mappa wiki entity (`concepts/bootstrap-manifest`) so cross-project layout drift stays debuggable
|
||
|
||
Two modes, picked automatically: **init** for an empty folder, **upgrade**
|
||
for an existing project (the skill only fills the gaps and never overwrites
|
||
without explicit confirmation). On upgrade, `AGENTS.md` is merged
|
||
idempotently — only canonical trigger lines that aren't already present are
|
||
appended after explicit confirm, so re-running `project-bootstrap` after a
|
||
template change picks up the new triggers without duplicating the old ones.
|
||
|
||
### Edit a skill
|
||
|
||
```bash
|
||
# 1. Edit skills/<name>/SKILL.md (or its assets).
|
||
# 2. Push the changes into the live skill folder:
|
||
bash scripts/install.sh <name>
|
||
# 3. Rebuild the archive (optional, but handy before a commit):
|
||
bash scripts/build.sh <name>
|
||
```
|
||
|
||
### Build `.skill` archives
|
||
|
||
```bash
|
||
bash scripts/build.sh # all skills
|
||
bash scripts/build.sh caveman # one skill
|
||
```
|
||
|
||
`build.sh` uses `zip` when it's available (Linux/macOS) or delegates to
|
||
`scripts/build.ps1` via PowerShell (Windows without `zip`). On Windows you
|
||
can also run `powershell scripts/build.ps1` directly.
|
||
|
||
### Build for Hermes
|
||
|
||
The same `skills/` are rolled out to Hermes Agent (Nous Research) on factory
|
||
Linux machines. The converter reads `hermes/mapping.yaml` (per-skill
|
||
mode / category / replace-rules / skip-list) and writes a Hermes-formatted
|
||
skill tree to `dist-hermes/`, which is committed to the repo.
|
||
|
||
```bash
|
||
python scripts/build-hermes.py # regenerate dist-hermes/ from mapping
|
||
```
|
||
|
||
Every skill in `skills/` must have an explicit entry in `mapping.yaml`
|
||
(`auto` / `manual` / `skip` / `pending`); the build fails on unmapped skills.
|
||
Skip and pending entries land in `dist-hermes/SKIPPED.md` with reasons. Full
|
||
design rationale lives in
|
||
[`.wiki/concepts/hermes-skills-rollout-design.md`](.wiki/concepts/hermes-skills-rollout-design.md).
|
||
|
||
## Sovereignty / provenance
|
||
|
||
This catalog is sovereign: every skill is either **authored by us** or an
|
||
**adapted vendored copy** we maintain ourselves. No raw vendor plugins are
|
||
installed as dependencies — anything borrowed is vendored into this repo with
|
||
an explicit `adapted-from` marker in its frontmatter.
|
||
|
||
| skill | provenance |
|
||
|---|---|
|
||
| `caveman`, `caveman-commit`, `caveman-compress`, `caveman-help`, `caveman-review` | `adapted-from: JuliusBrussee/caveman @ 0993277` (MIT) — vendored copy |
|
||
| `find-skills` | `adapted-from: vercel-labs/skills @ c6f69c6` (MIT) — vendored copy |
|
||
| `grilling` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — family collapsed to one skill (pi hides `disable-model-invocation` wrappers) |
|
||
| `brainstorming` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — divergent phase, visual-companion dropped |
|
||
| `diagnosing-bugs` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) + superpowers 6.2.0 concepts (Iron Law, red flags) |
|
||
| `loop-me` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — workflow-spec design gate |
|
||
| `review-kit-pi-method` | `author: ours` — pi-native spawn for clean-context review subagents |
|
||
| `command-index` | `author: ours` — just/Makefile command-index convention (standard targets, auto-doc; idea 3/18) |
|
||
| `code-search` | `author: ours` — rg-first code search (measured 15 min → 0s; routing: rg / git grep / interns repo_read / grep_audit) |
|
||
| `code-review` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — two-axis + Fowler baseline; output: caveman-review format |
|
||
| `writing-skills` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — TDD-for-skills core + ideya 8 self-skill-authoring |
|
||
| `web-search` | `author: ours` — search_web tool (pi-extension) + policy: when to search, «без поиска» session-off |
|
||
| `ops-browser` | `author: ours` — свой **скрытый** браузер агента: отдельный профиль + CDP (`eval`/`fetch` из страницы/скриншоты), `handoff` человеку для пароля/капчи; свой замок `ops.lock` |
|
||
| `browser-operator` | `author: ours` — браузер ОПЕРАТОРА (его Chrome/логины): канал по харнессу (Hermes `browser_exec` / pi тул `browser` / CC `chrome-devtools`), аренда «один водитель за раз», границы «человек vs агент», рецепты тяжёлых страниц. Закрывает провал базового прогона 2026-09-11 («куки из Chrome + curl + ввод пароля» мимо канала); анонимные прогоны — `browser-cdp` |
|
||
| `review-subagent` | `author: ours` — review_subagent tool (pi-extension): clean-context review by your own model, optional `model` override |
|
||
| `report-mappa-issue` | `author: ours` — TEMPORARY stopgap: mappa deviation reporting (mail to `mappa` + `.workshop`) while the service is unstable; retire when stabilized |
|
||
| all other `skills/*` | `author: ours` |
|
||
|
||
Adaptation policy: a clone is rewritten to our conventions (`.tasks/` boards,
|
||
`.wiki/concepts/` specs, `using-*` skill names), never shipped with vendor junk,
|
||
and versioned under our own semver. Upstream pins are reviewed by the catalog
|
||
owner on update; no automatic upstream sync.
|
||
|
||
## Layout
|
||
|
||
```
|
||
skills/
|
||
├── skills/ ← sources (one folder per skill)
|
||
├── dist/ ← .skill archives for Claude (committed)
|
||
├── hermes/
|
||
│ ├── mapping.yaml ← per-skill Hermes-rollout config
|
||
│ └── skills/ ← `mode: manual` overrides (Hermes-flavour rewrites)
|
||
├── dist-hermes/ ← pre-converted Hermes-flavour tree (committed)
|
||
│ ├── <category>/<name>/ ← e.g. software-development/diagnosing-bugs/
|
||
│ └── SKIPPED.md ← skip + pending log (auto-generated)
|
||
├── scripts/
|
||
│ ├── build.sh / build.ps1
|
||
│ ├── install.sh / install.ps1
|
||
│ └── build-hermes.py
|
||
├── .wiki/ ← design docs, notes
|
||
├── .tasks/ ← STATUS.md
|
||
├── AGENTS.md ← canon (CLAUDE.md is a legacy pointer)
|
||
└── README.md (this file — see README.ru.md for Russian)
|
||
```
|
||
|
||
For the principles and decisions behind this layout see
|
||
[`.wiki/concepts/repo-layout.md`](.wiki/concepts/repo-layout.md).
|