Reference Skills page — rot → generated (#2120)

The rot (verified on main @ 8.12.4)

Claimed in title

Slugs actually listed

160

…that are real refs

Real reference skills

The page claimed "61", its tables listed 160 distinct slugs (more than the 111 skills that even exist), and only 16 matched a real user-invocable: false skill — the rest were renamed or removed (e.g. api-design-framework → the real api-design). A number-swap would have papered over it; this regenerates the page from source instead.

Before → After

BEFORE hand-authored, rotted

title: "61 Skills That Power Agents"

slugs: 160 (144 phantom)

grouping: 14 hand-curated tables, stale

maintenance: manual → drifts every release

AFTER generated from frontmatter

title: "Reference Skills" (no count to rot)

slugs: 80 (0 phantom)

grouping: 17 agent sections + Cross-Cutting (auto)

maintenance: zero — rebuilds from agent: field

How it works

scripts/_build-docs-generate.py  (+ build-docs.sh wiring)

+ def generate_reference_skills(skills_src, out_file):
+     # every SKILL.md with user-invocable: false, grouped by `agent:`
+     for skill_dir in sorted(skills_dir):
+         if meta.get("user-invocable"): continue   # command skill, skip
+         agent = meta.get("agent")                  # group key
+         (by_agent[agent] or cross_cutting).append((slug, desc))
+     count = 80   # computed, never hardcoded

Generator output: "80 reference skills (17 agents + 31 cross-cutting)"

Membership comes entirely from frontmatter, so a new reference skill auto-appears under its agent and the count auto-updates. A small agent→title map only prettifies headings (unknown agents fall back to title_case).

Sections generated

Accessibility · Backend & Distributed Systems · CI/CD · Code Quality
Data Pipelines & RAG · Database · Debugging · API Emulation
Frontend Performance · Frontend & UI · LLM, RAG & AI · Product & Strategy
Python Performance · Security · Testing · Web Research · LangGraph & Workflows
+ Cross-Cutting Skills (31)