mathias
83b069afba
Both skills shipped without an index row. The rows existed — on the feature branches deleted in #22 — and were dropped by the squash-merge that followed a directory reorg: the SKILL.md landed under skills/, the row did not. Nothing errored, the index just under-reported the library to every harness reading it. Adding two rows by hand fixes today and not tomorrow, so the assertion goes in `task check` via bin/check-index, following the same pattern as bin/should-skip-release: a real script with a real test, not untested logic buried in a Taskfile. It checks both directions — a skill with no row, and a row naming a skill that no longer exists. Verified by mutation: deleting the `dream` row turns `task check` red and the report names it. Closes #15 Bump-Type: patch
9.7 KiB
9.7 KiB
Engineering Skills Index
This index lists all available engineering skills. Load the full SKILL.md on demand.
| Skill | Description | Use when |
|---|---|---|
tdd |
Test-Driven Development enforcement | Starting any new feature or fixing a bug |
clean-code |
Clean code principles with Go adaptation | Code review, refactoring, new code |
solid |
SOLID principles with Go examples | Design review, architecture decisions |
code-review |
Code smell detection + Go-specific checklist | Pre-merge review |
refactoring |
Systematic refactoring methodology (Fowler) | When improving existing code |
test-design |
Dave Farley test design scoring (Farley Index) | Reviewing or writing tests |
cognitive-load |
Cognitive complexity analysis (CLI score) | Identifying hotspots, before refactoring |
problem-analysis |
Deep problem understanding before coding | Starting any non-trivial task |
user-stories |
Elephant Carpaccio story slicing | Breaking down features |
atdd |
Acceptance Test-Driven Development workflow | Feature development with acceptance criteria |
spec-driven-dev |
Spec-driven development for PMs | Writing specs and requirements |
planning |
Planning and task breakdown | Sprint planning, task decomposition |
gitea-ci |
Gitea CI/CD pipeline with act_runner, buildah, k3s, GitHub mirror | Setting up or debugging CI on this infra |
debug |
Hypothesis-first debugging discipline | Any test failure or bug whose cause is not immediately obvious |
feature-spec |
Implementation-level feature spec (tighter than spec-driven-dev) | Scoping one feature inside an already-specced project |
experiment-spec |
Rigorous experiment spec — falsifiable hypothesis, quantitative acceptance, null-result protocol | Scoping a research/ML phase instead of a feature |
playwright |
Playwright E2E testing — setup, HTMX patterns, SSE streams, CI wiring | Adding browser tests to any project with a web UI |
session-retrospective |
Surface non-obvious learnings from a session log | After a coding session ends, before context is lost |
trainer |
Two-phase brain curation (score candidates, write past quality gate) | Periodic brain pruning and curation |
dream |
Reflective consolidation pass over an agent's memory directory | Pruning/merging memory files, rebuilding a memory index |
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 |
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 |
telos-load |
Load TELOS intention substrate at session start | Starting any koala session; before architectural decisions; CAD pipeline entry |
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 |
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 |
discovery-framing |
Problem-before-solution discovery/framing method | Framing/validating a problem before any solution; opportunity sizing |
stage-gate-review |
Stage-gate product governance (go/no-go council) | Preparing a Product Council ask; building a go/no-go checklist; gate review |
web-shot |
Screenshot a running web UI via a koala k3s Playwright job | Visual verification of a running UI when no local browser exists |
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 |
superpowers-brainstorming |
Structured divergent brainstorming | Generating or expanding a set of ideas |
superpowers-writing-plans |
Writing implementation plans | Planning substantial work before coding |
superpowers-executing-plans |
Executing a written plan step by step | Running an approved plan to completion |
superpowers-dispatching-parallel-agents |
Fan work out across parallel subagents | Decomposing work for concurrent agents |
superpowers-subagent-driven-development |
Subagent-driven development workflow | Building via orchestrated subagents |
superpowers-systematic-debugging |
Hypothesis-first systematic debugging | Diagnosing a failure methodically |
superpowers-test-driven-development |
TDD discipline (superpowers variant) | Red → green → refactor on a change |
superpowers-verification-before-completion |
Verify behavior before claiming done | Before marking any task complete |
superpowers-requesting-code-review |
Requesting a code review well | Asking another agent/human to review |
superpowers-receiving-code-review |
Acting on received review feedback | Responding to review comments |
superpowers-finishing-a-development-branch |
Cleanly finishing/landing a dev branch | Wrapping a branch → merge/PR |
superpowers-using-git-worktrees |
Isolating work with git worktrees | Parallel/isolated work in a worktree |
superpowers-writing-skills |
Authoring new SKILL.md skills | Creating a new reusable skill |
superpowers-using-superpowers |
Meta: orienting in the superpowers set | Learning how to use the superpowers skills |
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 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
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)
│
└── 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 |