Auto-Generating an Index of Your Claude Code Custom Agents from Their Frontmatter

This is a continuation of my "Claude Code environment" series. In the previous post, Automatically thinning conversation logs to prevent bloat , I introduced the basic pattern for scheduled launchd jobs. This time I'm using that same mechanism to automatically maintain a list of the custom agents in ~/.claude/agents/ . Dropping a single .md file into ~/.claude/agents/ adds a custom agent, but before long you lose track of how many you have, what model each one uses, and which tools each is allowed to touch. That's exactly what happened to me with the 27 agents I now have. I tried writing an INDEX.md by hand to manage them, and of course within a few days it had drifted from reality. The problem: the index rots Manually updating INDEX.md every time you add a custom agent is not sustainable. You forget you added one and leave it out You change a model later and never reflect it in INDEX.md You typo a name or description and never notice I concluded there was no sustainable way to manage this other than "generate it automatically," so I wrote agents-index.sh . The output: a real INDEX.md Here's how the top of my current ~/.claude/agents/INDEX.md looks. <!-- AUTO-GENERATED by ~/.claude/scripts/agents-index.sh — DO NOT EDIT MANUALLY --> # Agents Index (27 agents · 2026-07-28 02:02) | Name | Model | Description | Tools | |------|-------|-------------|-------| | `architect` ( [ architect.md ]( ./architect.md ) ) | opus | Software architecture specialist ... | ["Read", "Grep", "Glob"] | | `build-error-resolver` ( [ build-error-resolver.md ]( ./build-error-resolver.md ) ) | sonnet | Build and TypeScript error resolution specialist ... | ["Read", "Write", "Edit", "Bash", "Grep", "Glob"] | | `doc-updater` ( [ doc-updater.md ]( ./doc-updater.md ) ) | haiku | Documentation and codemap specialist ... | ["Read", "Edit", "Bash", "Grep", "Glob"] | Four columns: Name, Model, Description, and Tools. You can see at a glance how the models break down across opus / sonnet / haiku , and i