ABD Skill & Agent Catalogue

Maintain a browsable catalogue of skills under the repo root skills/ and agents under agents/, aligned with the tone of agents/abd-skill-builder/docs/process-outline.md and the compact HTML chrome used under agents/abd-skill-builder/docs/overview/.

When to use this skill

• You added, renamed, or retired a skill or agent and the catalogue is stale.
• You need a stakeholder-facing index of what each skill and agent is for.
• You want both Markdown (diffable, review in Git) and HTML (quick browse).

What it produces

Each catalogue entry includes:

• Package README.md (at skills/<dir>/README.md or agents/<dir>/README.md) — human- or AI-authored catalogue copy. Convention:
  • Optional YAML catalogue_summary: — one line for cards and grids.
  • ## Overview — prose shown as the HTML Description (falls back to SKILL.md / agent entry doc if this section is empty).
    • Skills: problem, approach, main inputs/outputs, when to use (keep it short).
    • Agents: concise digest — what the agent does, why it exists, the main steps (high-level only, not a paste of AGENT.md), and which other agents and skills it orchestrates or depends on (names/paths). Full behaviour stays in the entry file; README is the stakeholder-facing summary.
  • ## How it fits together — narrative plus a single fenced ```ascii block. The generator copies the fence body into the <pre> diagram as-is (no Python “invented” ASCII). Use an assistant: read SKILL.md or AGENT.md, decide what the package does / how / why, then write README. If a README already exists but is insufficient, the assistant overwrites that file after judgement — scaffolding in Python only creates missing files; it never bulk-replaces existing READMEs.
• Summary (cards) — catalogue_summary from README, else first paragraph of ## Overview, else the same heuristic as before from SKILL.md / entry doc.
• Contents (detail page) — still generated by code: linked file tree from disk (<details> / <summary>, file names as links). Known folder blurbs and nested SKILL.md summaries unchanged. Repo links open in a new tab.

Agent instructions

1. Regenerate on command. From the agilebydesign-skills repository root, run:

   python skills/abd-skill-catalog/scripts/generate_abd_catalog.py
   

   First-time or new packages — create stub READMEs only where the file is missing, then regenerate:

   python skills/abd-skill-catalog/scripts/generate_abd_catalog.py --scaffold-readmes
   

   The script never overwrites an existing README.md. If a README is thin, wrong, or still full of TODOs, you (the assistant or maintainer) read SKILL.md / the agent entry doc, decide what is insufficient, and replace the README content yourself (edit in the IDE or rewrite the file in one pass). That is not a generator flag — it is judgement + prose.

   Options:

   • --repo-root <path> — defaults to the parent of the repo skills/ directory (detected from this script location).
   • --output-dir <path> — overrides <repo-root>/catalog if you need a different folder.
   • --scaffold-readmes — write README.md from templates only where the file does not exist, then run generation.

2. Discovery rules.

   • Skills: every immediate child of skills/ that contains SKILL.md. (Skips plain files and folders without SKILL.md.)
   • Agents: every immediate child of agents/ that contains one of AGENT.md, AGENTS.md, or SKILL.md (first match in that order).

3. Extraction (skills). Same heuristics as skill-garden-catalogue for name and fallbacks when README.md is absent or sections are empty:

   • Name — YAML name in SKILL.md, else directory name.
   • Summary — README catalogue_summary / ## Overview when present; else YAML description, else ## Purpose, else opening text after the H1.

4. Extraction (agents).

   • Name — YAML name if present, else markdown H1 heading text.
   • Summary — README first, else same heuristics as before from the entry document.

5. Catalogue intros (review with an AI or editor). Short HTML above the grids lives in skills/abd-skill-catalog/templates/intros/. Keep copy user-facing (how to browse, link to outline) — do not explain how the catalogue is built (README conventions, generator, scaffolding); that belongs in this SKILL.md only.

   • catalog-hub-intro.html — hub; may use {{OUTLINE_HREF}} for outline.
   • catalog-skills-intro.html — line above the skills grid.
   • catalog-agents-intro.html — line above the agents grid.

   The script uses minimal built-in HTML if a fragment is missing.

6. README templates. Stubs are produced from templates/catalog-readme-skill.md and templates/catalog-readme-agent.md. Adjust those files if the default scaffold text should change for new packages.

7. Templates (layout). HTML shells and CSS live under skills/abd-skill-catalog/templates/ (excluding intros/, which are prose fragments) and are merged with token replacement. Edit those files to change branding or layout without touching Python.

8. Idempotent. Running the script twice with the same tree overwrites the same outputs deterministically.