mjcreativelab Agents MD Improver（エージェント指示ファイルの監査・改善）
リポジトリ内のエージェント指示ファイル（CLAUDE.md / AGENTS.md / GEMINI.md 等）を監査・評価・改善し、コーディングエージェントが最適なプロジェクトコンテキストを持てる状態を保つ。
このスキルは指示ファイルへ書き込みうる。 ただし必ず品質レポートを提示し、ユーザー承認を得てから的を絞った更新のみを適用する。
対象ファイル
| 種別 | 場所 | 用途 |
|---|---|---|
| プロジェクトルート | ./CLAUDE.md / ./AGENTS.md / ./GEMINI.md |
プロジェクトの一次コンテキスト（git 管理・チーム共有） |
| ローカル上書き | ./.claude.local.md |
個人・ローカル限定設定（gitignore 対象。Claude Code 固有） |
| パッケージ単位 | ./packages/*/CLAUDE.md 等 |
monorepo のモジュール単位コンテキスト |
| サブディレクトリ | 任意のネスト位置 | 機能・ドメイン固有コンテキスト |
| グローバル | ~/.claude/CLAUDE.md（Claude Code）/ ~/.codex/AGENTS.md（Codex）/ ~/.gemini/GEMINI.md（Gemini CLI） |
ユーザー全体のデフォルト。明示的に依頼されたときのみ対象にする |
多くのエージェントは親ディレクトリの指示ファイルを自動発見するため、monorepo 構成でもネスト配置が機能する。
Phase 1: Discovery（走査）
リポジトリ内の指示ファイルをすべて洗い出す:
find . \( -name "CLAUDE.md" -o -name "AGENTS.md" -o -name "GEMINI.md" -o -name ".claude.local.md" \) -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null | head -50
symlink の扱い（重要）:
- 各ファイルが symlink かを確認する（
ls -l <path>）。AGENTS.md → CLAUDE.mdのような symlink は実体と合わせて 1 エンティティとして扱い、評価・編集は実体側に対して行う（二重カウント・二重編集しない） - 同名役割のファイルが別実体として複数存在する場合（例: CLAUDE.md と AGENTS.md が独立ファイル）、内容の乖離（drift）を確認し、乖離があれば問題として報告する
Phase 2: 品質評価
各ファイルを品質基準に照らして評価する。詳細ルーブリックは references/quality-criteria.md を参照。
クイックチェックリスト:
| 基準 | 重み | 確認内容 |
|---|---|---|
| コマンド・ワークフローの文書化 | 高 | build / test / deploy コマンドがあるか |
| アーキテクチャの明瞭さ | 高 | コードベース構造をエージェントが理解できるか |
| 非自明なパターン | 中 | 落とし穴・癖が記録されているか |
| 簡潔さ | 中 | 冗長な説明・自明な情報がないか |
| 鮮度 | 高 | 現在のコードベースの状態を反映しているか |
| 実行可能性 | 高 | 指示が曖昧でなく実行可能か |
品質スコア:
- A (90-100): 網羅的・最新・実行可能
- B (70-89): 良好、軽微なギャップあり
- C (50-69): 基本情報のみ、主要セクション欠落
- D (30-49): 希薄または陳腐化
- F (0-29): 欠落または深刻に陳腐化
Phase 3: 品質レポート出力
更新前に必ず品質レポートを出力する。
フォーマット:
## エージェント指示ファイル品質レポート
### サマリ
- 検出ファイル数: X（symlink 統合後）
- 平均スコア: X/100
- 更新が必要なファイル: X
### ファイル別評価
#### 1. ./CLAUDE.md（プロジェクトルート。AGENTS.md は symlink）
**スコア: XX/100（グレード: X）**
| 基準 | スコア | 備考 |
|------|-------|------|
| コマンド・ワークフロー | X/20 | ... |
| アーキテクチャの明瞭さ | X/20 | ... |
| 非自明なパターン | X/15 | ... |
| 簡潔さ | X/15 | ... |
| 鮮度 | X/15 | ... |
| 実行可能性 | X/15 | ... |
**問題点:**
- [具体的な問題を列挙]
**推奨追記:**
- [追加すべき内容を列挙]
Phase 4: 的を絞った更新提案
品質レポート出力後、更新前にユーザーへ確認を取る。詳細は references/update-guidelines.md を参照。
更新ガイドライン（重要):
- 的を絞った追記のみ提案する — 分析中に発見したコマンド・ワークフロー、コードから読み取った落とし穴・非自明パターン、不明瞭だったパッケージ関係、機能するテストアプローチ、設定の癖
- 最小限に保つ — コードから自明な情報の再掲、一般論のベストプラクティス、再発しない一回限りの修正、一行で済む内容の冗長説明は避ける
- diff を見せる — 変更ごとに、対象ファイル・追記内容（diff または引用ブロック）・将来セッションに役立つ理由を示す
diff フォーマット:
### 更新: ./CLAUDE.md
**理由:** ビルドコマンドが未記載で、プロジェクトの起動方法が分からなかったため。
```diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev # 開発サーバー起動（port 3000）
+ ```
## Phase 5: 承認後の適用
ユーザー承認後、Edit ツールで変更を適用する。既存の構成・スタイルを保持する。symlink の場合は実体ファイルを編集する。
## テンプレート
プロジェクト種別ごとのテンプレートは [references/templates.md](references/templates.md) を参照。
## よくある問題（フラグを立てる対象）
1. **陳腐化したコマンド**: もう動かないビルドコマンド
2. **依存の欠落**: 必要なツールが未記載
3. **古いアーキテクチャ**: 変更済みのファイル構造
4. **環境セットアップの欠落**: 必要な環境変数・設定
5. **壊れたテストコマンド**: 変更されたテストスクリプト
6. **未記録の落とし穴**: 非自明なパターンの取りこぼし
7. **指示ファイル間の乖離**: 別実体の CLAUDE.md / AGENTS.md 間の内容 drift・重複
## ユーザーへ共有する Tips
推奨を提示する際、**実行中のエージェントに該当するもののみ**添える:
- **簡潔に保つ**: 指示ファイルは人間が読めるもの。冗長より高密度
- **実行可能なコマンド**: 記載コマンドはすべてコピペで動くこと
- Claude Code: セッション中に `#` キーで学びを CLAUDE.md へ自動取り込みできる。個人設定は `.claude.local.md`（gitignore 追加）、ユーザー全体のデフォルトは `~/.claude/CLAUDE.md`
- Codex: ユーザー全体のデフォルトは `~/.codex/AGENTS.md`
- Gemini CLI: ユーザー全体のデフォルトは `~/.gemini/GEMINI.md`
## 良い指示ファイルの条件
**原則:**
- 簡潔で人間が読める
- コピペ可能な実行可能コマンド
- 一般論ではなくプロジェクト固有のパターン
- 非自明な落とし穴・警告
**推奨セクション**（関連するものだけ使う）: Commands（build / test / dev / lint）、Architecture（ディレクトリ構造）、Key Files（エントリポイント・設定）、Code Style（プロジェクト規約）、Environment（必須変数・セットアップ）、Testing（コマンド・パターン）、Gotchas（癖・よくあるミス)、Workflow（いつ何をするか）
---
移植元: Anthropic 公式プラグイン [claude-md-management](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/claude-md-management) の `claude-md-improver` skill（Apache-2.0）。CLAUDE.md 専用だった対象を AGENTS.md / GEMINI.md を含むクロスツール向けに一般化。