ai-ready

AI 対応リポジトリスキル

ペルソナ

経験豊富なリポジトリメンテナーの視点で取り組んでください。レビューの負担とコントリビューターの手間を減らすことを優先してください。生成するすべてのファイルには、存在する価値が必要です。汎用的な定型文はノイズになります。

---

以下の手順に沿って、現在のリポジトリを分析し、不足している AI 対応設定アセットをすべて生成してください。

初回実行と再実行： 初回はほとんどのアセットが不足しているため、このスキルで作成します。再実行時は、既存のアセットを現在のコードベースと照らし合わせて監査し、乖離、古くなった内容、最近の PR レビューで生まれた新しい規約がないか確認します。

アセットのスキップ： ユーザーのプロンプトで特定のアセットをスキップするよう指示されている場合は、その除外指定に従ってください。分析はすべて実施し、除外されたアセットの生成だけをスキップします。

レポートのみのモード： ユーザーがファイルを生成せずにレポートを求めている場合（例：「このリポジトリはどれくらい AI 対応できていますか？」「このリポジトリを評価してください」）、分析をすべて実施し（Step 0～1）、レポートを表示します（Step 11）。生成手順（Step 2～10）はすべてスキップしてください。

追跡対象の 11 アセット

アセットは 3 つのカテゴリに分類されます。スコアには、ステータスが Nailed It のアセットを数えます。

🤖 AI コンテキスト — AI エージェントがリポジトリを理解するために読むもの

#	アセット	生成手順
1	AGENTS.md	Step 2
2	ツール別ポインターファイル（.github/copilot-instructions.md、CLAUDE.md、…）	Step 3
3	保守マトリックス（AGENTS.md 内）	Step 2
4	レビュー担当エージェント（.github/agents/）	Step 4c
5	スタータースキル（.github/skills/）	Step 4d
6	セキュリティスキル（対象領域がある場合、.github/skills/）	Step 4e

🔧 開発ワークフロー — PR を適切に保ち、コントリビューターを支援するもの

#	アセット	生成手順
7	CI ワークフロー（.github/workflows/ci.yml）	Step 5
8	Issue テンプレート（.github/ISSUE_TEMPLATE/）	Step 6
9	PR テンプレート（.github/PULL_REQUEST_TEMPLATE.md）	Step 6

📖 オンボーディング — 新しいコントリビューターの立ち上がりを支援するもの

#	アセット	生成手順
10	変更履歴（CHANGELOG.md）	Step 9
11	ドキュメント（または「不要」であることを明記した注記）	Step 10

スコアリング： 🟩 Nailed It（カウント対象） · 🟨 改善の余地あり（カウント対象外） · ⬜ 不足（カウント対象外）。 メダル、上限を決める 2 つの前提条件、スコアで決して主張してはならない内容については、references/report-template.md を Step 11 で読むこと。

---

Step 0 — GitHub コンテキストを自動検出する

このスキルは GitHub を前提としており、すべての情報を GitHub のツールから検出します。

0a. リポジトリを特定する

git remote -v を実行して、GitHub の owner/repo を抽出します。GitHub でない場合は、ローカルのみの分析に切り替えます。

0b～0d. メタデータを取得し、PR レビューを調査して、コミュニティの健全性を確認する

GitHub MCP ツールまたは gh CLI を使って、リポジトリのメタデータ、PR レビューの傾向、コミュニティの健全性に関する不足を自動検出します。API テーブル全体、PR の調査手法、健全性の不足を特定する方法については、references/github-discovery.md を参照してください。

人間とレビューエージェントの双方から繰り返し寄せられるレビューのフィードバックは、AGENTS.md の規約になります。最近の傾向ほど重視し、放棄された規約は現行ルールとして復活させず、その旨を明記してください。

---

Step 1 — コードベースを分析する

GitHub コンテキストからリポジトリの「概要」がわかります。ローカル分析からは、その「仕組み」がわかります。glob、grep、view を、Step 0 で得た GitHub コンテキストと組み合わせて使ってください。

1a. 言語、フレームワーク、リポジトリの種類を検出する

マニフェストファイルを探して詳細を抽出します。マニフェストの一覧、VS Code 拡張機能の検出、複数アプリのコレクション、デモアプリのパターン、コース／チュートリアルリポジトリの検出については、references/detection-tables.md を参照してください。

コースリポジトリ（信号が 3 つ以上あるもの：番号付きフォルダー、レッスン関連のキーワード、主要なアプリがないこと）では、Step 2～5 を適宜調整します。信号の一覧と手順の調整内容は detection-tables.md を参照してください。

1b–1c. テスト環境と CI を検出する

コミュニティのワークフロー（stale、welcome、labeler）は有効な自動化であり、CI がないという意味ではありません。 ワークフローが stale-bot のみであることを理由に、リポジトリに CI がないと報告しないでください。

1d. 既存の AI 設定を確認する

次を確認します：AGENTS.md、.github/copilot-instructions.md、CLAUDE.md、.cursorrules、.cursor/rules/、 .github/skills/、.github/agents/、.github/extensions/、.devcontainer/。

問題には 2 つのパターンがあり、よくあるのは 2 つ目です。 AGENTS.md が標準のファイルであり、ほかの指示ファイルはすべて、そこを参照する短い案内にしてください。

1. 重複 — ツール用ファイルに、AGENTS.md にも記載されている規約を再掲しています。これは 改善の余地あり として指摘します。重複したガイダンスは気づかないうちに食い違い、同じ規約について 2 つのエージェントが異なるバージョンを参照することになります。
2. 分散 — 各ファイルに異なる内容があり、どちらも不完全です。実際にはほとんどのリポジトリで起きており、何も問題がないように見えるため、重複よりも深刻です。AGENTS.md しか読まないツールは規約を把握できず、Copilot ファイルしか読まないツールはビルドとテストのコマンドを把握できません。

分散がある場合は、ツール用ファイルには存在するが AGENTS.md にはないセクションを具体的に列挙してください。これらをステップ 2 で取り込む必要があります。ここではツール用ファイルを書き換えず、移動を提案したうえで、ユーザーに判断を委ねてください。

1e–1h. 設定、変更履歴、ドキュメント、構成を確認する

CODEOWNERS、dependabot.yml、Issue と PR のテンプレート、LICENSE、README の Contributing セクション、変更履歴の状態、ドキュメントの設定を検出します。判断が難しい点が 2 つあります。変更履歴は CHANGELOG.md ではなくドキュメントサイトにある場合があるため、見つからないと報告する前に 参照ファイルをたどって確認してください。また、最新の Git タグを基準に鮮度を判断し、ファイルの日付は基準にしません。

1i. 調査結果をまとめる

GitHub の情報とコードベースの分析を、ファイルパスの根拠とともにまとめた、構造化された調査結果テーブルを作成します。調査結果テーブルのテンプレート全体については、references/detection-tables.md を参照してください。

11 個のアセットのうち、欠けているものを列挙します。既存のアセットについては、分析結果と照合し、乖離があれば「改善の余地あり」として指摘します。

1j. モノレポの領域を検出する

ワークスペース設定が見つかった場合は、領域名、パスの glob、主要な技術スタックを列挙します。大規模なライブラリのモノレポでは、パッケージ間の依存関係を整理します。詳細は、references/detection-tables.md を参照してください。

ステップ 2 — AGENTS.md を生成する

存在しない場合は、リポジトリのルートに AGENTS.md を作成します。すでに存在する場合は、分析結果と比較し、乖離があれば指摘します。

AGENTS.md は、このリポジトリの仕組みを示す標準のエントリーポイントです。すべてのツールが読む唯一のファイルであり、各規約を記載する唯一の場所です。だからといって、すべてをここに書くわけではありません。生成する前にreferences/agents-md.mdを読み、何を記載し、何を記載せず、残りをどこに置くかを確認してください。

以下の 2 つのルールがすべてを決めます。

1. 見つけやすさのテスト。 どのセクションを書く場合も、まず エージェントがコードを読めば見つけられるか を確認してください。見つけられるなら、書く必要はありません。AGENTS.md はすべてのタスクの前に読み込まれるため、行ごとに毎回コストがかかり、実際の作業と注意を奪い合います。ディレクトリツリー、技術スタックの一覧、アーキテクチャの概要は、どれもこのテストに合格しません。このリポジトリで本当に予想外な点だけを生成し、構成が一般的なら、そうした項目はすべて省いてください。

2. 適切な範囲の中で、最も限定的な場所に記載する。 すべてのタスクで必要 → ルートの AGENTS.md。特定の領域だけで必要 → そのディレクトリ内のネストされた AGENTS.md。これは標準の一部であり、モノレポを拡張するための想定された方法です（最も近いファイルが優先されます）。特定の手順を行うときだけ必要 → スキル（ステップ 4d）。参照用の資料 → リンクされたドキュメント。

まずは 20〜30 行にします。このリポジトリでエージェントが最もよく間違えることを記載し、実際の誤りによって不足が証明された場合にだけ増やしてください。150 行は上限であり、目標ではありません。それを超えるなら、何かを移動してください。このファイルは長くなるほど質が落ちます。モデルが指示に従えなくなる前に、だいたい 150〜200 個の指示を処理し、1 行ごとに既存の指示と注意を奪い合うためです。

次の項目を生成してください。コード内のどこにも存在しないため、必ずテストに合格します。

• ビルド、テスト、実行コマンド — ツール設定に埋もれていますが、すべてのタスクで必要です。バージョンをハードコードせず、マニフェストを参照してください。
• 推測できない規約 — コードとリンター設定を見ても読み取れない言語、フレームワーク、テスト、スタイルのルールです。リンターがすでに適用している場合は、改めて記載せず設定へのリンクを貼ってください。
• PR レビューから抽出した規約（ステップ 0c）
• 新しい［機能／モジュール］の追加 — 列挙型、インデックスからの再エクスポート、設定宣言など、登録に関わる一連の手順です。1 つのファイルを読むだけでは、登録手順全体は把握できません。
• よくある落とし穴 — ここでよくある間違いです。これは経験に基づくもので、コードにはありません。
• メンテナンスマトリクス — コードベースの各部分を変更するときに、何を更新する必要があるかを示します。実際のファイルパスを記載してください。最上位のファイルだけで止めず、実際の依存関係を追跡します。.csproj の ProjectReferences、インポートの連鎖、mod 宣言、__init__.py の再エクスポートなどが対象です。表形式を維持してください。ステップ 4d でこれを手順にするため、ここに手順も重ねて記載しないでください。

リポジトリ内で予想外な点がある場合を除き、次の項目は生成しないでください。 プロジェクトの概要、CI/CD セクション、リポジトリ構造のセクション、技術スタックの一覧です。どれもすべてのタスクで注意を消費し、エージェントが自分で確認できることを伝えるだけです。

主要なパターンと規約という見出しは、たいてい上記の規約の項目と名前が違うだけです。どちらか一方を選んでください。

テスト規約 — テストできないという主張。 リポジトリに複数のテストレーンがある場合（高速なモック単体テストと、実際のフレームワークにアクセスする低速なテスト、または単体・統合・E2E テストなど）、プルリクエストにある「これはテストできない」という主張を鵜呑みにしないよう、エージェントへのルールを追加してください。同意する前に、別のテストレーンを検索し、新しいコードが依存する特定の API または状態をスタブ化した既存の先例がないか確認します。あるテストレーンでは正しい主張でも、別のテストレーンを確認すると誤りであることがよくあります。「テストできない」は、変更にカバレッジがないまま、誰も異議を唱えずに取り込まれる最も簡単な口実です。

このルールは、複数のテストレーンが実際に存在する場合にのみ生成してください。テストレーンが 1 つしかない構成では、リポジトリにない状況についての助言になるため、省いてください。

ほとんどのリポジトリにない2つのセクションを生成する

どちらのセクションも、すべての行を人の解釈なしに機械で判定できる必要があります。 失敗時にゼロ以外の終了コードを返すコマンドは、この条件を満たします。「きれいなコードを書く」では満たしません。

## 完了の条件 — 変更が完了と見なされるために満たす必要がある条件です。リポジトリで実際に使われているコマンドから導きます。

## 人の確認なしにマージしない条件 — このリポジトリに実在するリスクのあるパスを基にし、カテゴリではなくパスや条件として明示する境界です。

境界の行を書く前に、照合した内容が data/risk-paths.yml § false_positivesに該当しないか確認してください。 そこにある各項目は、このスキルが実際のリポジトリで誤って判断した行です。誤った項目は、項目の不足よりも問題です。本来必要のなかったマージに人の確認を再び持ち込むうえ、明らかに誤った行が1つでもあれば、読者はこのセクション全体を当てずっぽうだと考えるようになります。

両セクションのテンプレートと、境界の見出しの下に置く必要がある定義行は、references/agents-md.md § 2つのセクションの生成にあります。

採点基準： AGENTS.mdが申し分なしと評価されるのは、両セクションがあり、各行を機械でチェックでき、さらに## 人の確認なしにマージしない条件に定義行が含まれている場合のみです。これらがないAGENTS.mdは改善の余地ありです。エージェントの作業方法は示しますが、何を単独で完了してよいかは示しません。

---

ステップ3 — ツールごとのポインターファイルを生成する

ステップ1dで検出した各ツールと、デフォルトの.github/copilot-instructions.mdに対して、短いポインターを生成します。

ツール	ファイル
GitHub Copilot	.github/copilot-instructions.md
Claude Code	CLAUDE.md
Cursor	.cursorrules

ポインターの内容は3行です。

# Conventions

The conventions for this repository live in [`AGENTS.md`](<relative path>). Read that file first.

リンクはリポジトリのルートではなく、ポインターファイルからの相対パスです。

ポインターファイル	リンク
.github/copilot-instructions.md	../AGENTS.md
CLAUDE.md、.cursorrules（リポジトリのルート）	./AGENTS.md
.github/instructions/*.instructions.md	../../AGENTS.md

Copilotだけは、少しだけ例外を設ける価値があります。 Copilotは.github/copilot-instructions.mdを自動的にコンテキストに読み込むため、本当にCopilot固有の内容（それに限ります）だけは、同じファイル内のポインター行の後に追加できます。AGENTS.mdにすでにある規約を再掲しないでください。

重複させないでください。 既存のツールファイルにAGENTS.mdの内容が再掲されている場合、黙って書き換えず、レポートでドリフトとして指摘し、ユーザーが判断できるようにしてください（「害を与えない」を参照）。

モノレポ： スタックが異なる領域には、applyToパターンを指定した.github/instructions/{area-name}.instructions.mdを作成します。これらはルートの規約を重複させるのではなく、特定のパスを対象とするため、実際の内容を含めてもかまいません。

---

ステップ4b — .mcp.jsonを生成する

存在しない場合は、検出した依存関係（データベース、API、クラウドプラットフォーム、ブラウザー自動化、DevOpsツール）を基に、リポジトリのルートに.mcp.jsonを生成します。シークレットには${VAR}を使用します。プロジェクトで実際に必要なサーバーだけを含め、推測でサーバーを追加しないでください。

.vscode/mcp.jsonがある場合は、改善の余地ありと指摘し、.mcp.jsonへの移行を提案します。

---

ステップ 4c — レビュアーエージェントを生成する

.github/agents/ がない場合、またはレビュアーが含まれていない場合は、レビュアーエージェントの初期セットを生成します。 多くのリポジトリでは spec-conformance、test-integrity、blast-radius の3つで十分ですが、数はルールではなく、リポジトリに応じて決めます。 この問いへの答えが no になり得るものだけを生成してください。テストのないリポジトリでは test-integrity を省略し、元に戻すのが難しいものがない場合は blast-radius を省略します。省略したものとその理由を伝えてください。完全な本文と追加方法については、references/reviewer-agents.md を参照してください。

利用するツールでモデルを固定できる場合は、モデルを分散させるようユーザーに伝えてください。 1つのモデルを使うレビュアーエージェントは、見落とす点もほぼ同じです。同じモデルに3つ配置しても、プロンプトが3つある1人のレビュアーにすぎません。

blast-radius は、境界と実際に実行されるものを結び付ける、ステップ2で記述した ## Never merges without a human セクションを読み取ります。

リポジトリにすでにこれらの懸念事項をカバーするエージェントがある場合は、そのまま残し、乖離を指摘してください。

---

ステップ 4d — メンテナンスマトリックスからスタータースキルを生成する

マトリックスと Adding a New [Feature/Module] の登録チェーンから、.github/skills/shipping-a-change/SKILL.md を生成します。

---
name: shipping-a-change
description: What to update when you change something in this repo, and what "done" requires. Use before opening a pull request.
---

# Shipping a change

## Add a new <thing this repo adds most often>
1. <real path> — create it
2. <real path> — register it
3. <real path> — export or declare it
4. <real command> — verify

## When you change this, also change that
| Change | Also update |
|---|---|
| <real path> | <real paths> |

## Done
<the `## Done means` list from AGENTS.md, verbatim>

実際のパスと実際のコマンドを使ってください。 プレースホルダーだらけのスキルは、ないよりも悪いものです。権威があるように見えて、何も教えません。

.github/skills/ にこれをカバーするものがすでにある場合は、代わりに乖離を指摘してください。 マトリックスの内容が薄い場合（実際のカスケードが3つ未満の場合）は、生成を省略し、その理由を伝えてください。1行だけのスキルはノイズです。

---

ステップ 4e — セキュリティスキルは、対象となる領域がある場合のみ生成する

汎用的なセキュリティスキルは生成しないでください。 「シークレットをハードコードしない」は、すでにあらゆるモデルの学習データに含まれています。ブログ記事のようなセキュリティスキルは、ここで本当に重要なルールを薄め、人々が読まなくなるため、ないよりも悪いものです。このステップの目的は、このリポジトリ特有で、ほかにはない内容を記録することです。

セキュリティ対象領域をスキャンします（references/detection-tables.md の § Security surface detection を参照）。見つからない場合は、スキルを生成しないでください。ステップ4dで内容の薄いマトリックスを省略する場合と同様に、レポートに1行で記載します。

対象領域が見つかった場合は、リポジトリに実際にある内容をもとに .github/skills/security-review/SKILL.md を生成します。参照元の優先順位は次のとおりです。

1. すでに書き留められているセキュリティに関する注意事項 — SECURITY.md、AGENTS.md 内のチェックリスト、機密性の高いコード付近のコメントなどです。通常はすでにあるため、新たに作らず移動してください。
2. 対象領域そのもの — 実際のハンドラーと信頼境界を、実際のパスとともに明記します。
3. セキュリティに関する PR レビューコメント（ステップ0c）— レビュアーが同じセキュリティ上の質問を繰り返しているなら、その内容がすでにスキルになっています。

記入する骨組みは、references/detection-tables.md の § Security surface detection にあります。

すべての行で、このリポジトリに実在するものを挙げてください。 セクションの内容が一般的なベストプラクティスの言い換えにすぎない場合は、そのセクションを削除してください。

セキュリティスキルまたは SECURITY.md がすでにある場合は、移動を提案し、ユーザーに判断を委ねてください。

---

ステップ 5 — CI ワークフローを生成する

PR をトリガーとするワークフローがない場合は、.github/workflows/ci.yml を作成します。pull_request と push のトリガーに、ドキュメントと設定を対象外にする paths-ignore を設定し、プロジェクトで実際に使われているツールチェーンに合ったビルドとテストのジョブを含めます。ステップ0bで検出したデフォルトブランチを使い、main をハードコードしないでください。既存のワークフローは決して変更しないでください。

---

ステップ 6 — Issue テンプレートと PR テンプレートを生成する

存在しない場合は、バグ報告用と機能リクエスト用の YAML フォームに加え、説明、変更内容、テスト方法、チェックリスト（メンテナンスマトリックスに基づく）を含む PR テンプレートを作成します。旧形式の .md テンプレートは「改善の余地あり」として記録します。

---

ステップ 7 — README の Contributing セクションを更新する

README が存在するものの、Contributing セクションがない場合は、CONTRIBUTING.md があればそのファイルにリンクします。なければ、フォーク、ブランチ、PR の手順とテストコマンドを記載した Contributing セクションを追加します。README のその他の部分は書き換えないでください。

---

ステップ 9 — 変更履歴を評価して改善する

存在しない場合は、Keep a Changelog 形式で CHANGELOG.md を作成します。ポインターファイルの場合は、リンク先を確認します。古くなっている場合は、日付を添えてその旨を示します。標準以外の場所については、AGENTS.md に記載します。

---

ステップ 10 — ドキュメントを評価して改善する

ドキュメントが存在する場合は、その場所、フレームワーク、規約を AGENTS.md に記録します。内容を持たないポインターファイルには記録しないでください。存在しない場合は、プロジェクトの種類に応じて必要かどうかを評価します。ドキュメントの状況は必ず AGENTS.md に記載してください。

---

ステップ 11 — AI-Readiness レポートを表示する

references/report-template.md の形式でレポートを表示します。レポートの末尾に、フロントマターの metadata.version にあるスキルのバージョンを記載します（例：Assisted by ai-ready v1.0.0）。その後、次の手順を実行します。

1. AI-Ready バッジを追加します（report-template.md § 11a を参照）。
2. PR の作成を提案します（report-template.md § 11b を参照）。

---

重要なルール

悪影響を与えない

このスキルの第一の責務は、リポジトリを見つけたときより良い状態にすることです。決して悪化させてはいけません。

• 重複ファイルは絶対に作成しないでください — ファイルを作成する前に、既知のすべての場所（標準、旧式、ルート）を確認します。ファイルがどこかに存在する場合は、別のコピーを作成せず、統合してください。
• main/master に直接 push しないでください — 常にフィーチャーブランチを作成し、レビュー用の PR を開きます。例外は、ユーザーがデフォルトブランチへのコミットを明示的に依頼した場合のみです。
• 開いた PR を放置しないでください — PR が開かれ、CI が成功したら、マージするか（小規模で、十分にテストされ、判断に曖昧さがない場合）、ユーザーに方針を確認してください。どちらの場合も結果を報告します。CI が失敗している、またはまだ保留中の場合はマージせず、修正するか、完了を待つか、阻害要因を報告してください。
• マージする場合は、必ず squash し、その後ブランチを削除してください — ローカルとリモートの両方で削除します。
• 既存ファイルを上書きしないでください — 不足しているアセットのみを作成します。差異があれば、ユーザーの確認用に報告します。
• ユーザーの承認なしにファイルを削除しないでください — 重複の統合や古いファイルの削除を行う場合は、レビュー用 PR に削除を含めてください。

一般ルール

• ページャーを開かないでください — すべての gh／git コマンドの末尾に | cat を追加します。git --no-pager を使用します。
• レポート全体を必ず表示してください — レポートは、見つかった内容と変更内容をユーザーが確認するためのものです。
• ユーザー向けの出力に Markdown の見出しを使わないでください — 太字と絵文字を使用します。
• 課題や PR のやりとりでは、必ず AI Ready スキルに言及してください — 課題や PR に投稿する際（本文またはコメント）には、Assisted by [ai-ready](https://github.com/johnpapa/ai-ready) のように明示的にクレジットを記載します。
• ドキュメントは必ずリポジトリの規約に合わせて更新してください — 生成されたガイダンスやワークフローを変更する場合は、このリポジトリの保守マトリックスに記載されているドキュメントと変更履歴を更新します。他のリポジトリにファイルがあるからといって、このリポジトリにも存在すると決めつけないでください。
• PR の競合には必ず先回りして対処してください — PR を作成するときは、ターゲットブランチと同期し、競合の解消を試みます。競合が残る場合は、どのように進めるかをユーザーに明示的に確認してください。

---