mathiasandClaude Opus 5
56a947b2a0
Skills move to skills/<name>/SKILL.md and the repo gains both manifests, so it is now a marketplace hosting exactly one plugin whose root is the repo root (source: "."). Claude Code installs it from git; no symlinks involved. Why: install.sh wired the library into every consuming repo as an ABSOLUTE symlink to $CHECKOUT_DIR. The checkout moved three times, most recently when local-dev@1966d5a dropped the embedded .skills/ copy, and nothing migrated the links — 243 dangling links across 12 repos, hidden from git by the **/.claude/skills/ ignore rule. Worse, ~/dev spans two path roots (/Users/mathias on the iCloud-shared Macs, /home/mathias on koala), so an absolute link stored there is broken on one side by construction. Re-running the installer cannot fix that; only removing the mechanism can. install.sh keeps the harnesses with no plugin system and drops from 42 links per harness to one directory link, via the convergent ~/.agents/skills convention that Pi and OpenCode both read: ~/.agents/skills -> $CHECKOUT_DIR/skills ~/.config/crush/skills -> ~/.agents/skills ~/.config/opencode/skills -> ~/.agents/skills wire_claude_repo is deleted outright rather than gated behind a flag — on a mixed-root fleet it cannot be made correct. Antigravity and Vibe targets go too; both unused. CHECKOUT_DIR keeps its host-local default deliberately: pointing it into ~/dev would put a git working tree inside iCloud with two concurrent writers. Taskfile drops five near-identical wiring loops (they had already drifted) and delegates to install.sh. `task check` gains frontmatter validation, a stray-root-entry gate, and manifest/tag version parity — the loose secret-hygiene.md sat unloadable for months because nothing checked layout. Verified: claude plugin validate . passes clean; a probe skill loaded as skills:zzprobe through --plugin-dir; task check green at 42 skills. Refs: #23 Bump-Type: minor Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BeAp5LTscnz2W7Ubt4eJ6m
skills
Engineering skills library — markdown SKILL.md files that plug into any
project or AI-coding harness. Installed via task skills:install in
consumer projects, or directly by install.sh on hosts without Task.
What is a skill?
A skill is a single directory containing one or more markdown files. The
canonical entrypoint is <name>/SKILL.md. Additional reference material
lives alongside in the same directory (e.g.
clean-code/references/code-smells.md). Harnesses load skills on
demand — keep SKILL.md short and triggerable; push depth into
references.
See SKILLS_INDEX.md for the full catalogue with
descriptions and "use when" triggers.
Install (consumer project)
The expected pattern: each consumer project's Taskfile.yml has a
skills:install target that delegates here. From a project root:
task skills:install
Bare-shell fallback for hosts without Task installed:
curl -fsSL https://gitea.d-ma.be/mathias/skills/raw/branch/main/install.sh | bash
Both forms are idempotent and re-runnable. On every run they:
git clone(orgit pull) this repo into~/.local/share/skills/— the canonical local checkout on every host.- Wire per-skill symlinks into the harnesses found on the host (see Wired harnesses).
Re-run after git pull upstream to pick up new skills or version
changes. CI tags every change as a vX.Y.Z release (see
Versioning).
Wired harnesses
| Harness | Target path | Notes |
|---|---|---|
| Claude Code (global) | ~/.claude/skills/<name> |
Visible in every Claude Code session on the host. |
| Claude Code (per-repo) | <repo>/.claude/skills/<name> |
Created when install is invoked inside a git repo (not the skills repo itself). Gitignored globally via **/.claude/skills/. |
| Crush | ~/.config/crush/skills/<name> |
Charmbracelet Crush — successor to opencode-ai/opencode (archived). |
| Antigravity | ~/.gemini/antigravity/skills/<name> |
Google Antigravity (VS Code extension). Our SKILL.md frontmatter (name + description) is already in the format Antigravity expects, so symlinks suffice — no manifest translation. |
Not wired (and why)
- opencode (
opencode-ai/opencode): archive notice; succeeded by Crush. Its only "skill"-like surface — Custom Commands at~/.config/opencode/commands/— is for user-facing prompt templates, not system-level instructions. Misaligned with how we use skills. Skipped. - gitea-resident agents (cobalt-dingo, agentsquad): they consume
skills via their containing project's
.claude/skillsdirectory (populated by the per-repo wirer when run from the host), or via the brain MCP. No special target needed.
Per-host env-var overrides
Each target path can be overridden by setting the matching env var before
running install.sh:
| Env var | Default |
|---|---|
SKILLS_REPO_URL |
https://gitea.d-ma.be/mathias/skills.git |
SKILLS_REF |
main (set to e.g. v0.1.0 to pin a release) |
SKILLS_CHECKOUT_DIR |
$HOME/.local/share/skills |
CLAUDE_SKILLS_DIR |
$HOME/.claude/skills |
CRUSH_SKILLS_DIR |
$HOME/.config/crush/skills |
ANTIGRAVITY_SKILLS_DIR |
$HOME/.gemini/antigravity/skills |
Versioning
Every commit to main is auto-tagged as a semver release by the
.gitea/workflows/release.yml action. Bump direction follows the commit
footer:
Bump-Type: major→X.0.0Bump-Type: minor→0.Y.0- anything else →
0.0.Z(patch, the default)
Consumer projects can pin a version by setting SKILLS_REF=v0.1.0
before task skills:install; default is main for always-current.
Contributing a skill
- Add a directory
<short-kebab-name>/. - Create
<short-kebab-name>/SKILL.md— start with one-paragraph purpose, then triggers ("use when …"), then mechanics. - Add a row to
SKILLS_INDEX.md(description + use-when). - Commit directly to
main. Conventional-commit prefix (feat:/fix:/docs:). AddBump-Type: minorfooter when adding a new skill or expanding scope; default patch covers edits.
This repo is markdown-only and public — never include secrets, client names, or anything under NDA in a skill.