abd-skill-catalog

name	abd-skill-catalog
catalog_garden_tier	foundational
catalogue_one_liner	Regenerate the browsable AI Garden (skills + agents HTML + outline.md) from repo packages.
description	Scan agilebydesign-skills (`skills/` and `agents/`), maintain each package’s root `README.md` for card and detail copy (overview + ASCII), then regenerate `catalog/` HTML and `outline.md` from those files plus a generated file tree.
license	MIT
metadata	{"author":"agilebydesign","version":"1.0.0"}

The ABD AI Garden (abd-skill-catalog)

Maintain the browsable AI Garden: 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 AI Garden 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

Artifact	Format	Location (default)
Outline	Markdown	catalog/outline.md (repository root)
Site hub	HTML	catalog/index.html — one page: Agile Garden prelude (mission + practice/foundational skill lists + agents box, generated from catalog_garden_* in SKILL.md / AGENT.md), then collapsible About, Skills, Agents; hub intro links jump to #catalog-skills / #catalog-agents
Skills grid	HTML	catalog/skills.html (standalone grid; nav from detail pages)
Agents grid	HTML	catalog/agents.html (standalone grid; nav from detail pages)
Hub / grid intros	HTML fragments	skills/skill-builder/abd-skill-catalog/templates/intros/*.html (short lines above grids; optional polish)
Skill detail pages	HTML	catalog/skill/<dir>.html (one per skill; cards link here)
Agent detail pages	HTML	catalog/agent/<dir>.html (one per agent; cards link here)

Skill detail pages include an Install with npx block: a single fenced-style command npx skills add agilebydesign/agilebydesign-skills@<frontmatter name> -y, matching the skill id from npx skills add https://github.com/agilebydesign/agilebydesign-skills -l. Agent pages omit that block (agents are not separate npx skills packages in this repo).

Each listed package includes:

• Package README.md (at skills/<dir>/README.md or agents/<dir>/README.md) — human- or AI-authored card and detail 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/skill-builder/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/skill-builder/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 agilebydesign-skills root (folder that contains both skills/ and agents/, detected from this script).
   • --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.
   • --omit-garden-families <ids> — comma-separated column family ids to hide from the Agile Garden prelude only (e.g. utilities); skills stay in the flat grids and outline. Combines with _CATALOG_GARDEN_PRELUDE_OMIT_FAMILIES in generate_abd_catalog.py.

2. Discovery rules.

   • Skills: every immediate child of repo skills/ that contains SKILL.md, plus packages under agents/<agent>/skills/ that contain SKILL.md and YAML catalog_garden_tier: practice or foundational (so agent-local pipeline skills without that field stay off the grid).
   • Agents: every immediate child of agents/ that contains one of AGENT.md, AGENTS.md, or SKILL.md (first match in that order).
   • AI Garden listing — omit a package from hub, outline, grids, and detail pages when catalog_ready is false (no / 0 / draft / not-ready in YAML), or top-level tags includes not-ready, wip, draft, or hidden, or skill-config.json sets "catalog_ready": false (agents and skills that ship that file). Default: listed.

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 (cards + garden rows) — optional YAML catalogue_one_liner on the entry doc wins when set (short card line; keeps long description for discovery/npx). Else README catalogue_summary / ## Overview; else YAML description, ## Purpose, or opening text after H1.
   • Tags — optional top-level YAML tags as tag1, tag2, flow tags: [tag1, tag2], or a block list under tags: (one - item per line). Order in the file is preserved for tooling; nothing re-sorts tag lists.
   • Agile Garden lists — optional YAML catalog_garden_tier: practice or foundational to include the skill in the generated prelude on catalog/index.html (and the synced fragment under abd-works). Optional catalog_garden_order: <int> sorts within that column (default 999).

4. Extraction (agents).

   • Name (cards + detail H1) — package directory name (kebab-case), not the markdown title.
   • Summary — same as skills: catalogue_one_liner on the entry doc wins when set; else README; then description / ## Purpose / …
   • Agile Garden agents box — agents are listed by default; set catalog_garden: false in front matter to hide. Optional catalog_garden_order: <int> for sort order.

5. Hub and grid intros (review with an AI or editor). Short HTML above the grids lives in skills/skill-builder/abd-skill-catalog/templates/intros/. Keep copy user-facing (how to browse, link to outline) — do not explain how the AI Garden 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/skill-builder/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.