agents-md-generator

AGENTS.md ジェネレーター（ルート＋ネスト、ポータブル）

目的

簡潔で有用な情報に絞った AGENTS.md ファイルを維持します。

• ルート AGENTS.md — リポジトリの目的、ナビゲーション、共通のツールチェーン、標準コマンド、ドキュメントとスキルへのリンク。
• ネストされた AGENTS.md — モジュール／パッケージの目的、ローカルコマンド、モジュールの参照情報。

段階的開示を活用します。AGENTS.md は簡潔に保ち、詳細はドキュメントやスキルに記載します。

---

スキルの場所（エージェント固有）

• .agents/ や特定の固定ディレクトリが存在すると決めつけないでください。
• スキルは次の場所にある場合があります。
  • リポジトリ内（組み込み）、
  • または外部／グローバルのスキルライブラリ（外部）。
• ローカルスキルを参照する場合は、プロジェクトで既に使用されている既存のスキルルートか、リポジトリのドキュメントに既に記載されている既存のプロジェクトパスのみを使用してください。
• ローカルのスキルディレクトリが存在しない場合は、スキル名のみを参照してください（外部）。
• スキルを保存するためだけに、隠しエージェントディレクトリを作成しないでください。

---

リソースの振り分け

テンプレートはひな形として使用し、そのまま出力しないでください。

• ルートの AGENTS.md を作成または更新する場合に限り、references/AGENTS_TEMPLATE_ROOT.md を読みます。
• ディレクトリが独自の AGENTS.md を必要とするネストされたモジュールだと確認できた後に限り、references/AGENTS_TEMPLATE_MODULE.md を読みます。
• すべてのプレースホルダーを置換するか削除してください。完成した AGENTS.md ファイルに、未解決の <...> テンプレートマーカーを残してはいけません。

---

実行するタイミング

次の場合にこのスキルを実行します。

• AGENTS.md が存在しない、肥大化している、矛盾している、または古くなっている。
• AGENTS.md の生成、修復、簡略化、分割、更新が必要である。
• 新しいパッケージ／サービス／モジュールが追加された。
• リポジトリの構造が変わった（モノレポの拡大または分割）。
• チームが多様なスタック間で一貫したエージェントコンテキストを求めている。

---

ワークフロー（決定論的）

1. リポジトリの構成を把握する

• リポジトリのルートを特定します（利用可能な場合は git のルート）。
• 言語／ツールのマーカーを検出します。
  • package.json、pnpm-workspace.yaml
  • go.mod、go.work
  • pyproject.toml
  • Cargo.toml
  • pubspec.yaml
  • pom.xml、build.gradle
• docs/、README.md、既存の AGENTS.md を探します。

---

2. モジュールの境界を検出する

次の条件を満たすディレクトリには、ネストされた AGENTS.md を作成します。

• 独立したビルド／パッケージマニフェストを含む
• または、デプロイ可能なサービス単位を表す（apps/、services/、packages/）
• かつ、親のスコープとは異なるコマンド、ドキュメント、担当範囲、デプロイに関する注意事項、またはツールチェーンのガイダンスがある。

ルートの指示を繰り返すだけのネストされた AGENTS.md は作成しないでください。

---

3. ルート AGENTS.md を生成／更新する

制約：

• 理想的なサイズ：60 行以下
• 必ず含める内容：
  • リポジトリの目的を表す 1 文
  • 主要なツールチェーン／パッケージマネージャー
  • 標準コマンド（標準と異なる場合）
  • ドキュメントへのリンク
  • モジュール内ではネストされた AGENTS.md を読むよう指示すること
  • 任意のスキル参照（ローカルまたは外部に応じて調整）
• 既存のルート AGENTS.md にある、確認済みのコマンド、ドキュメント、セキュリティ／シークレット／デプロイに関する警告、重要なローカルルールを保持します。

---

4. ネストされた AGENTS.md を生成／更新する

制約：

• 理想的なサイズ：40 行以下
• 必ず含める内容：
  • モジュールの目的を表す 1 文
  • モジュール固有のコマンド
  • ローカルドキュメントへの参照
  • 任意のスキル参照（状況に応じて調整）
• 既存のネストされた AGENTS.md にある、確認済みのモジュールに関する警告、担当範囲、デプロイに関する注意事項、ローカルルールを保持します。

---

5. 段階的開示のルール

• スタイルガイド、CI ポリシー、アーキテクチャの詳細を埋め込まないでください。
• 既存のドキュメントや外部／ローカルのスキルへのリンクを優先します。
• コマンドやポリシーの情報源として実在する、または明示的に記載されているリンクのみを含めてください。
• 権威あるドキュメントが存在する場合は、古くなった長文のセクションをリンクに置き換えます。
• 正確性／セキュリティに不可欠な場合を除き、「常に／絶対に」といったルールは避けてください。

---

6. 安全性／正確性の確認項目

• コマンドをでっち上げないでください。
• 次の情報からコマンドを推定します。
  • パッケージスクリプト
  • Makefile
  • CI 設定
  • README
• 不確かな場合は、次のように記述します。 「確認できているコマンド：<既存のファイル> を参照」
• 重要な警告（セキュリティ、シークレット、デプロイ）を保持します。

出力要件

作成または更新するファイルは、次のものだけです。

• <repo_root>/AGENTS.md
• <module_dir>/AGENTS.md

エージェント設定用のフォルダーは作成しないでください。

---

スキル参照の方針

AGENTS.md にスキルへの参照を追加する場合：

1. ローカルのスキルディレクトリが検出された場合

   See: <detected-skill-root>/<skill-name>/SKILL.md
   

2. ローカルのディレクトリが存在しない場合

   Skill: agents-md-generator (external)
   

ファイルシステムのパスを決めつけないでください。

---

検証

完了前に、次の点を確認してください。

• 作成または更新したのは、ルートまたはモジュールの AGENTS.md ファイルだけであること。
• 最終的な AGENTS.md ファイルに、未解決の <...> プレースホルダーが含まれていないこと。
• 相対パスのドキュメントリンクが存在するか、コマンドやポリシーの参照元ファイルを明確に示していること。
• コマンドが、パッケージスクリプト、Makefile、CI 設定、または README でサポートされていること。確認できるコマンドがない場合は、Known commands: see <existing file> を使用してください。
• 行数の上限を守っていること。ルートは 60 行以下、ネストされたモジュールは 40 行以下です。
• ネストされたファイルは、モジュールの境界が確認できた場合にのみ存在すること。
• 既存の AGENTS.md ファイルにある重要な警告を保持していること。