md-docs

Markdown ドキュメントの管理

概要

README.md やエージェントのコンテキストファイル（AGENTS.md / CLAUDE.md）など、Claude Code のワークフローに関するプロジェクトドキュメントを管理します。このスキルでは、対象読者を厳密に分けます。README.md は人間向け、AGENTS.md はコマンドを実行するエージェントと開発者向けです。新しいプロジェクトを初期化するとき、既存のドキュメントを更新するとき、またはコンテキストファイルが現在のコードを正確に反映しているか確認するときに、このスキルを使用します。

既定では、スキルはリポジトリのルートだけでなく、リポジトリ全体を再帰的に処理します。update-* ワークフローは、ツリー内に存在するすべての README.md / AGENTS.md を検索して更新します。init-* ワークフローは、まだファイルがないリポジトリのルートと各パッケージのルート（マニフェストまたはワークスペースメンバーを含むディレクトリ）にファイルを作成します。各ファイルの対象範囲は、そのファイルが置かれたディレクトリ以下のサブツリーと、最も近い上位のマニフェストです。--root-only を渡すと、どのワークフローでもリポジトリのルートだけに制限できます。また、path 引数を渡すと、指定したサブツリーだけを対象にできます。

このスキルでは、無条件に生成するのではなく、検証と妥当性確認を重視します。ドキュメントを作成または更新する前に、実際のコードベースの構造、ファイルの内容、パターンを分析してください。生成する内容はすべて簡潔で、命令形を用い、説明過多やチュートリアル調ではなく、専門家同士のやり取りに適したものにしてください。

対象読者の区分

このスキルが作成するすべてのものに適用される中心的なルールです。

ファイル	対象読者	含める内容	含めない内容
README.md	リポジトリを閲覧する人（GitHub、npm など）	説明、バッジ、ドキュメント／サイト／デモへのリンク、参考資料、論文、関連プロジェクト、謝辞、ライセンス、コントリビュートへの案内	CLI コマンド、just レシピ、パッケージスクリプト、ビルド／テスト／lint のワークフロー、プロジェクト構成ツリー、API リファレンス
AGENTS.md（および CLAUDE.md シンボリックリンク）	リポジトリで作業する AI エージェントと開発者	技術スタック、コマンド（インストール、開発、ビルド、テスト、lint）、just レシピ、package.json スクリプト、Makefile ターゲット、コードスタイル、アーキテクチャ、規約、コントリビュートのワークフロー	マーケティング文、バッジ、開発に関係のない外部リンク

判断に迷ったら、次のように考えてください。GitHub でこれを読む人に役立つか、それともコマンドを実行する開発者／エージェントだけに必要か。 後者であれば、AGENTS.md に記載します。

例外 — 運用担当者が実行するセットアップガイド。 この区分は既定の方針であり、絶対ではありません。README は、dotfiles リポジトリ（例：新しいマシンの初期設定手順を README に記載した chezmoi のソースツリー）、ホームラボやインフラの設定、個人用ツールなど、人間の読者が手順を実行する運用担当者でもある場合や、ユーザーから明示的に求められた場合に、簡潔な技術ガイドを含めてもかまいません。ガイドは短く、セットアップ、初期設定、復元などの作業に絞ってください。開発ワークフローのコマンド（ビルド、テスト、lint）は、引き続き AGENTS.md に記載します。更新時は、既存の例外対象ガイドを削除せず、そのまま残してください。

ワークフローの選択

ユーザーの意図に合ったワークフローを選択します。

トリガー	ワークフロー	参照
「update README」／「refresh README」（ファイルがすでに存在する）	README の更新	references/update-readme.md
「init README」／「create README」／「new README」（ファイルがない、または --force）	README の初期化	references/init-readme.md
「update CLAUDE.md」／「update AGENTS.md」／「update context files」	コンテキストファイルの更新	references/update-agents.md
「init AGENTS.md」／「create CLAUDE.md」／「init context」	コンテキストの初期化	references/init-agents.md

選択ルール：

• 対象ファイルがすでに存在し、ユーザーが「update」／「refresh」／「fix」と指示した場合は、update-* ワークフローを選択します。
• 対象ファイルがない、またはユーザーが「create」／「init」／「new」と指示した場合は、init-* ワークフローを選択します。
• 指示が曖昧な場合は、まず対象ファイルを列挙し（再帰的な検索を参照）、ユーザーに確認します。
• ユーザーが引数なしでスキルを実行した場合、推測せず、ツリー全体に存在するファイルの一覧を表示し、ワークフローを提案します。
• 1つのリクエストで複数のワークフローを指定してもかまいません（例：「README と AGENTS.md を更新」）。ユーザーが指定した順に実行し、それぞれの結果を個別に報告します。
• 選択した各ワークフローは、検出ステップで見つかったすべての対象ファイルに適用されます。ただし、--root-only または対象を絞る path 引数で検索範囲が制限される場合を除きます。

CONTRIBUTING.md の方針

このスキルでは CONTRIBUTING.md を管理しません。ワークフローで対象ファイルと同じ場所（リポジトリのルートまたは任意のパッケージルート）に CONTRIBUTING.md が検出された場合：

1. 他の書き込みはブロックせず、そのディレクトリについて注意事項を伝えます。
2. 内容を隣接する AGENTS.md に統合するよう推奨します（開発ワークフロー、ブランチ規約、レビュー手順、ツールの参照先は、現在 AGENTS.md が管理しているためです）。
3. 統合後に CONTRIBUTING.md を削除し、エージェントのコンテキストファイルを唯一の情報源にするよう提案します。
4. 自動で統合または削除は行いません。統合はユーザーが実行します。

標準の要約形式でディレクトリごとに推奨事項を報告し、ユーザーが依頼した README／AGENTS ワークフローを続行します。CONTRIBUTING.md 自体は対象外として扱います。

前提条件

ドキュメントのワークフローを使用する前に、基本的なプロジェクト構造を確認します。

git rev-parse --git-dir

出力に git リポジトリ内であることが示されているか確認します。初期化されていない場合もドキュメントのワークフローは続行できますが、git 固有の機能はスキップされます。

リポジトリのルートを一度だけ解決します。すべての検索はそのルートを基準に行います（path 引数が指定されている場合は、そのパスを基準にします）。

git rev-parse --show-toplevel

ワークフローを実行する前に、対象ファイルを列挙します（「再帰的な検索」を参照）。対象ファイルと同じ場所に CONTRIBUTING.md が見つかった場合は、そのディレクトリに上記の方針を適用します。

再帰的な検出

デフォルトでは、ワークフローはツリー内の関連するすべてのファイルを対象にします。--root-only を指定するとリポジトリのルートに限定され、path 引数を指定すると対象を1つのサブツリーに絞れます。

除外対象（常時）。 検出および作成では、以下を常にスキップします。

• VCS および依存関係・ビルド出力ディレクトリ：.git、node_modules、vendor、.venv、target、dist、build、out、.next、coverage。
• Git で無視されるもの（--exclude-standard／git check-ignore を利用）。
• 隠しドットディレクトリ（.github、.vscode、.claude など） — マニフェストを含むディレクトリは除きます。

update-* の検出 — 更新対象となる既存ファイルを探します。

# README.md / AGENTS.md tracked or untracked, respecting .gitignore
git ls-files --cached --others --exclude-standard -- '**/README.md' 'README.md' '**/AGENTS.md' 'AGENTS.md'

除外ディレクトリ以下のパスはすべて除外します。CLAUDE.md は隣接する AGENTS.md へのシンボリックリンクであり、単独では処理しません。

init-* の検出 — 新しいファイルを作成するパッケージルートを探します。

# Directories holding a language/tooling manifest = package roots
git ls-files --cached --others --exclude-standard \
  -- '**/package.json' 'package.json' '**/Cargo.toml' 'Cargo.toml' \
     '**/pyproject.toml' 'pyproject.toml' '**/setup.py' 'setup.py' \
     '**/go.mod' 'go.mod' '**/foundry.toml' 'foundry.toml' \
     '**/Gemfile' 'Gemfile' '**/composer.json' 'composer.json'

パッケージルートは、リポジトリのルートと、該当するマニフェストのディレクトリ（重複を除き、除外対象を除く）です。init-* は、対象ファイルが存在しないパッケージルートにのみ作成します。任意の末端ディレクトリには作成しません。

ファイルごとのスコープ。 各対象を個別に扱います。

• メタデータの取得元は、最も近い上位のマニフェストです（同じディレクトリにあるものを優先し、それ以外はリポジトリのルートまで上位をたどります）。
• ネストされた README.md は、ルートの AGENTS.md ではなく、同じディレクトリにある AGENTS.md にリンクします。
• 各 AGENTS.md の隣には、同じディレクトリに CLAUDE.md のシンボリックリンクを作成します（そのディレクトリで ln -sf AGENTS.md CLAUDE.md を実行）。
• CONTRIBUTING.md はディレクトリごとに確認し、隣接する AGENTS.md に統合します。

ファイルは一貫して深い階層から、またはルートから順に処理し、結果はパスごとにまとめて報告します。

共通の引数

これらのフラグは、すべてのワークフローで一貫して解釈されます。各項目ではワークフローごとの効果を詳しく説明しています。共通の解析規約については、references/common-patterns.md を参照してください。

• path（位置引数）：リポジトリ全体ではなく、このディレクトリのサブツリーに再帰処理を限定します。任意のワークフローと組み合わせられます。
• --root-only：再帰を無効にし、リポジトリのルートのみを対象にします（再帰導入前の動作）。常にサポートされます。
• --dry-run：ファイルを書き込まず、適用される変更をプレビューします。常にサポートされます。
• --preserve：ユーザーが作成した既存の内容を保持し、検証可能な誤りのみを修正します。update-* ワークフローで使用します。
• --minimal：有用な出力を最小限（トップレベルの構成のみ）に生成または検証します。
• --thorough（別名 --full）：詳細な分析を行うか、包括的な内容を生成します。最も時間がかかるモードです。
• --force：安全確認を上書きします（例：確認を求めずに既存の対象を上書き）。init-* ワークフローで使用します。処理対象のすべてのファイルに適用されます。

ユーザーが他のフラグを渡した場合はデフォルトモードに戻し、最終レポートに認識されないフラグについて1行の注記を記載します。

文体

生成するすべてのドキュメントでは、ワークフローにかかわらず、以下の規約に従います。

• 簡潔に：不要な言葉を省き、答えやリンクから始めます。
• 命令形（AGENTS.md）：説明的な表現（「プロジェクトがビルドされます」）ではなく、命令形（「プロジェクトをビルドする」）を使います。
• 平易な文章（README.md）：短く直接的な説明にし、命令口調での解説は避けます — 読者は実行するのではなく、情報を閲覧しています。
• 専門家向け：基本的な説明は省き、読者が十分な知識を持っていることを前提とします。
• 見つけやすく：見出し、リスト、コードブロックを使います。読者が必要な情報を30秒以内に見つけられるようにします。
• 正確に：記述する前に、すべてのコマンド、リンク、パスを実際のコードベースと照合します。

チュートリアル風の文章、重複する説明、「するために」といった埋め草は避けます。迷ったら、より簡潔にします。良い出力と悪い出力の例については、references/common-patterns.md を参照してください。

安全のデフォルト設定

すべてのワークフローに適用される動作です。

• 自動コミットは行いません。ワークフローが扱うのはドキュメントファイルのみです。ユーザーが確認し、手動で git add / git commit を実行します。復元には git を使用し、*.backup ファイルは作成しません。
• init-* ワークフローでは、--force が設定されているか、ユーザーが AskUserQuestion で確認しない限り、既存の対象を上書きしません。スイープの対象ファイルが多い場合は、ファイルごとに確認を求めず、まとめて一度確認します。
• デフォルトでは再帰的に処理しますが、リポジトリ内にとどまります（git rev-parse --show-toplevel）。再帰的な検出に記載された除外対象を適用します。範囲を絞るには --root-only または path 引数を使用します。検出された対象セットの外には書き込みません。
• スイープによって数個を超えるファイルを作成または書き換える場合は、予定されている対象を一覧表示し、書き込み前に確認を得ます（最初に暗黙の --dry-run プレビューを行うものとして扱います）。
• いずれかの対象と同じ場所に CONTRIBUTING.md がある場合は、編集しません。そのディレクトリについて AGENTS に統合することを推奨し、そのまま続行します。

コンテキストファイルを更新する

使用する場合：ユーザーが、実際のコードベースに合うように CLAUDE.md または AGENTS.md を更新するよう依頼したときです。トリガーフレーズには、「update CLAUDE.md」、「update AGENTS.md」、「update context files」、「fix context」、「refresh context」などがあります。

CLAUDE.md は同じディレクトリにある AGENTS.md へのシンボリックリンクであり、個別には処理しません。

ツリー内の既存のすべての AGENTS.md に対して実行されます（再帰的な検出を参照）。それぞれのファイルは自身のディレクトリと最も近いマニフェストの範囲を対象とします。AGENTS.md が管理する内容：スタック、すべての CLI コマンド（インストール、開発、ビルド、テスト、lint、デプロイ）、just レシピ、package.json スクリプト、Makefile ターゲット、コードスタイル、アーキテクチャ、規約、コントリビューションのワークフロー。

入力：既存の各 AGENTS.md（必須）、最も近い上位のマニフェスト、ロックファイル、スクリプト、justfile、Makefile。出力：書き換えられた AGENTS.md ファイル、およびそれぞれに対応する更新済みの CLAUDE.md シンボリックリンク。

認識されるフラグ：path、--root-only、--dry-run、--preserve、--thorough、--minimal。

references/update-agents.md を参照してください。

README を更新する

使用する場合：ユーザーが既存の README.md の更新またはリフレッシュを依頼したときです。トリガーフレーズには、「update README」、「refresh README」、「fix README」、「regenerate README」などがあります。

ツリー内の既存のすべての README.md に対して実行されます（再帰的な検出を参照）。README.md がないパッケージルートは、そのディレクトリを README を初期化する に振り分けます（または、--force を指定した場合は、update-readme によるその場所での作成を許可します）。

README が管理する内容：説明、バッジ、リンク（ホームページ、ドキュメントサイト、デモ、パッケージレジストリ）、参考資料、関連プロジェクト、謝辞、ライセンス、コントリビューションの案内。CLI コマンド、just レシピ、スクリプト、プロジェクト構成ツリーは含めません。これらは同じ場所にある AGENTS.md が管理し、README からリンクします。

入力：既存の各 README.md、名前／バージョン／説明／ライセンス／ホームページ URL の情報を得るための最も近い上位のマニフェスト、リポジトリ URL を得るための git リモート。出力：書き換えられた README.md ファイル。

認識されるフラグ：path、--root-only、--dry-run、--preserve、--minimal、--thorough（別名 --full）。

references/update-readme.md を参照してください。

README の初期化

使用する場面：リポジトリ内（またはパッケージのルート）に README.md がない場合に、ユーザーが README.md を新規作成するよう依頼したときです。トリガーとなるフレーズには、「init README」、「create README」、「new README」、「generate a README」などがあります。

README.md がない各パッケージルート（リポジトリのルートと、マニフェストを含むディレクトリ。再帰的な検出を参照）に README.md を作成します。--force または AskUserQuestion による明示的な確認がない限り、既存の README.md は上書きしません。次の 2 つの動作モードに対応しています。

• 自動推論：プロジェクトの分析のみから内容を導き出します。
• ガイド付き：ユーザーが提示した説明（例：「依存関係なしの日付解析用 TypeScript ライブラリ」）を中心に内容を作成します。ガイド付きの説明はルートのファイルに適用され、ネストされたパッケージのファイルは各自のマニフェストから推論します。

対象読者のルールは Update README と同じです。人間のみを対象とし、CLI は対象外です。

入力：パッケージルートごとのコードベース分析（言語、フレームワーク、LICENSE、ホームページ URL、リポジトリ内の引用または論文）と、任意のユーザー提供の説明。出力：対象となる各パッケージルートに新しい README.md を作成します。

認識されるフラグ：path、--root-only、--dry-run、--minimal、--full、--force。

references/init-readme.md を参照してください。

コンテキストの初期化

使用する場面：リポジトリ内（またはパッケージのルート）にコンテキスト文書がない場合に、ユーザーが新しい AGENTS.md ファイル（および CLAUDE.md シンボリックリンク）の作成を依頼したときです。トリガーとなるフレーズには、「init AGENTS.md」、「create CLAUDE.md」、「init context」、「new context file」、「generate AGENTS.md」などがあります。

AGENTS.md がない各パッケージルート（再帰的な検出を参照）に AGENTS.md を作成します。README の初期化と同様に、自動推論とガイド付きモード（例：「セキュリティを最優先する Foundry スマートコントラクトプロジェクト」）に対応しています。生成する各ファイルについて、そのディレクトリで ln -sf AGENTS.md CLAUDE.md を実行し、同じ階層に CLAUDE.md シンボリックリンクを必ず作成します。

生成する各 AGENTS.md には、開発者またはエージェントがそのパッケージで必要とするすべての CLI 呼び出しをまとめた Commands セクションを含める必要があります。これには、インストール、開発、ビルド、テスト、リント、フォーマット、デプロイに加え、そのディレクトリで検出されたすべての just レシピ、npm/pnpm/yarn/bun スクリプト、Makefile ターゲットが含まれます。

入力：パッケージルートごとのコードベース分析（スタック、スクリプト、justfile、Makefile、アーキテクチャに関するヒント、最も近い package.json、README.md、言語固有のマニフェスト）と、任意のユーザー提供の説明。出力：新しい AGENTS.md ファイルと、それぞれに対応する同じ階層の CLAUDE.md シンボリックリンクを作成します。

認識されるフラグ：path、--root-only、--dry-run、--minimal、--full、--force。

references/init-agents.md を参照してください。

レポート

すべてのワークフローの最後に、短い概要を記載します。すべてのワークフローで、次の表記を使用してください。

• ✓ 成功した操作：「✓ Updated AGENTS.md」に続けて、具体的な変更を箇条書きでインデントして記載します。
• ⊘ スキップした任意のファイル。
• ⚠ 注意事項（例：CONTRIBUTING.md のマージ推奨）。
• ✗ 失敗：「✗ Failed to write README.md」と、原因を 1 行で記載します。

各行の下に変更の詳細をインデントして記載し、ユーザーが見出しを読み直さなくても、単一ファイルの差分を確認できるようにします。再帰的な実行では、ファイルパスごとに結果をまとめ（リポジトリのルートからの相対パスを小見出しとして使用）、最後に件数の概要を 1 行で記載します（例：「4 ファイルを更新、1 ファイルをスキップ、注意事項 1 件」）。--dry-run の場合は、「Planned Changes」という見出しをレポートの先頭に付け、対象パスをすべて列挙し、確認メッセージの代わりに差分または内容案のプレビューを含めます。レポートのテンプレート全体については、references/common-patterns.md を参照してください。

追加リソース

詳細なワークフロー、例、実装ガイダンスについては、以下の参考ドキュメントをご覧ください。

• references/common-patterns.md — 対象読者の分類、引数の解析、文体、レポートの書式設定、ファイルの検出、メタデータの抽出、CONTRIBUTING.md の統合に関する推奨事項
• references/update-agents.md — 検証戦略、コマンドの特定、差異の検出を含む、コンテキストファイルの完全な更新ワークフロー
• references/update-readme.md — 人間向けコンテンツを対象とした README の完全な更新ワークフロー
• references/init-readme.md — 人間向けコンテンツを対象とした README の完全な初期化ワークフロー
• references/init-agents.md — 言語別テンプレートやコマンドの統合を含む、コンテキストの完全な初期化ワークフロー

これらの参考資料では、各ワークフローの実装の詳細、コード例、トラブルシューティングのガイダンスを紹介しています。