Markdown ドキュメント管理

概要

Claude Code ワークフロー用のプロジェクトドキュメント（README.md とエージェント文脈ファイル AGENTS.md / CLAUDE.md）を管理します。このスキルは厳密なオーディエンス分離を強制します：README.md は人間向け、AGENTS.md はエージェントとコマンド実行開発者向け。新規プロジェクトの初期化、既存ドキュメントの更新、または文脈ファイルが現在のコードを正確に反映していることの確認が必要な場合に使用します。

このスキルは盲目的な生成よりも検証と妥当性確認を重視します。ドキュメント作成や更新前に、実際のコードベース構造、ファイル内容、パターンを分析してください。生成されるすべてのコンテンツは簡潔で命令的であり、冗長またはチュートリアル風ではなく専門家向けであるべきです。

オーディエンス分離

これはこのスキルが生成するあらゆるもの中心となるルールです。

ファイル	オーディエンス	含む内容	除外する内容
README.md	リポジトリを閲覧する人間（GitHub、npm等）	説明、バッジ、ドキュメント/サイト/デモへのリンク、参考資料、論文、関連作品、謝辞、ライセンス、貢献への指針	CLIコマンド、justレシピ、パッケージスクリプト、ビルド/テスト/lint ワークフロー、プロジェクト構造ツリー、API リファレンス
AGENTS.md（および CLAUDE.md シンリンク）	リポジトリで作業する AI エージェントと開発者	スタック、すべての CLI コマンド（install、dev、build、test、lint、deploy）、justレシピ、package.jsonスクリプト、Makefileターゲット、コードスタイル、アーキテクチャ、規約、貢献ワークフロー	マーケティングコピー、バッジ、開発に無関連な外部リンク

迷った場合は問い自分：GitHub でこれを読む人間がケアするか、それともコマンド実行する開発者/エージェントだけがケアするか？ 後者の場合は 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 を更新」）が可能です。ユーザーがリストした順序で順次実行し、各結果を独立して報告します。

CONTRIBUTING.md ポリシー

このスキルは CONTRIBUTING.md を保守しません。ワークフローが repo ルートで CONTRIBUTING.md を検出した場合：

1. そのワークフロー用に他に何かを書く前に停止します。
2. ユーザーにその内容を AGENTS.md にマージすることをお勧めします（AGENTS.md が開発ワークフロー、ブランチ規約、レビュープロセス、ツール参照を所有しているため）。
3. マージ後に AGENTS.md をエージェント文脈ファイルの唯一の情報源にするため CONTRIBUTING.md を削除することを提案します。
4. 自動マージまたは自動削除は行いません。ユーザーがマージを実行します。

標準サマリー形式で推奨事項を報告し、ユーザーがリクエストした README/AGENTS ワークフローを続行します。CONTRIBUTING.md ファイルは無視します。

前提条件

ドキュメントワークフローを使用する前に、基本的なプロジェクト構造を確認してください：

git rev-parse --git-dir

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

更新ワークフロー向けに、対象ファイルの存在を確認します：

ls -la CLAUDE.md AGENTS.md README.md CONTRIBUTING.md

更新を試みる前にどのファイルが存在するかを確認してください。見つからないファイルはエラーを表示し、何の初期化が必要かを識別するのに役立ちます。CONTRIBUTING.md が表示される場合は、続行前にポリシーを適用します。

モノレポ向けには、ワーキングディレクトリも確認します：

git rev-parse --show-toplevel

すべてのワークフローは repo ルートのファイルで動作します。サブパッケージ内のネストされた README/AGENTS ファイルではありません。特定のパッケージをドキュメント化するには、ユーザーがまずそのパッケージディレクトリに cd する必要があります。

共通引数

これらのフラグはすべてのワークフロー間で一貫して解釈されます。各リファレンスはワークフロー別の効果を詳細に説明しています。references/common-patterns.md で共有解析規約を参照してください。

• --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 で確認しない限り、既存の対象を上書きすることを拒否します。
• repository ルート（git rev-parse --show-toplevel）でのみ動作します。モノレポサブパッケージの場合、ユーザーはスキルを呼び出す前にそのパッケージディレクトリに cd する必要があります。
• 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 が所有：スタック、すべての CLI コマンド（install、dev、build、test、lint、deploy）、justレシピ、package.jsonスクリプト、Makefileターゲット、コードスタイル、アーキテクチャ、規約、貢献ワークフロー。

入力：既存の AGENTS.md（必須）、パッケージマニフェスト、ロックファイル、スクリプト、justfile、Makefile。出力：改訂 AGENTS.md、リフレッシュ CLAUDE.md シンリンク。

認識フラグ：--dry-run、--preserve、--thorough、--minimal。

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

README を更新

使用時期：ユーザーが既存の README.md を更新またはリフレッシュしたい場合。トリガーフレーズには「update README」、「refresh README」、「fix README」、「regenerate README」が含まれます。

README.md が存在しない場合は、代わりにREADME を初期化にルーティングします（または --force で update-readme に作成させます）。

README が所有：説明、バッジ、リンク（ホームページ、ドキュメントサイト、デモ、パッケージレジストリ）、参考資料、関連作品、謝辞、ライセンス、貢献への指針。CLI コマンド、justレシピ、スクリプト、またはプロジェクト構造ツリーは含みません。それらは AGENTS.md に存在し、README はそれら向けに AGENTS.md にリンクします。

入力：repo ルート（git rev-parse --show-toplevel）の既存 README.md。パッケージマニフェスト（名前/バージョン/説明/ライセンス/ホームページ URL）。リポジトリ URL 向けの git リモート。出力：改訂 README.md。

認識フラグ：--dry-run、--preserve、--minimal、--thorough（別名 --full）。

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

README を初期化

使用時期：ユーザーが README.md のないリポジトリで新しい README.md を最初から作成したい場合。トリガーフレーズには「init README」、「create README」、「new README」、「generate a README」が含まれます。

--force または AskUserQuestion で明示的な確認なしに既存の README.md を上書きすることを拒否します。2 つの動作モードをサポート：

• 自動推論：プロジェクト分析から完全にコンテンツを導出します。
• ガイド付き：ユーザー提供の説明（例：「ゼロ依存関係で日付を解析する TypeScript ライブラリ」）を中心にコンテンツに焦点を当てます。

README を更新するのと同じオーディエンスルール：人間のみ、CLI なし。

入力：コードベース分析（言語、フレームワーク、LICENSE、ホームページ URL、repo 内の引用または論文）、オプションのユーザー提供説明。出力：repo ルートの新しい README.md。

認識フラグ：--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」が含まれます。

README を初期化のように、自動推論とガイド付きモード（例：「セキュリティ第一のマインドセットの Foundry スマートコントラクトプロジェクト」）をサポートします。完了時に常に ln -sf AGENTS.md CLAUDE.md 経由で CLAUDE.md シンリンクを作成します。

生成された AGENTS.md は、開発者またはエージェントが必要とするすべての CLI 呼び出しを統合する Commands セクションを含む必要があります：install、dev、build、test、lint、format、deploy、plus repo で検出されたすべての justレシピ、npm/pnpm/yarn/bun スクリプト、Makefile ターゲット。

入力：コードベース分析（スタック、スクリプト、justfile、Makefile、アーキテクチャヒント、既存 package.json、README.md、言語固有マニフェスト）、オプションのユーザー提供説明。出力：新しい AGENTS.md、CLAUDE.md シンリンク。

認識フラグ：--dry-run、--minimal、--full、--force。

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

報告

すべてのワークフローは短いサマリーで終わります。すべてのワークフロー間でこれらの規約を使用：

• ✓ 成功した操作向け：✓ Updated AGENTS.md の後にインデントされた箇条書きで具体的な変更がリストアップされます。
• ⊘ スキップされたオプションファイル向け。
• ⚠ 勧告通知向け（例：CONTRIBUTING.md マージ推奨事項）。
• ✗ 失敗向け：✗ Failed to write README.md 1 行の原因付き。

各行の下の詳細変更をインデント化して、ユーザーがヘッダーを再読込することなく単一ファイルのデルタをスキャンできるようにします。--dry-run の場合、レポートの前に「Planned Changes」ヘッダーを付けて、確認ではなく diff または提案コンテンツプレビューを含めます。完全なレポートテンプレートは 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 — 言語固有テンプレートとコマンド統合を含む完全な文脈初期化ワークフロー

これらのリファレンスはワークフロータイプごとに実装詳細、コード例、トラブルシューティングガイダンスを提供します。