docs+ci: document the plugin path, bump plugin.json version on release

CI now writes the computed semver into .claude-plugin/plugin.json before tagging, committed with [skip-release] so it does not re-trigger the tagger. Claude Code gates plugin updates on that field: without the bump, installed hosts never see a new tag no matter how many releases go out. `task check` enforces manifest/tag equality so the two cannot silently diverge. Docs rewritten around the two delivery paths, and the checkout location is now stated as load-bearing rather than incidental: SKILLS_CHECKOUT_DIR defaults to ~/.local/share/skills because that is host-local and outside any synced directory. The previous docs told you to clone into ~/dev, which on this fleet is an iCloud folder shared by two Macs spanning two path roots — a git working tree with concurrent writers, and absolute links that are broken on one side by construction. That advice is what #23 is about; it is now inverted with the reason attached. Antigravity and Vibe removed from the docs along with their targets. Bump-Type: patch Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BeAp5LTscnz2W7Ubt4eJ6m
2026-08-23 14:35:38 +02:00
parent 88c54399fe
commit 78b9b59eca
3 changed files with 117 additions and 56 deletions
@@ -47,23 +47,55 @@ This index lists all available engineering skills. Load the full SKILL.md on dem

 ## Wiring into tools

-This repo **is** the canonical home. Wire every skill into each harness with the
-**`install.sh`** script (idempotent, per-skill symlinks) — either the one-shot
-`curl -fsSL https://git.d-ma.be/mathias/skills/raw/branch/main/install.sh | bash`,
-or, from a clone, `SKILLS_CHECKOUT_DIR="$PWD" bash install.sh`. (The `task
-install` targets are currently broken — see issue — use `install.sh`.)
+This repo is the canonical home, and it is delivered two different ways.

- **Claude Code (global)** — `~/.claude/skills/<name>` → `<repo>/<name>`.
- **Claude Code (per-repo)** — `<repo>/.claude/skills/<name>` when `task install`
-  is run inside another git repo (excluded via `~/.config/git/ignore`).
- **Crush** — `~/.config/crush/skills/<name>`.
- **Antigravity** — `~/.gemini/antigravity/skills/<name>`.
- **Mistral Vibe** — `~/.vibe/skills/<name>.md` → `<repo>/<name>/SKILL.md`
-  (flat `.md` layout).
+### Claude Code — install the plugin

-Individual targets are also runnable: `task install:claude:global`,
-`install:crush`, `install:antigravity`, `install:vibe`. `task update` pulls the
-canonical checkout then re-wires.
+This repo hosts a marketplace containing exactly one plugin: itself. The plugin
+carries the skills **plus** the `secret-guard` and `pre-task-ritual` hooks and
+the brain/gitea/infra MCP servers — none of which a symlink can deliver.
+
+```
+/plugin marketplace add https://git.d-ma.be/mathias/skills.git
+/plugin install skills@mathias
+```
+
+Skills are namespaced: `tdd` becomes `skills:tdd`. Updates arrive when
+`.claude-plugin/plugin.json`'s `version` moves, which CI does on every release.
+Remove any leftover `~/.claude/skills/<name>` symlinks from the pre-plugin era —
+plugin skills do **not** override same-named user skills, so leftovers make
+everything load twice.
+
+### Crush, Pi, OpenCode — run `install.sh`
+
+These have no plugin system, so they get symlinks — but **one directory link
+each**, never one per skill:
+
+```
+~/.agents/skills           -> $SKILLS_CHECKOUT_DIR/skills   (Pi reads this directly)
+~/.config/crush/skills     -> ~/.agents/skills
+~/.config/opencode/skills  -> ~/.agents/skills
+```
+
+Adding a skill therefore wires it everywhere with no re-run, and a broken link
+is one broken link instead of 42.
+
+```
+curl -fsSL https://git.d-ma.be/mathias/skills/raw/branch/main/install.sh | bash
+```
+
+`SKILLS_CHECKOUT_DIR` defaults to `~/.local/share/skills` and **must stay
+outside `~/dev`**. On this fleet `~/dev` is an iCloud folder shared by both
+Macs and spans two path roots (`/Users/mathias` vs `/home/mathias` on koala);
+a checkout there means a git working tree with two concurrent writers, and any
+absolute link stored there is broken on one side by construction. See #23.
+
+### Check a host
+
+`task doctor` (or `bin/doctor`) reports dangling links, links resolving into a
+foreign checkout, count mismatches, stray entries, and leftover Claude
+symlinks. It also runs automatically at session start via the plugin, so drift
+announces itself instead of waiting to be found.

 ## Skill Relationships