skills/README.md

skills

Russian version: 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):

git clone <repo> skills
cd skills
bash scripts/install.sh           # copies every skills/* into ~/.claude/skills/
# or only specific ones:
bash scripts/install.sh mappa-knowledge caveman

Linux / macOS (bash):

git clone <repo> skills
cd skills
bash scripts/install.sh           # copies every skills/* into ~/.claude/skills/
# or only specific ones:
bash scripts/install.sh mappa-knowledge caveman

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 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

# 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 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.

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.

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-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
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.