feat(index): generate the skills table from frontmatter

Second half of #29. The index was hand-maintained and had already drifted
once: dream and experiment-spec shipped with no row, their rows lost to a
squash-merge after a directory reorg. bin/check-index caught that after the
fact; generating removes the class.

The curated summary and trigger move into each SKILL.md as `summary:` and
`use_when:`, carried over verbatim from the existing table rather than derived
from `description:` — description is a paragraph written for model selection,
and truncating it would have produced a worse table than the one it replaced.
Knowledge now lives once, next to the skill it describes, which is the argument
that made a hand-maintained index the wrong shape to begin with.

The table is written between markers, so the wiring docs, the relationships
tree and the trigger table below it are untouched — those are prose, not data.
Rows are alphabetical now; the conceptual grouping the old order carried lives
in the relationships tree, which is the better place for it. A fourth column
shows each skill's surfaces, which is what makes #29's field visible rather
than merely enforced.

bin/check-index and its test are deleted: a generated table cannot drift in
either direction, so `generate-index --check` subsumes both of its assertions.
Verified by mutation — deleting the tdd row turns `task check` red with
"SKILLS_INDEX.md is out of date".

Closes #29
Bump-Type: minor

SKILLS_INDEX.md

@@ -2,50 +2,56 @@
 
 This index lists all available engineering skills. Load the full SKILL.md on demand.
 
-| Skill | Description | Use when |
+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
-| `tdd` | Test-Driven Development enforcement | Starting any new feature or fixing a bug |
+the SKILL.md, not the table.
-| `clean-code` | Clean code principles with Go adaptation | Code review, refactoring, new code |
+
-| `solid` | SOLID principles with Go examples | Design review, architecture decisions |
+<!-- BEGIN skills-table -->
-| `code-review` | Code smell detection + Go-specific checklist | Pre-merge review |
+| Skill | Description | Use when | Surfaces |
-| `refactoring` | Systematic refactoring methodology (Fowler) | When improving existing code |
+|-------|-------------|----------|----------|
-| `test-design` | Dave Farley test design scoring (Farley Index) | Reviewing or writing tests |
+| `atdd` | Acceptance Test-Driven Development workflow | Feature development with acceptance criteria | claude-code, library |
-| `cognitive-load` | Cognitive complexity analysis (CLI score) | Identifying hotspots, before refactoring |
+| `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 |
-| `problem-analysis` | Deep problem understanding before coding | Starting any non-trivial task |
+| `clean-code` | Clean code principles with Go adaptation | Code review, refactoring, new code | claude-code, library |
-| `user-stories` | Elephant Carpaccio story slicing | Breaking down features |
+| `code-review` | Code smell detection + Go-specific checklist | Pre-merge review | claude-code, library |
-| `atdd` | Acceptance Test-Driven Development workflow | Feature development with acceptance criteria |
+| `cognitive-load` | Cognitive complexity analysis (CLI score) | Identifying hotspots, before refactoring | claude-code, library |
-| `spec-driven-dev` | Spec-driven development for PMs | Writing specs and requirements |
+| `debug` | Hypothesis-first debugging discipline | Any test failure or bug whose cause is not immediately obvious | claude-code, library |
-| `planning` | Planning and task breakdown | Sprint planning, task decomposition |
+| `discovery-framing` | Problem-before-solution discovery/framing method | Framing/validating a problem before any solution; opportunity sizing | claude-code, library |
-| `gitea-ci` | Gitea CI/CD pipeline with act_runner, buildah, k3s, GitHub mirror | Setting up or debugging CI on this infra |
+| `dream` | Reflective consolidation pass over an agent's memory directory | Pruning/merging memory files, rebuilding a memory index | claude-code, library, chat |
-| `debug` | Hypothesis-first debugging discipline | Any test failure or bug whose cause is not immediately obvious |
+| `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 |
+| `feature-spec` | Implementation-level feature spec (tighter than spec-driven-dev) | Scoping one feature inside an already-specced project | claude-code, library |
-| `experiment-spec` | Rigorous experiment spec — falsifiable hypothesis, quantitative acceptance, null-result protocol | Scoping a research/ML phase instead of a feature |
+| `gitea-ci` | Gitea CI/CD pipeline with act_runner, buildah, k3s, GitHub mirror | Setting up or debugging CI on this infra | claude-code, library |
-| `playwright` | Playwright E2E testing — setup, HTMX patterns, SSE streams, CI wiring | Adding browser tests to any project with a web UI |
+| `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 |
-| `session-retrospective` | Surface non-obvious learnings from a session log | After a coding session ends, before context is lost |
+| `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 |
-| `trainer` | Two-phase brain curation (score candidates, write past quality gate) | Periodic brain pruning and curation |
+| `planning` | Planning and task breakdown | Sprint planning, task decomposition | claude-code, library |
-| `dream` | Reflective consolidation pass over an agent's memory directory | Pruning/merging memory files, rebuilding a memory index |
+| `playwright` | Playwright E2E testing — setup, HTMX patterns, SSE streams, CI wiring | Adding browser tests to any project with a web UI | 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 |
+| `problem-analysis` | Deep problem understanding before coding | Starting any non-trivial task | 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 |
+| `refactoring` | Systematic refactoring methodology (Fowler) | When improving existing code | claude-code, library |
-| `telos-load` | Load TELOS intention substrate at session start | Starting any koala session; before architectural decisions; CAD pipeline entry |
+| `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 |
+| `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 |
-| `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 |
+| `session-retrospective` | Surface non-obvious learnings from a session log | After a coding session ends, before context is lost | claude-code, library |
-| `discovery-framing` | Problem-before-solution discovery/framing method | Framing/validating a problem before any solution; opportunity sizing |
+| `solid` | SOLID principles with Go examples | Design review, architecture decisions | 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 |
+| `spec-driven-dev` | Spec-driven development for PMs | Writing specs and requirements | 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 |
+| `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 |
-| `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 | claude-code, library |
-| `superpowers-brainstorming` | Structured divergent brainstorming | Generating or expanding a set of ideas |
+| `superpowers-dispatching-parallel-agents` | Fan work out across parallel subagents | Decomposing work for concurrent agents | claude-code, library |
-| `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 | claude-code, library |
-| `superpowers-executing-plans` | Executing a written plan step by step | Running an approved plan to completion |
+| `superpowers-finishing-a-development-branch` | Cleanly finishing/landing a dev branch | Wrapping a branch → merge/PR | claude-code, library |
-| `superpowers-dispatching-parallel-agents` | Fan work out across parallel subagents | Decomposing work for concurrent agents |
+| `superpowers-receiving-code-review` | Acting on received review feedback | Responding to review comments | claude-code, library |
-| `superpowers-subagent-driven-development` | Subagent-driven development workflow | Building via orchestrated subagents |
+| `superpowers-requesting-code-review` | Requesting a code review well | Asking another agent/human to review | claude-code, library |
-| `superpowers-systematic-debugging` | Hypothesis-first systematic debugging | Diagnosing a failure methodically |
+| `superpowers-subagent-driven-development` | Subagent-driven development workflow | Building via orchestrated subagents | claude-code, library |
-| `superpowers-verification-before-completion` | Verify behavior before claiming done | Before marking any task complete |
+| `superpowers-systematic-debugging` | Hypothesis-first systematic debugging | Diagnosing a failure methodically | claude-code, library |
-| `superpowers-requesting-code-review` | Requesting a code review well | Asking another agent/human to review |
+| `superpowers-using-git-worktrees` | Isolating work with git worktrees | Parallel/isolated work in a worktree | claude-code, library |
-| `superpowers-receiving-code-review` | Acting on received review feedback | Responding to review comments |
+| `superpowers-using-superpowers` | Meta: orienting in the superpowers set | Learning how to use the superpowers skills | claude-code, library |
-| `superpowers-finishing-a-development-branch` | Cleanly finishing/landing a dev branch | Wrapping a branch → merge/PR |
+| `superpowers-verification-before-completion` | Verify behavior before claiming done | Before marking any task complete | claude-code, library |
-| `superpowers-using-git-worktrees` | Isolating work with git worktrees | Parallel/isolated work in a worktree |
+| `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 |
+| `superpowers-writing-skills` | Authoring new SKILL.md skills | Creating a new reusable skill | claude-code, library |
-| `superpowers-using-superpowers` | Meta: orienting in the superpowers set | Learning how to use the superpowers skills |
+| `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
 

Taskfile.yml

@@ -61,8 +61,13 @@ tasks:
         done
         exit $fail
 
+  index:
+    desc: 'Regenerate SKILLS_INDEX.md''s table from skill frontmatter.'
+    cmds:
+      - "'{{.TASKFILE_DIR}}/bin/generate-index' '{{.TASKFILE_DIR}}'"
+
   check:
-    desc: 'Structure gate — layout, frontmatter, manifest/tag parity. Runs in CI.'
+    desc: 'Structure gate — layout, frontmatter, surfaces, generated index, manifest/tag parity. Runs in CI.'
     cmds:
       - |
         fail=0
@@ -94,10 +99,11 @@ tasks:
           count=$((count + 1))
         done
 
-        # 3. SKILLS_INDEX.md lists exactly the skills that exist. Delegated
+        # 3. SKILLS_INDEX.md's table is generated from frontmatter, so the
-        #    to bin/check-index so the rule is covered by
+        #    assertion is that regenerating it changes nothing. This replaces
-        #    tests/check_index_test.sh rather than living untested here.
+        #    bin/check-index: a generated table cannot drift in either
-        sh '{{.TASKFILE_DIR}}/bin/check-index' '{{.TASKFILE_DIR}}' || fail=1
+        #    direction, so there is no separate rule left to check.
+        sh '{{.TASKFILE_DIR}}/bin/generate-index' --check '{{.TASKFILE_DIR}}' || fail=1
 
         # 4. Every skill says which surfaces it ships to, and names only
         #    surfaces that exist — a wrong value silently drops a skill from a

bin/check-index

@@ -1,42 +0,0 @@
-#!/bin/sh
-# check-index — asserts SKILLS_INDEX.md lists exactly the skills that exist.
-#
-# The index is hand-maintained and drifts silently in both directions: a skill
-# ships with no row (`dream` and `experiment-spec` did — their rows lived on
-# branches squash-merged after a directory reorg, so the SKILL.md landed and
-# the row did not, #15), or a row outlives the skill it names. Neither errors
-# anywhere; the library just misreports itself to every harness that reads it.
-#
-# Usage: check-index [checkout-root]   (defaults to this script's repo root)
-
-set -u
-
-ROOT=${1:-$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)}
-INDEX="$ROOT/SKILLS_INDEX.md"
-fail=0
-
-if [ ! -f "$INDEX" ]; then
-  echo "ERROR: missing SKILLS_INDEX.md" >&2
-  exit 1
-fi
-
-# A row is a table line whose first cell is the skill name in backticks.
-listed=$(sed -n 's/^|[[:space:]]*`\([^`]*\)`.*/\1/p' "$INDEX" | sort -u)
-
-for dir in "$ROOT"/skills/*/; do
-  name=$(basename "$dir")
-  [ -f "$dir/SKILL.md" ] || continue
-  printf '%s\n' "$listed" | grep -qx "$name" || {
-    echo "ERROR: skills/$name has no row in SKILLS_INDEX.md" >&2
-    fail=1
-  }
-done
-
-for name in $listed; do
-  [ -f "$ROOT/skills/$name/SKILL.md" ] || {
-    echo "ERROR: SKILLS_INDEX.md lists '$name', which has no skills/$name/SKILL.md" >&2
-    fail=1
-  }
-done
-
-exit $fail

bin/generate-index

@@ -0,0 +1,85 @@
+#!/bin/sh
+# generate-index — rebuild SKILLS_INDEX.md's table from skill frontmatter.
+#
+# The index was hand-maintained and drifted: `dream` and `experiment-spec`
+# shipped with no row at all, because their rows lived on branches that were
+# squash-merged after a directory reorg (#15). A gate catches that after the
+# fact; generating removes the class (#29).
+#
+# The curated summary and trigger live in each SKILL.md as `summary:` and
+# `use_when:` rather than being derived from `description:` — description is a
+# paragraph written for model selection, and truncating it produces a worse
+# table than the one being replaced.
+#
+# Everything outside the markers is left untouched: the wiring docs, the
+# relationships tree and the trigger table are prose, not data.
+#
+#   generate-index [root]           rewrite the table in place
+#   generate-index --check [root]   exit 1 if the table is out of date
+
+set -u
+
+CHECK=0
+if [ "${1:-}" = "--check" ]; then CHECK=1; shift; fi
+ROOT=${1:-$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)}
+INDEX="$ROOT/SKILLS_INDEX.md"
+
+BEGIN='<!-- BEGIN skills-table -->'
+END='<!-- END skills-table -->'
+
+[ -f "$INDEX" ] || { echo "ERROR: missing $INDEX" >&2; exit 1; }
+grep -qF "$BEGIN" "$INDEX" || { echo "ERROR: $INDEX has no $BEGIN marker" >&2; exit 1; }
+grep -qF "$END" "$INDEX" || { echo "ERROR: $INDEX has no $END marker" >&2; exit 1; }
+
+# field <file> <key> — a scalar frontmatter value, quotes stripped.
+field() {
+  sed -n "s/^$2:[[:space:]]*//p" "$1" | head -1 | sed 's/^"//; s/"$//'
+}
+
+table=$(mktemp)
+fail=0
+
+{
+  printf '| Skill | Description | Use when | Surfaces |\n'
+  printf '|-------|-------------|----------|----------|\n'
+} > "$table"
+
+for dir in "$ROOT"/skills/*/; do
+  [ -f "$dir/SKILL.md" ] || continue
+  name=$(basename "$dir")
+  summary=$(field "$dir/SKILL.md" summary)
+  use_when=$(field "$dir/SKILL.md" use_when)
+  surfaces=$(field "$dir/SKILL.md" surfaces | tr -d '[]')
+
+  if [ -z "$summary" ] || [ -z "$use_when" ]; then
+    echo "ERROR: skills/$name has no 'summary:'/'use_when:' — the index table is generated from them" >&2
+    fail=1
+    continue
+  fi
+  printf '| `%s` | %s | %s | %s |\n' "$name" "$summary" "$use_when" "$surfaces" >> "$table"
+done
+
+if [ "$fail" -ne 0 ]; then
+  rm -f "$table"
+  exit 1
+fi
+
+out=$(mktemp)
+awk -v begin="$BEGIN" -v end="$END" -v tablefile="$table" '
+  $0 == begin { print; while ((getline line < tablefile) > 0) print line; skip = 1; next }
+  $0 == end   { print; skip = 0; next }
+  !skip       { print }
+' "$INDEX" > "$out"
+rm -f "$table"
+
+if [ "$CHECK" -eq 1 ]; then
+  if cmp -s "$out" "$INDEX"; then
+    rm -f "$out"
+    exit 0
+  fi
+  rm -f "$out"
+  echo "ERROR: SKILLS_INDEX.md is out of date — run 'task index' and commit the result" >&2
+  exit 1
+fi
+
+mv "$out" "$INDEX"

skills/atdd/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: atdd
 surfaces: [claude-code, library]
+summary: "Acceptance Test-Driven Development workflow"
+use_when: "Feature development with acceptance criteria"
 description: Implement user stories using the ATDD workflow — Red (failing acceptance test) → Green (minimal implementation) → Refactor. One story at a time.
 ---
 

skills/cad-babysit/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: cad-babysit
 surfaces: [claude-code, library]
+summary: "Focused human-in-the-loop session working CAD's stuck queue (read-only)"
+use_when: "Picking up whatever `cad stuck` flags, with a human present"
 description: Focused human-in-the-loop session working CAD's stuck queue (cad-stuck output). Read-only — diagnoses, never dispatches, arms a label, or closes an issue. Use when picking up whatever CAD has run into trouble on, with a human present.
 ---
 

skills/clean-code/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: clean-code
 surfaces: [claude-code, library]
+summary: "Clean code principles with Go adaptation"
+use_when: "Code review, refactoring, new code"
 description: Write code that humans can read, understand, and safely change. Apply SOLID, GRASP, and Clean Code principles during the REFACTOR phase of TDD.
 ---
 

skills/code-review/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: code-review
 surfaces: [claude-code, library]
+summary: "Code smell detection + Go-specific checklist"
+use_when: "Pre-merge review"
 description: Systematic code smell detection and Go-specific review checklist. Load before any pre-merge review.
 ---
 

skills/cognitive-load/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: cognitive-load
 surfaces: [claude-code, library]
+summary: "Cognitive complexity analysis (CLI score)"
+use_when: "Identifying hotspots, before refactoring"
 description: Measure how much mental effort a codebase demands from developers. Use when identifying hotspots, before architectural decisions, or when code feels hard to understand.
 ---
 

skills/debug/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: debug
 surfaces: [claude-code, library]
+summary: "Hypothesis-first debugging discipline"
+use_when: "Any test failure or bug whose cause is not immediately obvious"
 description: Systematic hypothesis-first debugging. Generate 3-5 ranked hypotheses with verification steps before suggesting any fix. Use when encountering a bug, test failure, or unexpected behavior.
 ---
 

skills/discovery-framing/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: discovery-framing
 surfaces: [claude-code, library]
+summary: "Problem-before-solution discovery/framing method"
+use_when: "Framing/validating a problem before any solution; opportunity sizing"
 description: Run the discovery / framing phase of product innovation — define and quantify a focused customer problem BEFORE any solution exists. Four movements: understand the problem space, learn about customers, identify and size problems, decide pursue/table/kill. Produces a problem brief per prioritized opportunity. Use when an idea is still vague, when someone is jumping to solutions before the problem is validated, when scoping early research, or when deciding which problems are worth pursuing. Trigger phrases include "frame the problem", "discovery", "problem statement", "is this worth building", "early research", "opportunity sizing", "we have an idea for", "how might we", "what problem are we solving".
 ---
 

skills/dream/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: dream
 surfaces: [claude-code, library, chat]
+summary: "Reflective consolidation pass over an agent's memory directory"
+use_when: "Pruning/merging memory files, rebuilding a memory index"
 description: >
   Run a "dream" — a reflective memory consolidation pass over an agent's memory
   directory. Use this skill whenever the user says "dream", "run a dream", "consolidate

skills/experiment-spec/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: experiment-spec
 surfaces: [claude-code, library]
+summary: "Rigorous experiment spec — falsifiable hypothesis, quantitative acceptance, null-result protocol"
+use_when: "Scoping a research/ML phase instead of a feature"
 description: Write a rigorous experiment spec for a research phase before any code or training runs. Use instead of feature-spec for scientific/ML research projects. Enforces falsifiable hypothesis, quantitative acceptance criteria, baseline comparison, and null-result protocol.
 ---
 

skills/feature-spec/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: feature-spec
 surfaces: [claude-code, library]
+summary: "Implementation-level feature spec (tighter than spec-driven-dev)"
+use_when: "Scoping one feature inside an already-specced project"
 description: Write a tight implementation-level spec for a single feature or component before coding it. Use after a project-level spec exists (see spec-driven-dev) and you need to nail down one feature inside it.
 ---
 

skills/gitea-ci/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: gitea-ci
 surfaces: [claude-code, library]
+summary: "Gitea CI/CD pipeline with act_runner, buildah, k3s, GitHub mirror"
+use_when: "Setting up or debugging CI on this infra"
 description: End-to-end Gitea CI/CD setup with self-hosted act_runner, quality gate pipeline, shared buildctl image-build script, k3s deploy, and GitHub mirror. Covers act_runner-specific gotchas that are not documented anywhere.
 ---
 

skills/grill-me/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: grill-me
 surfaces: [claude-code, library, chat]
+summary: "Structured plan interrogation — Quick Poke, Full Grill, Pre-mortem"
+use_when: "Stress-testing a plan before committing; end of Diamond 1; before promoting to pre-prod"
 description: Critically interrogates plans, ideas, and proposals to make them sharper, more robust, and better grounded — with the explicit goal of producing a meaningfully better plan by the end. Use this skill whenever the user wants to stress-test a plan, prepare for hard questions, check if an idea is ready to act on, validate a hypothesis, or explicitly asks to be challenged, questioned, or grilled. Also trigger when a conversation has been exploring an idea for a while and it's time to converge — use this skill to check if the idea is actually ready. Trigger phrases include "grill me", "challenge this", "poke holes", "am I missing something", "is this ready", "stress-test this", "devil's advocate", "what am I not seeing".
 ---
 

skills/own-the-task/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: own-the-task
 surfaces: [claude-code, library, chat]
+summary: "Delegation ownership — Intake → Brief → Plan → Execute"
+use_when: "A task is handed over open-ended; \"take this off my plate\"; before a plan exists"
 description: Take ownership of a delegated task like a hired employee — interview first, write a handover brief, propose a plan, then execute. Use whenever the user says "take this off my plate", "own this", "act as my AI employee", "interview me first", "ask me questions before you start", or delegates anything open-ended where the real goal, the why, and the definition of done are not yet on the table. Trigger even when "interview" is never said — any delegation where getting the intent wrong would waste the whole effort belongs here.
 ---
 

skills/planning/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: planning
 surfaces: [claude-code, library]
+summary: "Planning and task breakdown"
+use_when: "Sprint planning, task decomposition"
 description: Decompose work into small, verifiable, ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable units.
 ---
 

skills/playwright/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: playwright
 surfaces: [claude-code, library]
+summary: "Playwright E2E testing — setup, HTMX patterns, SSE streams, CI wiring"
+use_when: "Adding browser tests to any project with a web UI"
 description: Add and run Playwright E2E tests for any project with a web UI — covers setup, HTMX-specific patterns, SSE/streaming, Taskfile integration, and CI wiring.
 ---
 

skills/problem-analysis/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: problem-analysis
 surfaces: [claude-code, library]
+summary: "Deep problem understanding before coding"
+use_when: "Starting any non-trivial task"
 description: Deeply understand a problem before coding begins. Identify the real problem, stakeholders, constraints, and success criteria. Use before starting any non-trivial feature.
 ---
 

skills/refactoring/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: refactoring
 surfaces: [claude-code, library]
+summary: "Systematic refactoring methodology (Fowler)"
+use_when: "When improving existing code"
 description: Systematic refactoring methodology based on Martin Fowler's catalog. Apply during the REFACTOR phase of TDD, never while making code changes that modify behavior.
 ---
 

skills/regulatory-risk-assessment/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: regulatory-risk-assessment
 surfaces: [claude-code, library]
+summary: "Structured risk register for regulated-industry features"
+use_when: "Filing a CAD issue (needs Risk: level); features touching payments, auth, external APIs, user data"
 description: Produce a structured regulatory risk assessment / risk-register entry for regulated-industry features (banking, payments, PSD2/PSR, DORA, AML). Use when filing a CAD issue that needs a Risk:LOW/MEDIUM/HIGH level, or designing features touching payments, auth, data storage, or external APIs ("what are the risks?", "compliance gate", "risk register").
 ---
 

skills/secret-hygiene/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: secret-hygiene
 surfaces: [claude-code, library]
+summary: "Stop credentials rendering into the session transcript; safe rotation chain when one leaks"
+use_when: "Before any kubectl/SOPS/token command; after a confirmed leak"
 description: Prevent agent sessions from rendering credentials into the transcript, and recover safely when one leaks. Load BEFORE any command that touches credentials - kubectl exec/env/describe, kubectl get secret, whole-file SOPS decryption, token generation or rotation, envFrom inspection, or edits to encrypted config. Also load when a credential has already been exposed and a rotation chain is needed. Triggers - "rotate this token", "decrypt the config", "check the env var", "leaked credential", "did that print a secret", "why is this secret wrong".
 ---
 

skills/session-retrospective/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: session-retrospective
 surfaces: [claude-code, library]
+summary: "Surface non-obvious learnings from a session log"
+use_when: "After a coding session ends, before context is lost"
 description: Review a completed coding session (from brain/sessions/*.jsonl) and surface non-obvious learnings worth preserving. Use after a session ends, before context is lost.
 ---
 

skills/solid/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: solid
 surfaces: [claude-code, library]
+summary: "SOLID principles with Go examples"
+use_when: "Design review, architecture decisions"
 description: Apply SOLID design principles in Go. Use during architecture decisions, design reviews, and when adding new abstractions.
 ---
 

skills/spec-driven-dev/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: spec-driven-dev
 surfaces: [claude-code, library]
+summary: "Spec-driven development for PMs"
+use_when: "Writing specs and requirements"
 description: Write a structured specification before writing any code. Use when starting a new project, feature, or significant change. Adapted for a PM-first workflow where why comes before how.
 ---
 

skills/stage-gate-review/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: stage-gate-review
 surfaces: [claude-code, library]
+summary: "Stage-gate product governance (go/no-go council)"
+use_when: "Preparing a Product Council ask; building a go/no-go checklist; gate review"
 description: Run or prepare a stage-gate product governance review — the go/no-go checkpoint where a council approves an initiative to advance through fixed innovation stages (Frame → Concept → Prototype → Validate → Scale), each gate guarded by a per-discipline readiness checklist. Use when preparing a Product Council / steering-group ask, building a go/no-go checklist, designing an innovation governance process, or auditing whether an initiative is genuinely ready to advance vs faking the gate. Trigger phrases include "stage gate", "product council", "go/no-go", "advance to the next stage", "is this ready to progress", "gate review", "phase gate", "innovation governance".
 ---
 

skills/superpowers-brainstorming/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: brainstorming
 surfaces: [claude-code, library]
+summary: "Structured divergent brainstorming"
+use_when: "Generating or expanding a set of ideas"
 description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
 ---
 

skills/superpowers-dispatching-parallel-agents/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: dispatching-parallel-agents
 surfaces: [claude-code, library]
+summary: "Fan work out across parallel subagents"
+use_when: "Decomposing work for concurrent agents"
 description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
 ---
 

skills/superpowers-executing-plans/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: executing-plans
 surfaces: [claude-code, library]
+summary: "Executing a written plan step by step"
+use_when: "Running an approved plan to completion"
 description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
 ---
 

skills/superpowers-finishing-a-development-branch/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: finishing-a-development-branch
 surfaces: [claude-code, library]
+summary: "Cleanly finishing/landing a dev branch"
+use_when: "Wrapping a branch → merge/PR"
 description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
 ---
 

skills/superpowers-receiving-code-review/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: receiving-code-review
 surfaces: [claude-code, library]
+summary: "Acting on received review feedback"
+use_when: "Responding to review comments"
 description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
 ---
 

skills/superpowers-requesting-code-review/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: requesting-code-review
 surfaces: [claude-code, library]
+summary: "Requesting a code review well"
+use_when: "Asking another agent/human to review"
 description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
 ---
 

skills/superpowers-subagent-driven-development/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: subagent-driven-development
 surfaces: [claude-code, library]
+summary: "Subagent-driven development workflow"
+use_when: "Building via orchestrated subagents"
 description: Use when executing implementation plans with independent tasks in the current session
 ---
 

skills/superpowers-systematic-debugging/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: systematic-debugging
 surfaces: [claude-code, library]
+summary: "Hypothesis-first systematic debugging"
+use_when: "Diagnosing a failure methodically"
 description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
 ---
 

skills/superpowers-using-git-worktrees/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: using-git-worktrees
 surfaces: [claude-code, library]
+summary: "Isolating work with git worktrees"
+use_when: "Parallel/isolated work in a worktree"
 description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
 ---
 

skills/superpowers-using-superpowers/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: using-superpowers
 surfaces: [claude-code, library]
+summary: "Meta: orienting in the superpowers set"
+use_when: "Learning how to use the superpowers skills"
 description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
 ---
 

skills/superpowers-verification-before-completion/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: verification-before-completion
 surfaces: [claude-code, library]
+summary: "Verify behavior before claiming done"
+use_when: "Before marking any task complete"
 description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
 ---
 

skills/superpowers-writing-plans/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: writing-plans
 surfaces: [claude-code, library]
+summary: "Writing implementation plans"
+use_when: "Planning substantial work before coding"
 description: Use when you have a spec or requirements for a multi-step task, before touching code
 ---
 

skills/superpowers-writing-skills/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: writing-skills
 surfaces: [claude-code, library]
+summary: "Authoring new SKILL.md skills"
+use_when: "Creating a new reusable skill"
 description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
 ---
 

skills/tdd/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: tdd
 surfaces: [claude-code, library]
+summary: "Test-Driven Development enforcement"
+use_when: "Starting any new feature or fixing a bug"
 description: Write failing tests first, then minimal code to pass. Non-negotiable for all new features and bug fixes.
 ---
 

skills/telos-load/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: telos-load
 surfaces: [claude-code, library]
+summary: "Load TELOS intention substrate at session start"
+use_when: "Starting any koala session; before architectural decisions; CAD pipeline entry"
 description: Load TELOS — the intention substrate (problems, goals, strategies, status) — into a session at start so every decision traces to a goal. Use when starting any koala session, before architectural decisions, or as the CAD pipeline entry point ("load TELOS", "what are we optimizing toward?").
 ---
 

skills/test-design/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: test-design
 surfaces: [claude-code, library]
+summary: "Dave Farley test design scoring (Farley Index)"
+use_when: "Reviewing or writing tests"
 description: Evaluate test quality using Dave Farley's 8 Properties of Good Tests. Use when reviewing or writing tests to ensure they provide genuine verification.
 ---
 

skills/trainer/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: trainer
 surfaces: [claude-code, library]
+summary: "Two-phase brain curation (score candidates, write past quality gate)"
+use_when: "Periodic brain pruning and curation"
 description: Two-phase brain curation — scan session logs to score candidate learnings (READ), then write the ones that pass the quality gate as generalized knowledge entries (WRITE). Use periodically to keep the brain useful, not noisy.
 ---
 

skills/user-stories/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: user-stories
 surfaces: [claude-code, library]
+summary: "Elephant Carpaccio story slicing"
+use_when: "Breaking down features"
 description: Decompose problems into thin, deliverable user stories using Elephant Carpaccio and INVEST criteria. Use after problem analysis, before planning and implementation.
 ---
 

skills/web-shot/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: web-shot
 surfaces: [claude-code, library]
+summary: "Screenshot a running web UI via a koala k3s Playwright job"
+use_when: "Visual verification of a running UI when no local browser exists"
 description: Screenshot any running web UI by spawning a one-shot Playwright Job on the koala k3s cluster. Auto-detects the calling host's Tailscale name so a dev server on flamingo:8099, iguana:3000 or koala:8181 just works. Use when the user asks for a screenshot, visual verification, "what does the UI look like", or any time chromium / firefox / a browser is requested but none is installed on the host.
 ---
 

tests/check_index_test.sh

@@ -1,70 +0,0 @@
-#!/bin/sh
-# Tests for bin/check-index.
-#
-# The regression these exist for: SKILLS_INDEX.md is maintained by hand, and
-# two skills (`dream`, `experiment-spec`) shipped without a row — the index
-# rows lived on feature branches that were squash-merged after a directory
-# reorg, so the SKILL.md landed and the row did not (#15, #22). Nothing
-# errored; the index just quietly under-reported the library.
-
-set -u
-
-ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
-SUT="$ROOT/bin/check-index"
-
-pass=0
-fail=0
-WORK=${TMPDIR:-/tmp}/check_index_test.$$
-
-if [ ! -f "$SUT" ]; then
-  printf 'FAIL: %s does not exist\n' "$SUT"
-  exit 1
-fi
-
-cleanup() { rm -rf "$WORK"; }
-trap cleanup EXIT INT TERM
-
-# new_fixture <name> — a checkout with skills/alpha and skills/beta.
-new_fixture() {
-  _f="$WORK/$1"
-  mkdir -p "$_f/skills/alpha" "$_f/skills/beta"
-  printf -- '---\nname: alpha\ndescription: a\n---\n' > "$_f/skills/alpha/SKILL.md"
-  printf -- '---\nname: beta\ndescription: b\n---\n' > "$_f/skills/beta/SKILL.md"
-  printf '%s' "$_f"
-}
-
-index() {
-  _dir=$1; shift
-  printf '# Engineering Skills Index\n\n| Skill | Description | Use when |\n|---|---|---|\n' > "$_dir/SKILLS_INDEX.md"
-  for _n in "$@"; do
-    printf '| `%s` | desc | when |\n' "$_n" >> "$_dir/SKILLS_INDEX.md"
-  done
-}
-
-# expect <0|1> <label> <fixture> [grep-for]
-expect() {
-  _want=$1; _label=$2; _fx=$3; _needle=${4:-}
-  _out=$(sh "$SUT" "$_fx" 2>&1); _rc=$?
-  if [ "$_rc" -ne "$_want" ]; then
-    fail=$((fail + 1)); printf '  FAIL %s (want rc=%s got %s)\n%s\n' "$_label" "$_want" "$_rc" "$_out"; return
-  fi
-  if [ -n "$_needle" ] && ! printf '%s' "$_out" | grep -q "$_needle"; then
-    fail=$((fail + 1)); printf '  FAIL %s (rc ok, but report never names %s)\n%s\n' "$_label" "$_needle" "$_out"; return
-  fi
-  pass=$((pass + 1)); printf '  ok   %s\n' "$_label"
-}
-
-fx=$(new_fixture complete); index "$fx" alpha beta
-expect 0 'every skill has a row' "$fx"
-
-fx=$(new_fixture missing); index "$fx" alpha
-expect 1 'a skill with no row is reported' "$fx" beta
-
-fx=$(new_fixture stale); index "$fx" alpha beta gamma
-expect 1 'a row for a skill that does not exist is reported' "$fx" gamma
-
-fx=$(new_fixture noindex)
-expect 1 'a missing index is reported' "$fx" SKILLS_INDEX.md
-
-printf '\ncheck_index: %d passed, %d failed\n' "$pass" "$fail"
-[ "$fail" -eq 0 ]

tests/generate_index_test.sh

@@ -0,0 +1,113 @@
+#!/bin/sh
+# Tests for bin/generate-index.
+#
+# SKILLS_INDEX.md was maintained by hand and drifted: two skills shipped with
+# no row at all (#15), because their rows lived on branches squash-merged after
+# a directory reorg. A gate caught drift after the fact; generating the table
+# from frontmatter removes the class entirely (#29) — the curated summary and
+# trigger now live next to the skill they describe, which is the same argument
+# that made a hand-maintained index the wrong shape.
+
+set -u
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+SUT="$ROOT/bin/generate-index"
+
+pass=0
+fail=0
+WORK=${TMPDIR:-/tmp}/generate_index_test.$$
+
+if [ ! -f "$SUT" ]; then
+  printf 'FAIL: %s does not exist\n' "$SUT"
+  exit 1
+fi
+
+cleanup() { rm -rf "$WORK"; }
+trap cleanup EXIT INT TERM
+
+ok() { pass=$((pass + 1)); printf '  ok   %s\n' "$1"; }
+no() { fail=$((fail + 1)); printf '  FAIL %s\n%s\n' "$1" "${2:-}"; }
+
+# skill <root> <name> <surfaces> [summary] [use_when]
+skill() {
+  mkdir -p "$1/skills/$2"
+  {
+    printf -- '---\nname: %s\nsurfaces: %s\n' "$2" "$3"
+    [ $# -lt 4 ] || printf 'summary: "%s"\n' "$4"
+    [ $# -lt 5 ] || printf 'use_when: "%s"\n' "$5"
+    printf -- 'description: d\n---\n'
+  } > "$1/skills/$2/SKILL.md"
+}
+
+# fixture <name> — a root with an index carrying the generated-table markers.
+fixture() {
+  _f="$WORK/$1"
+  mkdir -p "$_f"
+  cat > "$_f/SKILLS_INDEX.md" <<'IDX'
+# Engineering Skills Index
+
+<!-- BEGIN skills-table -->
+<!-- END skills-table -->
+
+## Wiring
+prose that must survive regeneration
+IDX
+  printf '%s' "$_f"
+}
+
+f=$(fixture basic)
+skill "$f" beta '[claude-code, library]' 'B summary' 'when B'
+skill "$f" alpha '[chat]' 'A summary' 'when A'
+out=$(sh "$SUT" "$f" 2>&1); rc=$?
+if [ "$rc" -ne 0 ]; then
+  no 'generates a table' "$out"
+elif ! grep -q '^| `alpha` | A summary | when A |' "$f/SKILLS_INDEX.md"; then
+  no 'generates a table' "$(cat "$f/SKILLS_INDEX.md")"
+elif ! grep -q 'prose that must survive regeneration' "$f/SKILLS_INDEX.md"; then
+  no 'content outside the markers survives' "$(cat "$f/SKILLS_INDEX.md")"
+elif [ "$(grep -n '`alpha`' "$f/SKILLS_INDEX.md" | cut -d: -f1)" -gt "$(grep -n '`beta`' "$f/SKILLS_INDEX.md" | cut -d: -f1)" ]; then
+  no 'rows are sorted' "$(cat "$f/SKILLS_INDEX.md")"
+else
+  ok 'generates a sorted table and leaves the rest of the file alone'
+fi
+
+# The surfaces a skill ships to are the point of #29, so they are visible.
+grep -q 'chat' "$f/SKILLS_INDEX.md" \
+  && ok 'the row names the surfaces' \
+  || no 'the row names the surfaces' "$(cat "$f/SKILLS_INDEX.md")"
+
+# Idempotent: a second run changes nothing.
+before=$(cat "$f/SKILLS_INDEX.md")
+sh "$SUT" "$f" >/dev/null 2>&1
+[ "$before" = "$(cat "$f/SKILLS_INDEX.md")" ] \
+  && ok 'regeneration is idempotent' \
+  || no 'regeneration is idempotent'
+
+# --check is the CI gate: clean tree passes.
+sh "$SUT" --check "$f" >/dev/null 2>&1 \
+  && ok '--check passes on a generated index' \
+  || no '--check passes on a generated index'
+
+# ...and fails once a skill appears without regenerating.
+skill "$f" gamma '[library]' 'G summary' 'when G'
+if sh "$SUT" --check "$f" >/dev/null 2>&1; then
+  no '--check fails on a stale index'
+else
+  ok '--check fails on a stale index'
+fi
+
+# A skill with no curated summary is an error, not an empty cell: the table
+# cell is what a reader scans, and a blank one is worse than a missing row.
+f=$(fixture nosummary)
+skill "$f" alpha '[library]'
+out=$(sh "$SUT" "$f" 2>&1); rc=$?
+if [ "$rc" -eq 0 ]; then
+  no 'a missing summary is an error' "$out"
+elif ! printf '%s' "$out" | grep -q alpha; then
+  no 'a missing summary is an error' "$out"
+else
+  ok 'a missing summary is an error naming the skill'
+fi
+
+printf '\ngenerate_index: %d passed, %d failed\n' "$pass" "$fail"
+[ "$fail" -eq 0 ]