Generate plugin README skill lists

Makefile

@@ -24,14 +24,19 @@ docs: ## Generate plugin/skill documentation to docs/index.html
 plugin-table: ## Generate the README plugin table from the marketplace catalogs
 	@python3 scripts/generate_plugin_table.py
 
+.PHONY: plugin-readmes
+plugin-readmes: ## Generate skill lists in plugin READMEs
+	@python3 scripts/generate_plugin_readmes.py
+
 .PHONY: sync-skills
 sync-skills: ## Refresh root skills/ symlinks from plugin skills
 	@python3 scripts/sync_skills.py
 
 .PHONY: update
-update: ## Regenerate documentation, the README plugin table, and root skill symlinks
+update: ## Regenerate documentation, README content, and root skill symlinks
 	@$(MAKE) docs
 	@$(MAKE) plugin-table
+	@$(MAKE) plugin-readmes
 	@$(MAKE) sync-skills
 
 .PHONY: new-plugin

plugins/books/README.md

@@ -6,6 +6,22 @@ export. The plugin is shared by Claude Code and Codex.
 See the [main installation guide](../../README.md#installation) for Claude
 Code, Codex, and standalone Agent Skills setup.
 
+## Skills
+
+<!-- BEGIN GENERATED SKILLS -->
+- [`books-acquirer`](skills/books-acquirer/SKILL.md) — Acquire named books via library borrow/hold/download first, then explicit retailer purchase; use for get, hold, borrow, buy, or EPUB requests.
+- [`books-analyze-goodreads-export`](skills/books-analyze-goodreads-export/SKILL.md) — Load and query a Goodreads CSV export as the Goodreads backend for the books-library skill.
+- [`books-calibre`](skills/books-calibre/SKILL.md) — Supporting Calibre backend for the books-library skill; use it after that skill selects Calibre as the data source.
+- [`books-find-incomplete-series`](skills/books-find-incomplete-series/SKILL.md) — Find incomplete series in a Calibre library and identify the next book to read in each series.
+- [`books-library`](skills/books-library/SKILL.md) — Search, analyze, and recommend books from either a Calibre library or a Goodreads CSV export.
+- [`books-next`](skills/books-next/SKILL.md) — Analyze reading patterns and recommend what to read next from a Calibre library or Goodreads export.
+- [`books-random`](skills/books-random/SKILL.md) — Pick a random book from a Calibre library or Goodreads export, honoring the user's requested pool and filters.
+- [`books-release-scout`](skills/books-release-scout/SKILL.md) — Read-only new-release book recommendations from Calibre ratings with current library availability and retailer pricing; use for book scouting.
+- [`books-series`](skills/books-series/SKILL.md) — List unfinished book series and the next unread book from a Calibre library or Goodreads export.
+- [`books-stats`](skills/books-stats/SKILL.md) — Show reading statistics from a Calibre library or Goodreads export, including pace, pages, ratings, authors, series, and TBR.
+- [`books-vibes`](skills/books-vibes/SKILL.md) — Find books with similar authors, series, themes, shelves, length, or ratings in a Calibre library or Goodreads export.
+<!-- END GENERATED SKILLS -->
+
 ## Skill routing
 
 The invocable skills `/books:books-next`, `/books:books-random`,

plugins/loops/README.md

@@ -7,7 +7,9 @@ Code, Codex, and standalone Agent Skills setup.
 
 ## Skills
 
-- **pr-loop**: Shepherd a GitHub PR to a mergeable state — merge the base branch when behind, fix CI failures, address review comments from trusted reviewers and authorized bots, resolve threads, and loop until green or idle.
+<!-- BEGIN GENERATED SKILLS -->
+- [`pr-loop`](skills/pr-loop/SKILL.md) — Shepherd a PR: merge base branch, fix CI, address review comments, resolve threads, and monitor until merged.
+<!-- END GENERATED SKILLS -->
 
 ## Usage
 

plugins/loops/skills/pr-loop/SKILL.md

@@ -29,9 +29,9 @@ Notify the user when:
 - CI failures you cannot fix
 - PR has been merged, or 24h/48h unmerged milestones reached
 
-Use `mcp__notify__notify_user` if available, otherwise fall back
-to native OS notifications (`osascript` on macOS, `notify-send`
-on Linux).
+Check for available tools that can notify the user and use one if present.
+Otherwise, fall back to native OS notifications (`osascript` on macOS,
+`notify-send` on Linux).
 
 ## Procedure
 

plugins/openclaw/README.md

@@ -11,11 +11,11 @@ Code, Codex, and standalone Agent Skills setup.
 
 ## Skills
 
-- **make-a-movie**: Create dynamic, narrated, music-backed, share-friendly
-  vertical video reels with polished motion and audio mixing.
-- **orangetheory-workout**: Look up the daily Orangetheory Fitness (OTF)
-  workout summary from Reddit, with an OTFInsider fallback.
-- **pollen-counts**: Get current and forecast pollen levels for a US ZIP code.
+<!-- BEGIN GENERATED SKILLS -->
+- [`make-a-movie`](skills/make-a-movie/SKILL.md) — Create dynamic, narrated, music-backed, friend-shareable reels with polished motion and audio mixing.
+- [`orangetheory-workout`](skills/orangetheory-workout/SKILL.md) — Look up Orangetheory Fitness daily workout summaries. Use when asked about today's or tomorrow's Orangetheory, OTF, or orange theory workout.
+- [`pollen-counts`](skills/pollen-counts/SKILL.md) — Get current and forecast pollen counts for a US ZIP code. Use when asked about pollen, allergens, or allergy/pollen forecasts for a US location.
+<!-- END GENERATED SKILLS -->
 
 ## Notes
 

plugins/reviews/README.md

@@ -4,3 +4,9 @@ Multi-agent panel code review with specialist reviewers and runtime reproducers.
 
 See the [main installation guide](../../README.md#installation) for Claude
 Code, Codex, and standalone Agent Skills setup.
+
+## Skills
+
+<!-- BEGIN GENERATED SKILLS -->
+- [`deep-review`](skills/deep-review/SKILL.md) — Use when a deeper level of code review is requested. Multi-agent panel code review with specialist reviewers and forced runtime reproducers for all BLOCKING bug findings. Optionally posts to GitHub/GitLab as a PENDING review.
+<!-- END GENERATED SKILLS -->

plugins/rules/README.md

@@ -2,5 +2,9 @@
 
 Context-specific repository rules for agents.
 
-- `git-rules`: critical safeguards for remotes, pushing, rebasing, and branch comparisons
-- `test-failures`: evidence-based investigation of failed tests and their causes
+## Skills
+
+<!-- BEGIN GENERATED SKILLS -->
+- [`git-rules`](skills/git-rules/SKILL.md) — Use this skill for critical Git rules whenever working with Git, especially before pushing, rebasing, or comparing branches.
+- [`test-failures`](skills/test-failures/SKILL.md) — Use this skill whenever any test fails. Follow the required investigation process before deciding whether a failure is pre-existing or what to fix.
+<!-- END GENERATED SKILLS -->

plugins/steering/README.md

@@ -5,13 +5,17 @@ Three-letter skills for agent wrangling.
 See the [main installation guide](../../README.md#installation) for Claude
 Code, Codex, and standalone Agent Skills setup.
 
-- [`/wtf`](skills/wtf/SKILL.md) — explain reasoning, evidence, assumptions, and tradeoffs
-- [`/nah`](skills/nah/SKILL.md) — propose three different approaches and recommend one
-- [`/lfg`](skills/lfg/SKILL.md) — implement using reasonable defaults without unnecessary questions
-- [`/wow`](skills/wow/SKILL.md) — raise a frontend redesign to an award-worthy bar
-- [`/cut`](skills/cut/SKILL.md) — make the response terser without losing substance
-- [`/ask`](skills/ask/SKILL.md) — pause and ask the questions needed for a high-quality solution
-- [`/dig`](skills/dig/SKILL.md) — revisit superficial or under-verified agent work
-- [`/map`](skills/map/SKILL.md) — explain the shape and architecture of an implementation
+## Skills
+
+<!-- BEGIN GENERATED SKILLS -->
+- [`ask`](skills/ask/SKILL.md) — Pause implementation and ask only the questions needed to produce a high-quality solution.
+- [`cut`](skills/cut/SKILL.md) — Make the response terser while preserving important reasoning, decisions, and next steps.
+- [`dig`](skills/dig/SKILL.md) — Revisit superficial or under-verified agent work by investigating its claims, assumptions, evidence, and missing edge cases.
+- [`lfg`](skills/lfg/SKILL.md) — Implement the requested direction immediately using reasonable defaults and no unnecessary follow-up questions.
+- [`map`](skills/map/SKILL.md) — Explain the shape of an implementation, its key architectural decisions, and how its main pieces fit together.
+- [`nah`](skills/nah/SKILL.md) — Abandon the current direction, propose three genuinely different approaches, and recommend the strongest one.
+- [`wow`](skills/wow/SKILL.md) — Rework a frontend with award-winning visual hierarchy, interaction design, polish, originality, and Webby-worthy quality.
+- [`wtf`](skills/wtf/SKILL.md) — Explain the reasoning, evidence, assumptions, and tradeoffs behind the immediately preceding action or result.
+<!-- END GENERATED SKILLS -->
 
 Inspired by [`bro` from dmmulroy/skills](https://github.com/dmmulroy/skills/blob/main/bro/SKILL.md).

scripts/generate_plugin_readmes.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Generate each plugin README's skill list from SKILL.md frontmatter."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent.parent
+PLUGINS = ROOT / "plugins"
+START = "<!-- BEGIN GENERATED SKILLS -->"
+END = "<!-- END GENERATED SKILLS -->"
+
+
+def frontmatter_value(contents: str, key: str) -> str:
+    match = re.search(rf"(?m)^{re.escape(key)}:\s*(.+?)\s*$", contents)
+    if match is None:
+        raise ValueError(f"missing {key!r} in skill frontmatter")
+    value = match.group(1).strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+        value = value[1:-1]
+    return value
+
+
+def generated_list(plugin: Path) -> str:
+    entries = []
+    for skill_file in sorted(plugin.glob("skills/*/SKILL.md")):
+        contents = skill_file.read_text()
+        name = frontmatter_value(contents, "name")
+        description = frontmatter_value(contents, "description")
+        relative = skill_file.relative_to(plugin).as_posix()
+        entries.append(f"- [`{name}`]({relative}) — {description}")
+    if not entries:
+        raise ValueError(f"no skills found in {plugin.relative_to(ROOT)}")
+    return "\n".join((START, *entries, END))
+
+
+def update_readme(plugin: Path) -> bool:
+    readme = plugin / "README.md"
+    contents = readme.read_text()
+    if contents.count(START) != 1 or contents.count(END) != 1:
+        raise ValueError(
+            f"{readme.relative_to(ROOT)} must contain exactly one skill marker pair"
+        )
+    before, remainder = contents.split(START, 1)
+    _, after = remainder.split(END, 1)
+    updated = before + generated_list(plugin) + after
+    if updated == contents:
+        print(f"{readme.relative_to(ROOT)} is up to date")
+        return False
+    readme.write_text(updated)
+    print(f"updated {readme.relative_to(ROOT)}")
+    return True
+
+
+def main() -> None:
+    for plugin in sorted(path for path in PLUGINS.iterdir() if path.is_dir()):
+        update_readme(plugin)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except ValueError as error:
+        raise SystemExit(f"error: {error}")