増えたカスタムエージェントを frontmatter から自動で一覧化する ― 週1回 launchd で INDEX.md を更新する

前回、会話ログを長期記憶に変える話を書きました。今回は同じ「積み上がったものを可視化する」系のミニ実装で、~/.claude/agents/ に増えたカスタムエージェント定義を、frontmatterから自動で一覧化する話です。

困りごと：何がいて、何ができるか分からない

~/.claude/agents/*.md にカスタムエージェント定義を書き足していくと、そのうち「このエージェント、modelは何だっけ」「tools何を許可してたっけ」が自分でも分からなくなります。ファイルを開いてfrontmatterを読めば分かりますが、数が増えるとそれ自体が面倒になる。

そこで agents-index.sh という80行弱のスクリプトを書きました。agents/*.md のfrontmatterを集約して INDEX.md に一覧を吐くだけの、地味なツールです。

実装：PyYAML非依存の簡易パーサ

本体は python3 のヒアドキュメントです。YAMLパーサに依存すると環境差分で壊れるので、key: value の1階層だけを読む簡易パーサにしています。

def load_frontmatter(path: pathlib.Path):
    text = path.read_text(encoding="utf-8", errors="replace")
    m = re.match(r"^---\n(.*?)\n---\n", text, flags=re.DOTALL)
    if not m:
        return None, "missing frontmatter"
    body = m.group(1)
    out = {}
    # YAML 風だが PyYAML 依存避けるため簡易パーサ（1階層 key: value のみ・list はリテラル文字列で扱う）
    for line in body.split("\n"):
        if not line.strip() or line.startswith("#"):
            continue
        if ":" not in line:
            continue
        k, _, v = line.partition(":")
        k = k.strip()
        v = v.strip()
        if (v.startswith('"') and v.endswith('"')) or (v.startswith("'") and v.endswith("'")):
            v = v[1:-1]
        out[k] = v
    return out, None

tools: ["Read", "Grep", "Glob"] のようなリストも、ネストせず1行で書かれている前提なので、パースせず文字列のまま保持して表に出力するだけにしています。実際のagent定義もこの形です。

---
name: architect
description: Software architecture specialist for system design, scalability, and technical decision-making. Use PROACTIVELY when planning new features, refactoring large systems, or making architectural decisions.
tools: ["Read", "Grep", "Glob"]
model: opus
---

集めたレコードから Markdown テーブルを組み、name / description が欠けているファイルは warnings に積んで末尾に警告セクションとして出力します。

if not name:
    warnings.append(f"{p.name}: missing 'name'")
if not desc:
    warnings.append(f"{p.name}: missing 'description'")

--json オプションを付けると .index.json にも同じ内容を書き出します。他のスクリプトから再利用する時用の窓口です。

実際の出力

いま ~/.claude/agents/ は7個のエージェント定義（+ INDEX.md 自身）があり、生成される INDEX.md はこうなります。

# Agents Index (7 agents · 2026-08-04 23:00)

| Name | Model | Description | Tools |
|------|-------|-------------|-------|
| `architect` ([architect.md](./architect.md)) | opus | Software architecture specialist for system design... | ["Read", "Grep", "Glob"] |
| `code-reviewer` ([code-reviewer.md](./code-reviewer.md)) | sonnet | Expert code review specialist. Proactively reviews code... | ["Read", "Grep", "Glob", "Bash"] |

冒頭に DO NOT EDIT MANUALLY を入れているのは、手で直接編集されて次回実行時に上書き消失する事故を防ぐためです。生成物は生成元（agents/*.md）を直すのが唯一の正しい直し方、という前提を書いておく。

launchd：日曜6:30に起動

com.shun.agents-index.plist はStartCalendarIntervalで日曜朝に固定しています。

<key>StartCalendarInterval</key>
<dict>
    <key>Hour</key>
    <integer>6</integer>
    <key>Minute</key>
    <integer>30</integer>
    <key>Weekday</key>
    <integer>0</integer>
</dict>

ProgramArguments は --json 付きでスクリプトを呼び、標準出力をログに追記するだけの1行コマンドです。

<key>ProgramArguments</key>
<array>
    <string>/bin/zsh</string>
    <string>-c</string>
    <string>~/.claude/scripts/agents-index.sh --json &gt;&gt; ~/.claude/logs/agents-index.log 2&gt;&amp;1 # weekly agents index</string>
</array>

LowPriorityIO と Nice 10 を付けて、他の作業を邪魔しない優先度に落としています。週次の棚卸しなので、即時性より「他の処理を邪魔しない」が優先です。

PATH を EnvironmentVariables で明示しているのがポイントです。launchdは最小限のPATHしか渡さないので、nvm 配下のnodeやhomebrewのbinを素の状態では見つけられません。ここでハードコードしないと、スクリプト自体は正しくてもジョブがサイレントに失敗します。

実測：ログが記録していた「見えていなかった増減」

agents-index.log は毎回追記なので、そのまま実行数の推移が残っていました。

[2026-06-14 06:38] agents=146 warnings=0
[2026-06-21 06:30] agents=146 warnings=0
[2026-06-28 06:30] agents=146 warnings=0
[2026-07-02 18:10] agents=57  warnings=0
[2026-07-05 06:30] agents=47  warnings=0
[2026-07-12 06:30] agents=47  warnings=0
[2026-07-19 06:30] agents=47  warnings=0
[2026-07-26 06:30] agents=37  warnings=0
[2026-07-28 02:02] agents=27  warnings=0
[2026-08-02 06:30] agents=17  warnings=0

直近では7個まで減っています。ピークの146個から7個へ、約95%減です。この仕組みを入れる前は、この推移を誰も見ていませんでした。定義が増えているのか減っているのかすら分からないまま、ただagents/ディレクトリが太っていくのを放置していたということです。

INDEX.mdを毎週見るようになって、はじめて「重複したreviewer系エージェントが多い」「プラグイン提供のエージェントと役割が被っている」に気づき、手動で整理を進めました。可視化した時点ですでに片付けの意思決定が始まるというのは、こういう地味なツールでも変わりません。

warnings=0 が続いているのも実は地味に効いていて、frontmatter記入漏れが7〜146個のどのタイミングでも一度も出ていません。これは警告付きのINDEX生成が抑止力になったというより、そもそも name と description を書かないと動かないagent定義フォーマット自体の効果が大きいです。

踏んだ落とし穴

• YAMLパーサに頼るとリスト値やネストで環境差分が出る → 1階層 key: value だけを読む自作パーサに割り切る
• launchdの最小PATHでpython3/nodeが見つからない可能性 → EnvironmentVariables にPATHをフルで書く
• 生成物を手で編集される事故 → ヘッダに DO NOT EDIT MANUALLY を明記し、直す場所は生成元だと分からせる
• ログを見なければ増減は誰も気づかない → >> log 2>&1 の追記だけで、後から推移を読める資産になる

まとめ

• agents/*.md のfrontmatterをPyYAML非依存の簡易パーサで読み、INDEX.md と .index.json を生成
• 欠落フィールド（name / description）は警告として出力するだけで、実行は止めない
• launchdは日曜6:30・LowPriorityIO・Nice 10で他作業を邪魔しない週次バッチにする
• 追記式ログが結果的に推移の記録になり、146個→7個・約95%減という「見えていなかった増減」を可視化できた

次回は、この手の週次バッチ・自己増殖スキル・自律ループが増えすぎてlaunchd自体の管理が煩雑になった話を書く予定です。

---

Lily（@bokuwalily）― 個人開発者。Claude Code で自動化基盤を組みながら、iOSアプリやWebサービスを量産しています

• AIで「寝てても回る仕組み」を作って月120万にした話は noteの有料記事 に💰
• OSS: github.com/bokuwalily 🐙
• 最新情報・お問い合わせは X @bokuwalily へ🌍

皆さんの ❤️ やシェアが励みになります！