| name | agents-md-creator |
| description | リポジトリを調査し、短く実用的な AGENTS.md を作成・更新・整理し、生成後に客観レビューして改善点を自己修正するスキル。何を書くべきか / 書くべきでないかを整理したいとき、AGENTS.md を新規作成したいとき、長すぎる AGENTS.md を見直したいとき、生成済み AGENTS.md をレビューして磨きたいとき、AGENTS.md を分割したいときに使う。 |
AGENTS.md Creator
概要
リポジトリの構造、日常コマンド、検証方法、既存ドキュメントを調べて、短く実用的な AGENTS.md を作る。
生成後はいったん第三者目線で見直し、見つけた改善点を自分で直してから完成させる。
詳細が増えすぎる場合だけ docs/agents/*.md に分割し、ルートには必要最小限だけを残す。
基本原則
- 先に調査し、後から書く。
AGENTS.md は推測ではなくリポジトリの事実を要約する。
- まず毎回使う情報を書く。低頻度の詳細や補足は
references/best-practices.md の基準に従って外へ逃がす。
- 既存の
README.md や docs/ を重複して要約しない。必要なら短い説明とリンクだけ残す。
- コマンド、パス、検証手順のような再現可能な情報を優先し、抽象的な心得だけで埋めない。
- ツール固有記法や特定エージェント専用構文に依存しない。プレーンな Markdown を使う。
- 既存文書の主言語に合わせる。判断材料がなければユーザーに確認する。
- 生成して終わらず、完成前に必ず客観レビューと自己修正を 1 パス入れる。
- レビュー結果は批評メモとして残すのではなく、原則として生成物へ反映する。
進め方
- 既存の
AGENTS.md, README.md, CONTRIBUTING.md, docs/, 主要設定ファイルを読んで、主言語、主要コマンド、検証方法、構造、制約を把握する。
references/best-practices.md を読み、ルートに残す内容と分割候補を切り分ける。
- 高影響で未確定な点だけを短く確認する。例: 主要な開発コマンド、承認境界、必須チェック、生成対象の言語。
- ルート
AGENTS.md は次の順で組み立てる。
- 一行概要
- よく使うコマンド
- 検証手順
- 重要パスや構造
- コーディング / テスト規約
- ワークフロー上の注意
- 追加ドキュメントへのリンク
- 詳細が長くなる場合だけ
docs/agents/*.md を作り、ルート側には短い説明付きリンクを残す。
- 生成した内容を、いったん「自分が書いた文書」ではなく「他人が置いた draft」と見なして
references/best-practices.md の rubric で客観レビューする。
- レビューで見つけた問題を優先順位に従って自己修正する。未解決の高影響な曖昧さだけをユーザーに確認する。
- 完成前に、コマンドの実在、パスの実在、重複、行数、古い記述の混入を再確認する。
生成後レビュー
- レビュー時は、自分の意図を弁護せず、初見のエージェントが読む前提で査読する。
- まず「削るべき情報」「外へ逃がすべき情報」がないかを見て、足りない情報より先に過積載を疑う。
README.md や docs/ の要約を増やすより、読む順番とリンクの付け方を整える。
- レビューだけで止めず、修正可能な指摘はその場で反映する。
- 最終成果物はレビュー済みで修正済みの
AGENTS.md とし、批評メモは補助情報に留める。
ルート AGENTS.md の推奨順序
- 最初に「何のリポジトリで、エージェントが最初に何を見るべきか」を短く書く。
- 次に日常的に使う
install, dev, test, lint, build などのコマンドを書く。
- その後にディレクトリ構造、編集方針、レビュー観点、安全上の注意を書く。
- 最後にだけ、補助ドキュメントや低頻度タスクへのリンクを書く。
docs/agents/*.md へ分割する条件
- ルートに入れると流れが崩れる長い説明がある。
- 一部のタスクでしか使わない詳細手順がある。
- 特定のサブシステム、生成物、運用フローだけで必要な知識がある。
- 既存の
docs/ と役割を分けた方が読みやすい。
分割した場合も、ルート AGENTS.md は入り口として単独で役立つ状態を保つ。
書かないこと
- 一般論だけのコーディング心得
- リポジトリから確認できない推測
- 既存 docs の焼き直し
- まれにしか使わない運用の詳細手順
- 全ファイル一覧や全スクリプト一覧
- 特定ツールでしか通じない独自構文
仕上げの確認
- ルート
AGENTS.md が短く、上から順に読むだけで着手できるか確認する。
docs/agents/*.md は本当に必要な場合だけ作る。
- 追加したコマンドとパスが実在するか確認する。
- 客観レビューで出た改善点を反映し終えたか確認する。
- 古い
AGENTS.md を更新する場合は、残すべきルールと削るべき重複を分けて扱う。