readme-creator

README クリエイター

README はウィキではなく、店頭のショーウィンドウのように読める内容にします。

• 対象: プロジェクトの利用を検討している人に向けて README.md を作成または書き直します。どの機能セクションを掲載するかはプロジェクトの種類に基づいて決め、画像やバッジの選択はファイルの表示先（GitHub のみか、レジストリページにも表示するか）に基づいて決めます。
• 対象外: プロジェクトの説明をすでに網羅している README の文章を磨くことや、複数ページのドキュメントサイト（docs-writing を使用）、AGENTS.md や CLAUDE.md などのエージェント向け指示ファイル（agents-md を使用）、README に記載されているインストールや初回実行の体験を改善すること（dx-audit を使用）、ランディングページ用のマーケティングコピー（copywriting を使用）は対象外です。

読者

検索結果、レジストリの掲載ページ、またはプロフィールページからたどり着いた人です。使える時間は約15秒で、知りたいことはただ一つです。自分の時間を使う価値があるかどうか。すべての行はその疑問に答えるものでなければならず、そうでなければ削除します。

読者はコントリビューターではありません。ビルドパイプライン、ワークスペースの構成、リリースプロセス、コーディング規約は、利用するかどうかの判断材料にならないため、ここには記載しません。

これは、## Contributing を必須とし、100行を超えると目次を追加し、短すぎるより長すぎるほうがよいとする standard-readme や Make a README とは、意図的に異なります。そうした標準に戻らないでください。コントリビューター向けの内容は CONTRIBUTING.md または AGENTS.md に移し、長さは読者が必要とする内容に合わせます。

参照ファイル

ファイル	読むタイミング
references/section-templates.md	フェーズ3：各骨格セクションのマークアップ、機能セクションの選択肢、種類別の注意事項
references/badges-and-shields.md	フェーズ4：フェーズ1でレジストリへの掲載（npm、crates.io、PyPI、VS Code Marketplace、skills.sh）が確認できた場合に限り読む
references/quality-checklist.md	フェーズ5：完了とする前に採点する

文体

下書きを作成する前に、外部の ghostwriter スキルのプロファイルを確認してください。場所は ${GHOSTWRITER_HOME:-~/.config/ghostwriter}/readme.md です。プロファイルがある場合は、文体、表記規則、プロジェクト固有のマークアップ（ヘッダーブロック、バッジの色、フッターのクレジット）をそれに従い、このスキルと矛盾する場合もプロファイルを優先します。内容をここで繰り返さず、プロファイルに従ってください。

プロファイルがない場合は、簡潔な二人称の命令形を使い、絵文字や感嘆符は避け、形容詞より具体的な数字を優先します。

ワークフロー

進捗を追跡するため、このチェックリストをコピーしてください。

README progress:
- [ ] Phase 1: Detect project type and where the README renders
- [ ] Phase 2: Fix the spine, then choose capability sections
- [ ] Phase 3: Write each section from the template
- [ ] Phase 4: Add badges (registry-listed projects only)
- [ ] Phase 5: Score against the checklist; report the pass count and render-check output

フェーズ 1：プロジェクトの種類と表示先を特定する

マニフェスト（package.json、Cargo.toml、pyproject.toml、go.mod）を読み、名前、説明、ライセンス、スクリプト、bin、"private"、repositoryを確認します。書き換える場合は既存のREADMEも読みます。トップレベルの構成も確認します。

種類を必ず1つに分類します。上から順に確認し、最初に一致した行を採用します。

種類	決め手となる特徴
スキルバンドル	SKILL.mdファイルを含むskills/ディレクトリ
モノレポ	ワークスペース設定（turbo.json、pnpm-workspace.yaml、workspaces）
CLIツール	binフィールド、src/cli.*、またはcommander/yargs/clapの依存関係
フレームワーク	プラグイン／ミドルウェアアーキテクチャ、設定API、ドキュメント化された拡張ポイント
ライブラリ／パッケージ	main／exportsが設定され、binがなく、src/index.*がエントリーポイント
Webアプリ	フレームワーク設定（next.config.*、vite.config.*）があり、公開されていない

READMEの観点では、モノレポはプロジェクトの種類ではありません。 これは配布方法です。初めて訪れた人が何をインストールするのか、または何にアクセスするのかを確認し、それに合わせてREADMEを書きます。たとえば、apps/cliをnpmで公開するリポジトリなら、ルートのREADMEはワークスペース一覧ではなくCLIのREADMEにします。ワークスペースの構成はAGENTS.mdに記載します。

それでも2つの種類に当てはまる場合（APIも公開するCLI、ライブラリとして公開されるフレームワークなど）は、最も多くのユーザーが利用する方法に合わせて選び、もう一方の役割は追加のセクション1つにまとめます。

次に、ファイルが表示される場所を記録します。"private": trueのマニフェスト、またはレジストリへの掲載がない場合は、GitHubだけで表示されます。公開パッケージはnpmjs.com、PyPI、crates.ioにも表示されるため、画像URLを変更し、バッジを付けます（フェーズ4と「注意点」を参照）。

コードからは分からないことだけをユーザーに尋ねます。

• これはどのような問題を解決するのか（タグラインの背景にある「理由」）。
• 必ず含めたいセクション、または省きたいセクションはあるか。

連絡が取れない場合は、マニフェストとコードから「理由」を推測し、要約にその前提を記載して、作業を止めずに進めます。

フェーズ 2：基本構成を整えてから、機能セクションを選ぶ

該当する場合は、次の基本構成を使用します。ホスト型アプリでは、インストールコマンドの代わりに公開URLを先頭にできます。ブラウザーで利用する製品のインストール方法を作り上げてはいけません。

1. ヘッダーブロック（タイトル、タグライン、2行目のテキスト、レジストリ掲載済みの場合はバッジ）
2. ## Demo（公開URLがある場合のみ）
3. ## Install
4. ## Quickstart
5. ## License

QuickstartとLicenseの間に機能セクションを配置します。references/section-templates.mdの候補から2～4つ選びます。5つ目のセクションを設けるのは、ほとんどの場合、読者向けの見出しを付けたコントリビューター向けの内容を追加することになります。5つ目が本当に読者の役に立つ場合は、黙って追加せず、要約でその理由を説明します。

見出し名を統一すると、リポジトリ間で一貫性を保てます。Install、Quickstart、Demo、Licenseを使用します。Installation、Getting Started、Quick start、Quick Start、Licenceは使用しません。文頭のみ大文字に統一し、## Browser supportのようにします。## Browser Supportとはしません。

対象読者の基準。 セクションを書く前に、それがプロジェクトの利用を検討している人に役立つのか、それともプロジェクトを変更する人だけに役立つのかを確認します。コントリビューター向けの内容はCONTRIBUTING.mdまたはAGENTS.mdに記載します（配置先の一覧はreferences/section-templates.mdにあります）。READMEには、せいぜい1行の案内だけを残します。配置先のファイルがない場合は作成します。重要なセットアップ情報を削除するより、READMEが少し長くなるほうがよい結果です。

フェーズ 3：セクションを作成する

references/section-templates.md から各セクションのひな形をコピーして内容を記入し、ファイル末尾にあるタイプ別の注意事項を適用します。以下のルールはすべてのタイプに共通です。

• タイトルは、スペースと大文字を使った表示名にし（react-vello ではなく「React Vello」）、実際のサイトがある場合はそこにリンクします。
• タグラインは見出しを付けずに直下に置き、8〜16語程度で、プロジェクトが何であるかではなく、何をするのかを説明します。プロジェクト名から始めると、H1で読んだばかりの名前に読者の最初の3語を費やすことになります。
• 2行目には、それを使って実際に何をするのかを、一文で平易に記載します。
• インストールには、マニフェストの name フィールドから取得した、最も手早く実行できるコマンドを1つだけ記載します（名前変更前の可能性がある古いREADMEから取得してはいけません）。npm、pnpm、yarn、bunを4つのタブで並べるのではなく、コマンドは1つにします。別のパッケージマネージャーを使いたい人は、npm install を読み替えられます。
• クイックスタートには、目に見える出力を生成する、最短かつ完全なものを記載します。ファイル内で最も長いブロックになったとしても、全体の長さを削ってはいけません。途中で切れた例は、読者が貼り付けた後に初めて失敗するためです。
• すべてのコードブロックは、コピー＆ペーストするだけでそのまま実行できるものにします。擬似コード、プレースホルダーのインポート、foo、bar、my-app、your-name-here は使わないでください。実際のポート番号、ブランチ名、16進数の色を使います。
• 長さは必要性に応じて決めます。大半は40〜90行に収まります。実際のフラグ一覧表があるCLIなら120行でも妥当です。約130行を超える場合は、ドキュメントサイトまたは docs/ フォルダーに移し、READMEからリンクします。
• セクション見出しには ## を使います。CLIのインストール方法など、1つのセクション内で本当に並列なバリエーションを分ける必要がある場合に限り、### を使います。

フェーズ 4：バッジを追加する

フェーズ1でレジストリへの掲載が確認できた場合を除き、バッジは追加しません。未公開アプリや内部モノレポでは、バッジ行なしのヘッダーブロックを使います。レジストリにはスキルバンドル向けのskills.shも含まれ、インストール数バッジのエンドポイントを提供しています。リポジトリ自身のREADMEでもこれを使っています。

バッジを使う場合は、references/badges-and-shields.md を読み込みます。デフォルトでは、バージョンとライセンスの2つ（スキルバンドルではインストール数とライセンス）を、1つのスタイルと1つの配色で使います。そうすることで、複数のリポジトリを一連のものとして見せられます。実行されないワークフローを参照するCIバッジは恒久的な失敗として表示され、スターのバッジはページ内にすでにある数字を繰り返すだけです。

フェーズ 5：検証する

references/quality-checklist.md を使って、利用者の視点での手順とプロジェクトの慣例を確認します。実行可能な例とリンク／表示結果を報告してください。自己採点は、表示確認の証拠にはなりません。

合格数と合わせて、以下の表示チェック結果を添付してください。いずれも何も返さない必要があります。

grep -nE "TODO|\{\{" README.md                                      # review candidates, not automatic failures
perl -CSD -ne 'print "$.: $_" if /\x{2014}/' README.md                  # em dashes
grep -nE "^## (Installation|Getting Started|Quick Start|Licence|Development|Tech Stack|Contributing)" README.md
grep -nE '(src|\]\()=?"?\.?/?\.github/assets' README.md                  # relative image paths: fine on GitHub, broken on npm and PyPI, so must be empty for a published package

チェックリストの「自動不合格」リストは必須条件です。説明の欠落、インストール方法の欠落、ひな形の残存、実行できないコード例、コントリビューター向けにしか役立たないセクションのいずれかがあれば、スコアにかかわらず未完了です。

公開済みパッケージのREADMEを書き換える場合は、npmjs.comとPyPIには最後のリリース時点のREADMEが表示され、ページが更新されるのは次のリリース後であることを、概要に記載してください。

注意点

• <div align="center"> 内の空行は重要です。CommonMark では <div> は次の空行まで続く HTML ブロックとして扱われるため、タグの直後の行にある # Title は、文字どおり # Title と表示されます。<p align="center"> のバッジ行と閉じタグ </div> も同様です。
• 相対画像パス（.github/assets/demo.png）は GitHub では表示されますが、リポジトリ外の README を配信する npmjs.com や PyPI では 404 になります。公開パッケージの場合は、src に https://raw.githubusercontent.com/{owner}/{repo}/main/.github/assets/demo.png を指定してください。ファイルは引き続きリポジトリ内に置きます。
• リポジトリ外の画像ホストは、いつ利用できなくなるかわかりません。GitHub は外部画像をすべて camo 経由でプロキシするため、現在は http:// の URL も読み込めますが、ホストがなくなるとスクリーンショットも表示されなくなります。画像は .github/assets/ にコミットしてください。
• ダーク／ライト用ロゴには、2 行の <source media="(prefers-color-scheme: ...)"> とフォールバック用の <img> を含む <picture> を使います。#gh-dark-mode-only URL フラグメントは非推奨です。PyPI は <source> を削除してフォールバックだけを表示するため、フォールバックにはライト版を指定してください。
• > [!NOTE] アラート（TIP、IMPORTANT、WARNING、CAUTION も同様）は GitHub、npmjs.com、crates.io で表示されます。PyPI では、グレーの引用ブロック内に [!NOTE] がそのまま表示されます。README で使うのは最大 1 つにし、インストールを妨げる問題に限って使ってください。コールアウトだらけの README は変更履歴のように見えます。
• https://img.shields.io/github/license/{owner}/{repo} は、リポジトリで検出されたライセンスを読み取ります。LICENSE ファイルがない場合は license: not identified と表示され、バッジがないよりも悪い状態になります。バッジを追加する前に、ファイルが存在することを確認してください。
• 書き換えで最もよくある失敗は、メンテナー向けに書かれた README を公開パッケージに使ってしまうことです。最初の見出しが ## Workspaces だったり、インストール手順が git clone だったりするのがその兆候です。解決策は削ることではなく、別の読者に向けて書くことです。
• Getting Started に git clone があるライブラリの README や、レジストリのバッジがあるアプリの README は、Phase 1 で種類を誤って判断したため、読者を行き止まりに導きます。文章を編集する前に分類し直してください。
• インストール行に記載する名前でパッケージが公開されていることを確認してください：npm view {{name}} version（または cargo search、pip index versions）。未公開または改名済みのパッケージを案内する README は、読者を最初の行でつまずかせます。
• 複数のリポジトリを一度に書き換えると、インストールコマンドを推測したくなります。それぞれのコマンドの根拠となるマニフェストの bin エントリまたはスクリプトを示し、サンプルを貼り付けてテストしてください。
• デフォルトのスキャフォールド README（create-next-app、create-vite）は絶対にそのまま公開しないでください。全面的に置き換えてください。読者は放置されたプロジェクトだと受け取ります。
• 機能の箇条書きには、コロンを使った - **Name:** what it does. の形式を使います。スペースを挟んだハイフン（- **Name** - what it does.）は、エムダッシュの代用に見え、スタイルガイドにも反します。
• キャッチフレーズを言い換えただけの ## Features セクションはノイズです。読者が得られる内容に合わせて見出しを付けてください（## Modes、## What you can do、## Keyboard shortcuts など）。そうすれば、各箇条書きに新たな機能を加える必要があります。

関連スキル

場合	実行するもの
README があり、文章の監査またはドキュメントサイト全体の見直しが必要な場合	docs-writing
エージェント向けの指示（AGENTS.md、CLAUDE.md）が必要な場合。対象読者の判定によって移動された内容も含みます	agents-md
README に記載されたインストール手順または初回実行手順自体に問題がある場合	dx-audit
キャッチフレーズを超えるランディングページやマーケティング用のコピー	copywriting
ユーザー自身の声で草稿を作成する場合	インストールされている外部の ghostwriter スキル、またはプラットフォームの readme

メンテナンスのみ：evals/evals.json には、このスキルへの変更に対する回帰シナリオが含まれています。ユーザーのタスク中には読み込まれません。