generate-docs.py had a longstanding bug: the rendering loop only iterated
top-level skills and only rendered their direct children. Sub-skills whose
parent is a plugin folder (not a top-level skill at <domain>/skills/<name>/)
were silently dropped.
Affected plugins (standalone-only, no bundled mirror at <domain>/skills/):
- executive-mentor (1 index + 5 sub-skills)
- agenthub (1 index + 7 sub-skills)
- autoresearch-agent (1 index + 5 sub-skills)
- playwright-pro (1 index + 9 sub-skills)
- self-improving-agent (1 index + 5 sub-skills)
- c-level-agents (1 index + 17 sub-skills — the new /cs:* commands)
- llm-wiki (1 index + sub-skills)
- behuman, code-tour, demo-video, helm-chart-builder, karpathy-coder,
llm-cost-optimizer, prompt-governance, statistical-analyst, terraform-patterns,
data-quality-auditor, docker-development (single-skill plugins)
Total: 79 sub-skills + 12 plugin-index skills = 91 pages were being dropped.
(Some plugins like behuman are single-skill so only their index is dropped.)
The bug: rendering loop at line 414 only handled `for skill in top_level`,
then for each top-level found `children = [s for s in sub_skills if
s["parent"] == skill["name"]]`. Plugins where the SKILL.md lives only at
<plugin>/skills/<plugin>/SKILL.md don't appear in top_level (their detection
puts them in sub_skills with parent=themselves), so their children were
orphaned.
The fix: after the existing top-level loop, render orphan sub-skills grouped
by their plugin parent. Index sub-skill (named same as parent) renders as
<parent>.md; other children render as <parent>-<child>.md. This matches the
URL convention already in use (e.g., executive-mentor-challenge.md), so
existing SEO equity is preserved.
Result: skill pages generated 193 → 272 (+79 recovered). Total docs pages
280 → 359. mkdocs build succeeds.
Verified:
- All 12 previously-dropped plugins render their index page
- All 79 previously-dropped sub-skills render their detail pages
- URL convention preserved (executive-mentor-challenge.md, agenthub-board.md,
playwright-pro-coverage.md, etc.)
- karpathy diff_surgeon: 0 findings
After dev → main release: GitHub Pages redeploys with the recovered 79 pages.
The docs site finally has 1:1 correspondence between SKILL.md files in the
repo and pages on the site.
https://claude.ai/code/session_012WtZMm5NJHqkYoRqA9fHMN
