vitya
6b36b312fa
Adds the conversion infrastructure for the Hermes-rollout (Nous Research): - hermes/mapping.yaml — per-skill schema (mode: auto|manual|skip|pending, category, replace-rules, source override). Every skills/<name>/ has an explicit entry; the build fails on unmapped skills. - scripts/build-hermes.py — Python converter. Reads mapping.yaml; for auto applies replace-rules to SKILL.md and copies the rest verbatim; for manual copies hermes/skills/<source>/ as-is; for skip / pending records to dist-hermes/SKIPPED.md. - dist-hermes/ — pre-converted Hermes-flavour tree (committed; consumed by the recursive installer in [hermes-installer-skill]). Includes 4 universal skills: pulling-before-work, active-platform (with Linux+bash replacement rule), project-discipline, using-markitdown. Plus SKIPPED.md listing 8 skip + 10 pending entries. - README.md — adds "Build for Hermes" section, updates layout, mentions hermes/, dist-hermes/, build-hermes.py. Mapping is the source of truth for the audit table from .wiki/concepts/hermes-skills-rollout-design.md (Q1-Q8). Pending entries preserve the audit decision (intended mode/category) for the follow-up tasks: hermes-flavour-mcp-setups, hermes-installer-skill, hermes-mvp-coverage. Security carry-forward (extraheader-pattern, POSIX-absolute paths, semver bumps) — infrastructure ready (replace-rules + manual mode); concrete content lands in hermes-flavour-mcp-setups. Smoke-tests: idempotent re-run produces no diff; replace-rules verified on active-platform (Linux+bash); strict-mapping fail-fast verified on a synthetic unmapped skill (exit 1). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
130 lines
5.4 KiB
Markdown
130 lines
5.4 KiB
Markdown
# claude-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> claude-skills
|
|
cd claude-skills
|
|
bash scripts/install.sh # copies every skills/* into ~/.claude/skills/
|
|
# or only specific ones:
|
|
bash scripts/install.sh caveman wiki-maintainer
|
|
```
|
|
|
|
**Linux / macOS (bash):**
|
|
|
|
```bash
|
|
git clone <repo> claude-skills
|
|
cd claude-skills
|
|
bash scripts/install.sh # copies every skills/* into ~/.claude/skills/
|
|
# or only specific ones:
|
|
bash scripts/install.sh caveman wiki-maintainer
|
|
```
|
|
|
|
The install target can be overridden with `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh`.
|
|
|
|
> `install.sh` works on Windows under git-bash. A native `install.ps1` is on the task board but not yet implemented.
|
|
|
|
### 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`
|
|
- lay out `.wiki/` per the [Karpathy LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) (delegated to [`setup-wiki`](skills/setup-wiki/))
|
|
- lay out `.tasks/` with the canonical task board (delegated to [`setup-tasks`](skills/setup-tasks/))
|
|
- write `CLAUDE.md` with skill triggers (`use superpowers`, `use project wiki`, `use task management system`, `check across all projects`, `we're on Windows`)
|
|
- record the skill versions used in `.wiki/concepts/bootstrap-manifest.md` so cross-project layout drift stays debuggable
|
|
- check whether the official `superpowers@claude-plugins-official` plugin is installed and, if not, print the install command — the `use superpowers` trigger is a no-op without it
|
|
|
|
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, `CLAUDE.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).
|
|
|
|
## Layout
|
|
|
|
```
|
|
claude-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/pulling-before-work/
|
|
│ └── 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
|
|
├── CLAUDE.md
|
|
└── 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).
|