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:

1. git clone (or git pull) this repo into ~/.local/share/skills/ — the canonical local checkout on every host.
2. 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/skills directory (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.0
• Bump-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

1. Add a directory <short-kebab-name>/.
2. Create <short-kebab-name>/SKILL.md — start with one-paragraph purpose, then triggers ("use when …"), then mechanics.
3. Add a row to SKILLS_INDEX.md (description + use-when).
4. Commit directly to main. Conventional-commit prefix (feat: / fix: / docs:). Add Bump-Type: minor footer 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.