From 6df2ceabda148526f9fb9e372e4a875d92765f9f Mon Sep 17 00:00:00 2001 From: Stephen Benjamin Date: Wed, 5 Aug 2026 14:02:14 -0400 Subject: [PATCH] Generate plugin README skill lists --- Makefile | 7 ++- plugins/books/README.md | 16 +++++++ plugins/loops/README.md | 4 +- plugins/loops/skills/pr-loop/SKILL.md | 6 +-- plugins/openclaw/README.md | 10 ++-- plugins/reviews/README.md | 6 +++ plugins/rules/README.md | 8 +++- plugins/steering/README.md | 20 ++++---- scripts/generate_plugin_readmes.py | 66 +++++++++++++++++++++++++++ 9 files changed, 123 insertions(+), 20 deletions(-) create mode 100644 scripts/generate_plugin_readmes.py diff --git a/Makefile b/Makefile index 4ec1cc1..32977f1 100644 --- a/Makefile +++ b/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 diff --git a/plugins/books/README.md b/plugins/books/README.md index 6d66164..a8e84ff 100644 --- a/plugins/books/README.md +++ b/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 + + +- [`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. + + ## Skill routing The invocable skills `/books:books-next`, `/books:books-random`, diff --git a/plugins/loops/README.md b/plugins/loops/README.md index a5fe4bf..5f824d1 100644 --- a/plugins/loops/README.md +++ b/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. + +- [`pr-loop`](skills/pr-loop/SKILL.md) — Shepherd a PR: merge base branch, fix CI, address review comments, resolve threads, and monitor until merged. + ## Usage diff --git a/plugins/loops/skills/pr-loop/SKILL.md b/plugins/loops/skills/pr-loop/SKILL.md index d4ed331..145eca8 100644 --- a/plugins/loops/skills/pr-loop/SKILL.md +++ b/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 diff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.md index f2cb841..cd2e850 100644 --- a/plugins/openclaw/README.md +++ b/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. + +- [`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. + ## Notes diff --git a/plugins/reviews/README.md b/plugins/reviews/README.md index 61640dd..e750c08 100644 --- a/plugins/reviews/README.md +++ b/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 + + +- [`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. + diff --git a/plugins/rules/README.md b/plugins/rules/README.md index 0194553..9868c77 100644 --- a/plugins/rules/README.md +++ b/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 + + +- [`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. + diff --git a/plugins/steering/README.md b/plugins/steering/README.md index 9ccec3c..fbb55c8 100644 --- a/plugins/steering/README.md +++ b/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 + + +- [`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. + Inspired by [`bro` from dmmulroy/skills](https://github.com/dmmulroy/skills/blob/main/bro/SKILL.md). diff --git a/scripts/generate_plugin_readmes.py b/scripts/generate_plugin_readmes.py new file mode 100644 index 0000000..d2bb135 --- /dev/null +++ b/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 = "" +END = "" + + +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}")