mathias/skills
1
0
Fork 0
Code Issues 17 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
808af7b0202c779e850f3f92d279ac05bbfc178f
skills/SKILLS_INDEX.md
T
mathias 2cb6b54a5e
CI / Check / Test (push) Failing after 1s
Details
CI / Tag release (push) Skipped
Details
feat(skill): adr — the house format, and how to record a decision you cannot make yet 
Codifies cad's ADR template (frontmatter + Status/Context/Decision/Consequences/
Validation) and formalises the productive-tensions pattern that ADR-0001 already
does informally under "Known refinements, deliberately not built yet".

The RED run is why the skill is shaped this way. An unaided agent given a
genuinely-undecidable transport choice produced a strong ADR — it invented a
"Cost of reversal" section, wrote concrete revisit triggers, and reframed the
unanswerable question ("which is better?") into an answerable one ("which
option's correctness depends on the unsettled variables?"). So the reasoning was
not the gap. What it could not guess was the house format: it invented a bullet
header instead of the frontmatter that makes the corpus greppable, and it wrote
no Validation section at all.

The GREEN run then found eleven problems. Four mattered:

- **The Overview contradicted the Escalation section in its first sentence** —
  "An ADR is not documentation of a decision. It is the decision" against
  "decides nothing". Escalation is right; the flourish is gone.
- **The escalation clause trapped every agent-authored ADR.** The deciders are
  never the agent, so `proposed` is mandatory — and the skill separately called
  a lingering `proposed` a failure mode. Now: a `proposed` ADR with a named
  decider is waiting on a person and gets chased; one without is waiting on
  nobody. Naming that person is the deliverable, not a formality.
- **No filename or path convention, in a skill whose thesis is greppability.**
  Called "the biggest hole in the skill", correctly. Now docs/adr/NNNN-slug.md,
  with the cross-repo caveat that a bare number is ambiguous between repos.
- **"Pick the option whose correctness does not depend on the unknown" assumed
  such an option always exists.** It often does not — that is what makes a
  tension productive — and the rule would then push the author to manufacture a
  reason one of them is, which reads as reasoned and never gets re-examined. A
  fallback ladder now says: cheaper to reverse, lower switching cost, already
  built — and say that is why.

Also: `deciders` had no valid value while proposed; the body Status section
duplicated frontmatter with no precedence; the tension template silently dropped
the "address the strongest case against" requirement the plain format demands;
the preservation strategy — the actual technical content — got one angle bracket
while the easy parts got full templates; resolution triggers were singular for
tensions that routinely have several; and lineage/grill-me were listed as
cross-references at the bottom when they are pre-steps that change the content.

Closes #9
Bump-Type: minor
2026-08-29 15:24:11 +02:00

170 lines
12 KiB
Markdown
Raw Blame History

# 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.
<!-- BEGIN skills-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 |
| `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 |
| `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 |
<!-- END skills-table -->
## 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` |
Reference in New Issue View Git Blame Copy Permalink