skills/SKILLS_INDEX.md

Engineering Skills Index

This index lists all available engineering skills. Load the full SKILL.md on demand.

The table is generated from each skill's frontmatter (summary, use_when, surfaces) by task index, and task check fails if it is out of date. Edit the SKILL.md, not the table.

Skill	Description	Use when	Surfaces
adr	Architecture Decision Records — house format, and how to record a decision you cannot make yet	Recording an architectural decision; revisiting one; or deciding between options where the right answer genuinely is not knowable yet	claude-code, library
atdd	Acceptance Test-Driven Development workflow	Feature development with acceptance criteria	claude-code, library
cad-babysit	Focused human-in-the-loop session working CAD's stuck queue (read-only)	Picking up whatever cad stuck flags, with a human present	claude-code, library
clean-code	Clean code principles with Go adaptation	Code review, refactoring, new code	claude-code, library
code-review	Code smell detection + Go-specific checklist	Pre-merge review	claude-code, library
cognitive-load	Cognitive complexity analysis (CLI score)	Identifying hotspots, before refactoring	claude-code, library
debug	Hypothesis-first debugging discipline	Any test failure or bug whose cause is not immediately obvious — or a bug report with no failure text, which this skill refuses rather than guesses at	claude-code, library
discovery-framing	Problem-before-solution discovery/framing method	Framing/validating a problem before any solution; opportunity sizing	claude-code, library
document-to-markdown	Read .docx/.xlsx/.pptx/.epub/.msg and other formats the Read tool cannot open	You need the contents of a binary document — Word, Excel, PowerPoint, EPUB, Outlook .msg, a zip of documents — and Read returns nothing useful	claude-code, library
dream	Reflective consolidation pass over an agent's memory directory	Pruning/merging memory files, rebuilding a memory index	claude-code, library, chat
experiment-spec	Rigorous experiment spec — falsifiable hypothesis, quantitative acceptance, null-result protocol	Scoping a research/ML phase instead of a feature	claude-code, library
feature-spec	Implementation-level feature spec (tighter than spec-driven-dev)	Scoping one feature inside an already-specced project	claude-code, library
gitea-ci	Gitea CI/CD pipeline with act_runner, buildah, k3s, GitHub mirror	Setting up or debugging CI on this infra	claude-code, library
grill-me	Structured plan interrogation — Quick Poke, Full Grill, Pre-mortem	Stress-testing a plan before committing; end of Diamond 1; before promoting to pre-prod	claude-code, library, chat
lineage	Backward decision archaeology — was this tried before, and does the reason it failed still hold	Before proposing something that feels new; when an idea keeps resurfacing; when you inherit code whose reason is gone	claude-code, library
own-the-task	Delegation ownership — Intake → Brief → Plan → Execute	A task is handed over open-ended; "take this off my plate"; before a plan exists	claude-code, library, chat
planning	Planning and task breakdown	Sprint planning, task decomposition	claude-code, library
playwright	Playwright E2E testing — setup, HTMX patterns, SSE streams, CI wiring	Adding browser tests to any project with a web UI	claude-code, library
problem-analysis	Deep problem understanding before coding	Starting any non-trivial task	claude-code, library
refactoring	Systematic refactoring methodology (Fowler)	When improving existing code	claude-code, library
regulatory-risk-assessment	Structured risk register for regulated-industry features	Filing a CAD issue (needs Risk: level); features touching payments, auth, external APIs, user data	claude-code, library
secret-hygiene	Stop credentials rendering into the session transcript; safe rotation chain when one leaks	Before any kubectl/SOPS/token command; after a confirmed leak	claude-code, library
session-retrospective	Surface non-obvious learnings from a session log	After a coding session ends, before context is lost	claude-code, library
solid	SOLID principles with Go examples	Design review, architecture decisions	claude-code, library
spec-driven-dev	Spec-driven development for PMs	Writing specs and requirements	claude-code, library
stage-gate-review	Stage-gate product governance (go/no-go council)	Preparing a Product Council ask; building a go/no-go checklist; gate review	claude-code, library
superpowers-brainstorming	Structured divergent brainstorming	Generating or expanding a set of ideas	claude-code, library
superpowers-dispatching-parallel-agents	Fan work out across parallel subagents	Decomposing work for concurrent agents	claude-code, library
superpowers-executing-plans	Executing a written plan step by step	Running an approved plan to completion	claude-code, library
superpowers-finishing-a-development-branch	Cleanly finishing/landing a dev branch	Wrapping a branch → merge/PR	claude-code, library
superpowers-receiving-code-review	Acting on received review feedback	Responding to review comments	claude-code, library
superpowers-requesting-code-review	Requesting a code review well	Asking another agent/human to review	claude-code, library
superpowers-subagent-driven-development	Subagent-driven development workflow	Building via orchestrated subagents	claude-code, library
superpowers-using-git-worktrees	Isolating work with git worktrees	Parallel/isolated work in a worktree	claude-code, library
superpowers-using-superpowers	Meta: orienting in the superpowers set	Learning how to use the superpowers skills	claude-code, library
superpowers-verification-before-completion	Verify behavior before claiming done	Before marking any task complete	claude-code, library
superpowers-writing-plans	Writing implementation plans	Planning substantial work before coding	claude-code, library
superpowers-writing-skills	Authoring new SKILL.md skills	Creating a new reusable skill	claude-code, library
tdd	Test-Driven Development enforcement	Starting any new feature or fixing a bug	claude-code, library
telos-load	Load TELOS intention substrate at session start	Starting any koala session; before architectural decisions; CAD pipeline entry	claude-code, library
test-design	Dave Farley test design scoring (Farley Index)	Reviewing or writing tests	claude-code, library
traceability	Forward trace — requirement to decision to commit to verification to release, and what cannot be checked	Proving why a change exists; auditing a claim; before an attestation or a compliance ask	claude-code, library
trainer	Two-phase brain curation (score candidates, write past quality gate)	Periodic brain pruning and curation	claude-code, library
user-stories	Elephant Carpaccio story slicing	Breaking down features	claude-code, library
web-shot	Screenshot a running web UI via a koala k3s Playwright job	Visual verification of a running UI when no local browser exists	claude-code, library

Wiring into tools

This repo is the canonical home, and it is delivered two different ways.

Claude Code — install the plugin

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 through one managed directory, never one link per skill per harness:

~/.agents/skills/          (real directory; Pi reads it directly)
~/.agents/skills/tdd       -> $SKILLS_CHECKOUT_DIR/skills/tdd
~/.agents/skills/xlsx      -> $SKILLS_EXTRA_SOURCES entry
~/.config/crush/skills     -> ~/.agents/skills
~/.config/opencode/skills  -> ~/.agents/skills

Total links are N + one per harness. SKILLS_EXTRA_SOURCES (colon-separated directories) lets a second library — Anthropic's official set, for instance — live alongside this one instead of being displaced by it; name collisions are logged rather than silently resolved, and the checkout wins (#27).

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 into a source nobody configured, skills in the checkout with no link, stray entries, leftover Claude symlinks, and a Claude Code plugin sitting on an older generation than the host already has. It also runs automatically at session start via the plugin, so drift announces itself instead of waiting to be found.

Skill Relationships

problem-analysis
    │
    └── user-stories
            │
            ├── spec-driven-dev (PM-kickoff lifecycle)
            │       │
            │       ├── feature-spec (per-feature, mid-implementation)
            │       │       │
            │       │       └── planning
            │       │               │
            │       │               └── atdd ──→ tdd (foundation)
            │       │                        ├──→ debug (when tests fail)
            │       │                        ├──→ clean-code (REFACTOR phase)
            │       │                        └──→ test-design (review)
            │       │
            │       └── experiment-spec (research/ML phase, instead of feature-spec)
            │
            └── planning

code-review ──→ refactoring ──→ clean-code
                                    └──→ solid

(post-session)
session-retrospective ──→ trainer ──→ brain (via brain_write)

(planning & convergence)
own-the-task ──→ grill-me (intent first, then stress-test the plan)
grill-me ──→ planning (after plan is sharpened)
         ──→ spec-driven-dev (after hypothesis is validated)

Quick Triggers

Situation	Load
"Build this feature"	problem-analysis → spec-driven-dev → planning → atdd
"Fix this bug"	tdd
"Review this code"	code-review
"Refactor this"	refactoring + clean-code
"Design this system"	solid + problem-analysis
"Break this down into stories"	user-stories
"Write a spec"	spec-driven-dev
"This code is hard to understand"	cognitive-load
"Review these tests"	test-design
"Set up CI for this project"	gitea-ci
"CI pipeline is failing / not triggering"	gitea-ci
"Commit directly to main? Or branch?"	TBD: commit to main unless parallel agents are active (see gitea-ci SKILL §Trunk-Based Development)
"Grill me / stress-test this / is this ready?"	grill-me
"End of Diamond 1 — should we build this?"	grill-me (Full Grill)
"About to promote to pre-prod"	grill-me (Pre-mortem)
"Take this off my plate / own this / act as my AI employee"	own-the-task
"What are the risks?" / "compliance gate" / "risk register"	regulatory-risk-assessment
"Start of session" / "load TELOS" / "what are we optimizing toward?"	telos-load