readme-generator

GitHub README ジェネレーター

README は、プロジェクトの最初のポートフォリオページです。説明書の目次でも、機能一覧を詰め込む場所でもありません。短時間で次の3つに答える必要があります。

1. これは何か。
2. なぜ見る価値があるのか。
3. どうすれば使い始められるのか。

この Skill の目標は、100 点の README 作品を作ることです。明快で、審美性があり、簡潔で、信頼でき、プロジェクトをひとつの完成した作品として理解してもらえるものです。

---

第一原理

README は信頼への入口であり、次の行動への入口です。完全なドキュメントではありません。初めてリポジトリを開いた人が、すばやく判断できるようにするものです。

1. このプロジェクトは何の問題を解決するのか。
2. 自分に適しているか。
3. すぐに実行、インストール、または詳細の確認ができるか。

スター数が 1 万を超えるオープンソースプロジェクトは、通常、情報量ではなく、わかりやすいファーストビュー、すぐに始められる導線、信頼できるドキュメントへの入口、そして簡潔なコミュニティ情報で支持されています。画像、バッジ、作者情報、設計理念はあくまで補助です。理解を妨げるなら、それはノイズです。

この Skill の基本方針は、まずプロジェクトを明確に伝え、その後で見栄えを整えることです。ビジュアルは理解を助けるものであり、理解の代わりにはなりません。

---

作品の基準

以下の採点表を使って、すべての出力を評価してください。

項目	点数	判断基準
15 秒で理解できる	25	ファーストビューでプロジェクト名、価値、対象者がわかる
プロジェクトのストーリー	20	機能を並べるのではなく、背景、動機、成果が明確に伝わる
ビジュアル表現	20	画像が作品らしく、小さな文字の入った手順画面のように見えない
すぐに始められる	15	インストールと使用への道筋が短く、明確で、そのまま実行できる
信頼できる成果物	10	実際の出力、機能の範囲、または結果が示されている
簡潔でノイズがない	10	重複、スローガン、過剰な説明、装飾を取り除いている

90 点未満の README は納品しません。まずノイズを削り、重要な点を際立たせ、ストーリーの順序を整えてください。

人気プロジェクトを参考にする基準

人気のあるオープンソースプロジェクトの構成を、次のような点で参考にしてください。

• プロジェクト名と、一文の価値提案。
• 必要最小限のバッジ。状態を示す装飾を並べすぎない。
• 「すぐに始める」またはドキュメントへの入口を上部に配置する。
• 例は、導入の手間を減らせる場合にのみ掲載する。
• コントリビューション、コミュニティ、セキュリティ、ライセンスの情報は簡潔にわかりやすくする。
• UI／プロダクトのプロジェクトにはスクリーンショットを掲載できます。ライブラリ、SDK、インフラのプロジェクトでは、画像を減らすか、掲載しません。

README を設計宣言、完全な説明書、機能の羅列、ソーシャルプロフィール、社内ワークフローの報告書にしないでください。

---

設計原則

必ず守ること

• H1 にはプロジェクトの正式名称を使い、その直後に一文の価値提案を置きます。
• README の冒頭では、インストール方法より先にプロジェクトの価値を伝えます。
• 画像では要点をひとつだけ表現します。ただし、プロジェクトの名刺としての役割を持たせ、読者が一目でプロジェクト名と位置づけを把握できるようにします。
• 画像は原則として最大 2 枚にします。表紙 1 枚と、主要な機能または結果を示す画像 1 枚です。
• GitHub では画像が縮小表示されるため、画像内のメインコピーはポスターの文字サイズを基準に設計します。
• 機能の説明は具体的にしますが、誇張しません。結果で説明できる場合は、自画自賛を避けます。
• 作者やライセンスの情報は簡潔にし、ソーシャルプロフィールのように盛り込みすぎません。

必ず避けること

• ASCII アートのタイトル。
• タイトルや作者一覧表を絵文字で装飾すること。
• 「私たちは非常に優れています」といった中身のない長文。
• 小さなカードを 6 個以上、1 枚の画像に詰め込むこと。
• フローチャートに段階、コマンド、小さな説明文を詰め込むこと。
• 3 枚目のフローチャートを標準の成果物にすること。作業方法は通常、本文で説明するほうがわかりやすくなります。
• Image Gen を長文のレイアウトツールとして使うこと。
• README を完全な製品マニュアルにすること。詳細なドキュメントは docs/ に配置します。

---

全体の流れ

Phase 0    项目阅读和模式识别
Phase 1    项目故事提炼
Phase 2    视觉生成方式选择
Phase 3    作品级视觉资产生成
Phase 4    README 组装
Phase 5    GitHub 元信息建议
Phase 6    验证和交付

---

Phase 0: プロジェクトの調査とパターンの判定

すぐにテンプレートを書くのではなく、まずプロジェクトを調査します。

確認項目：

ls
find . -maxdepth 2 -type f | sed 's#^\./##' | sort | head -80

優先して確認するファイルやディレクトリ：

• README.md
• package.json / pyproject.toml / go.mod / Cargo.toml
• docs/
• 主なエントリーファイル
• サンプル、スクリーンショット、デモファイル

プロジェクトの種類とビジュアルの予算を判断します。

ケース	判断基準	方針	画像の上限
README の新規作成	README がない、またはごく短い	全体を作成するが、導線は短く保つ	1-2
README の改善	既存の README に有効な内容がある	独自の内容を残し、構成とファーストビューを書き直す	0-2
ポートフォリオとしての強化	ユーザーが審美性、ストーリー、見せ方を重視している	ストーリーと表紙の表現を優先する	2
ドキュメント重視モード	SDK、ライブラリ、バックエンドツール、インフラ	画像を減らし、インストール、API、ドキュメントへの入口を重視する	0-1
UI／プロダクトの紹介	UI、スクリーンショット、デモ、視覚的な成果がある	実際の成果や表紙を使って理解を助ける	1-2

既存の README を改善するときは、ユーザーがすでに用意した重要な内容を削除しないでください。まず残すべき内容を抽出し、その後で構成を組み直します。

ノイズの確認

README を書く前に、別の場所に移すか削除する内容を洗い出します。

内容	標準の対応
設計の採点表、作業原則、内部の方法論	SKILL.md または docs/ に置き、README には含めない
生成ファイルツリー、テンプレート変数、スクリプトの詳細	ユーザーが開発者向けドキュメントを必要とする場合のみ残す
3 枚目のフローチャート	削除し、本文 2～4 行か短いリストに置き換える
多すぎるソーシャルリンク	GitHub やホームページなど、主要な入口だけを残す
抽象的すぎる機能一覧	成果に結びつく 3 つの機能にまとめる
インストール前の長い背景説明	短くし、「すぐに始める」を前に出す

---

Phase 1: プロジェクトのストーリーをまとめる

次の 7 つの項目を収集または推測します。

項目	説明
project_name	プロジェクトの正式名称
tagline	短く、明確な判断が示された一文の価値提案
origin	プロジェクトが生まれた背景と、その必要性
audience	想定する利用者
promise	ユーザーが得られる結果
proof	実際の機能、スクリーンショット、出力、例、指標
start	最短の導入手順

質問をしすぎないでください。プロジェクトから推測できることはそのまま判断します。ストーリーの正確さに影響する場合に限り、ユーザーに質問します。

推奨するストーリー構成

项目名
一句话价值主张
视觉封面（按项目类型决定是否需要）

这是什么
为什么需要它
你会得到什么
快速开始
示例或输出
工作方式（正文，不默认配图）
安装
许可证
作者

ツール、ライブラリ、インフラ寄りのプロジェクトでは、「すぐに始める」を「なぜ必要なのか」の直後に移動します。README の順序は読者の行動を支えるものであり、テンプレートを完全に埋めるためのものではありません。

---

Phase 2: ビジュアルの生成方法を選択する

README の画像には、次の 2 種類があります。

1. 作品の表紙：雰囲気、テーマ、印象に残る要素を伝えます。
2. 構造の説明図：手順、機能、比較、ワークフローを伝えます。

ユーザーの意図に応じてモードを選択します。

モード	適用するケース	画像の方針
portfolio	標準の推奨モード。作品としての完成度を見せたいプロジェクトに適しています	表紙 1 枚 + 主要機能の画像 1 枚
clean-doc	SDK、ライブラリ、バックエンドツール、堅牢性が重視されるインフラ	画像は 0～1 枚とし、「すぐに始める」と例を優先する
visual-story	AI ツール、デザインツール、個人開発のプロダクト、作品紹介	画像は最大 2 枚。印象に残る要素は Codex Image Gen で作成する
structured	ユーザーがインフォグラフィック、比較図、フローチャートを明確に求めている	文字の正確性を保った HTML/CSS のポスターを 1～2 枚作成する

まずプロジェクトの種類を判断し、無理に portfolio を当てはめないでください。ビジュアル素材の生成方法は、次の優先順位に従います。

1. Codex Image Gen Skill：ビジュアル素材の生成には、Codex に組み込まれた画像生成機能を優先して使用します。
2. 軽量化：README に掲載する画像は、まず WebP に変換してから README に参照パスを記述します。
3. HTML to PNG fallback：Image Gen が利用できない場合、出力が要件を満たさない場合、またはユーザーが正確に構成されたテキストを明示的に求めている場合に限り、HTML/CSS テンプレートのスクリーンショットに切り替えます。

HTML のスクリーンショットを標準の方法にしないでください。信頼できる代替手段ですが、最初に選ぶ方法ではありません。

---

Phase 3: 作品としてのビジュアル素材を作成する

標準では、次の 2 つの固定ファイル名を使用します。

assets/banner.webp
assets/features.webp

こうすることで、画像が Codex Image Gen で作成された場合でも、HTML のスクリーンショットを代替手段として使った場合でも、README の参照パスを固定できます。

画像の役割

画像	目標	推奨する方法
banner.webp	プロジェクトの名刺として、プロジェクト名、位置づけ、印象に残る要素を伝える	Codex Image Gen を優先
features.webp	主要機能、成果、または必要なワークフローを伝える	Codex Image Gen を優先。文字の正確性が重要な場合は HTML を代替手段として使う

workflow.png や workflow.webp を標準で生成しないでください。ユーザーがフローチャートを明確に求める場合は、その内容を features.webp に統合するか、本文に記載し、3 枚目の画像は追加しません。

標準のビジュアルスタイル

すべての README 用ビジュアル素材で、次のスタイルを標準とします。

黑底、极简、电影打光、高对比、大留白、低亮度、白/灰/暖金三色、高级杂志封面感。
画面质感：极深黑背景 #050505，纸张颗粒，浅景深，体积雾，细窄轮廓光，局部金属质感。
质量目标：出自 1w star 设计师水准作品。

デザイン上の制約：

• 背景は #050505 のような深い黒を基本にします。
• 色は白、グレー、暖色系のゴールドのみを使います。虹色のグラデーション、紫や青のネオン、高彩度の装飾色は使いません。
• 要素を詰め込まず、余白を大きく取り、部分的な光を使います。
• 画像内の文字は、伝える価値の高いものに絞り、プロジェクトの紹介と位置づけを担わせます。長い説明は載せません。
• 文字は少ないほど効果的です。README を読み終えた後も読者に覚えていてほしい情報だけを、各画像に残します。
• 段落、コマンド、表、バージョン番号の羅列、細かく密集した説明は載せません。

プロジェクト紹介画像のテキスト方針

デフォルトでは「プロジェクト紹介画像」を使用し、雰囲気だけの画像は使いません。

画像	推奨テキスト	上限
banner.webp	プロジェクト名 + 一言の位置づけ + 1～3 個の短いタグ	英語 18 語、または中国語 28 文字
features.webp	2～3 個の成果を表す短いフレーズ。必要に応じて短いタイトルを追加	各フレーズ 2～5 語

よいテキストは、説明書ではなく表紙のタイトルのようなものです。

• プロジェクト名は明確にし、優先して banner.webp に配置します。
• 位置づけの文ではスローガンではなく成果を伝えます。たとえば “Portfolio-grade README design for open source projects” のようにします。
• タグには、検索や記憶に役立つ価値が最も高い語だけを使います。たとえば Story、Visual、Signal です。
• 中国語も使えますが、控えめにします。英語のプロジェクト名や短い英語のタグのほうが、通常は安定します。
• Image Gen がテキストを誤って描画した場合は、もう一度試します。それでも正確でない場合は、Image Gen の画像を背景として残し、HTML/CSS のフォールバックで正確なテキストを表示します。
• 「すべて AI 生成」にこだわって、プロジェクト名や位置づけの正確さを犠牲にしないでください。

文字サイズの下限

1920×1080 でデザインする場合：

要素	最小文字サイズ
メインタイトル	92px
中国語のメインタイトル	80px
大きなカードのタイトル	48px
本文の説明	28px
補助タグ	22px
フッター	20px

18px 未満の文字は使わないでください。GitHub 上で縮小すると読めなくなります。

Codex Image Gen の生成物は、16:9 の比率と十分な鮮明さを保てば問題ありません。1920×1080 に合わせるために、よい画像を無理に再サンプリングしないでください。README の表示画像は WebP で保存するのを優先します。1920×1080 は HTML to PNG フォールバック用のテンプレートサイズです。

HTML to PNG フォールバック

Image Gen を利用できない場合、ユーザーが正確な構造化テキストを求める場合、または Image Gen の出力が検査に合格しない場合に限り使用します。

node scripts/gen_infographic.mjs /tmp/readme-banner.html assets/banner.png 1920 1080
node scripts/gen_infographic.mjs /tmp/readme-features.html assets/features.png 1920 1080
node scripts/convert_webp_assets.mjs assets/banner.png assets/banner.webp assets/features.png assets/features.webp

テンプレートの出典：

templates/banner.html
templates/features.html

テンプレート変数：

{{PROJECT_NAME}}
{{TAGLINE}}
{{PRIMARY_COLOR}}
{{CATEGORY}}
{{PLATFORM}}
{{LANGUAGE}}
{{VERSION_INFO}}
{{TECH_CARDS}}
{{FEATURE_CARDS}}
{{FEATURE_COUNT}}

カードの構成：

• {{TECH_CARDS}} は表紙の右側に配置し、2～3 件を推奨します。短いタグと一文の説明だけを入れます。
• {{FEATURE_CARDS}} には大きなカードを 2～3 枚だけ配置し、最初のカードには featured を追加できます。
• ワークフローを表現する必要がある場合は、features.webp の 3 つの成果段階で表現し、3 枚目の画像は追加しません。

Codex Image Gen / gpt-image-2 の使用方法

デフォルトでは Codex に組み込まれた画像生成機能の呼び出しを優先し、プロジェクト内に一時的な API スクリプトをハードコードしないでください。

Image Gen に適した内容：

• README の表紙。
• 製品の雰囲気を伝える画像。
• ポートフォリオのビジュアル。
• 抽象的なコンセプト画像。
• 既存の画像を使ったスタイル展開。

Image Gen に適さない内容：

• 正確なフローチャート。
• 大量の中国語テキストや複数段落の説明。
• コマンド、バージョン、表。
• 一字一句の正確さが求められる長文や UI 画像。

推奨するプロンプトの構成：

Use case: productivity-visual
Asset type: GitHub README visual asset, 16:9
Project: <project_name>
Story: <origin + promise>
Visual direction: black background, minimalist, cinematic lighting, high contrast, large negative space, low brightness, premium magazine cover
Texture and lighting: #050505 deep black background, subtle paper grain, shallow depth of field, volumetric haze, thin rim light, selective metallic highlights
Palette: white, gray, warm gold only
Composition: one strong visual idea, restrained, spacious, no dense UI
Quality bar: 10k-star designer portfolio quality
Text policy: include only high-value name-card text. Use the exact project name, one short positioning line, and optional 1-3 short labels. No paragraphs, commands, tables, tiny captions, or decorative text.
Avoid: emoji, clutter, fake interface text, tiny labels, generic gradients, bright neon, overdesigned dashboards

Image Gen が対応していない、呼び出せない、または誤ったテキストやスタイルのずれが出力された場合は、まず短いテキストプロンプトで一度再試行します。それでも正確でない場合は、HTML to PNG のフォールバック手順に切り替えて、正確なテキストを表示します。

画像の軽量化

README の表示画像には、デフォルトで WebP を使用します。WebP は通常、README の読み込みに PNG より適しています。PNG は HTML スクリーンショットのフォールバック用の中間生成物、透明画像、またはロスレスでの保存が必要な場合にのみ使用します。

デフォルトのコマンド：

npm run webp

プロジェクトに WebP 変換スクリプトがない場合は、cwebp、sips、または利用可能な軽量ツールを優先します。変換のために重い依存関係を追加しないでください。変換できない場合は PNG のまま残し、その理由を説明します。

ビジュアルの確認

画像を生成するたびに、次の点を確認します。

• GitHub README の表示幅まで縮小しても読める。
• 1 枚の画像で伝える要点は 1 つだけ。
• 小さな文字を詰め込んでいない。
• プロジェクト名と位置づけの文が一目でわかる。
• 画像内のテキストにスペルミス、文字化け、偽の文字がない。
• 装飾が過剰でない。
• ビジュアルのスタイルがプロジェクトのストーリーと一致している。
• Image Gen の画像に誤ったテキストや不要な透かしがない。
• 圧縮後も画像が鮮明で、目立つバンディング、ノイズによる劣化、文字のぼやけがない。

---

Phase 4: README の組み立て

デフォルトの構成：

<div align="center">

# 项目名

**一句话价值主张**

<img src="assets/banner.webp" alt="[项目名] — [价值主张]" width="100%">

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

</div>

---

## 这是什么

[2-3 句话讲清项目、背景、结果。]

## 为什么需要它

[讲真实问题，不列反模式清单。]

## 你会得到什么

<img src="assets/features.webp" alt="[3 个核心能力]" width="100%">

## 工作方式

[2-4 行讲清工作方式；不要默认再放第三张图。]

## 快速开始

[最短可执行路径。]

## 安装

[依赖和安装命令。]

## 许可证

[MIT](./LICENSE)

## 关于作者

[简洁作者信息。]

ルール：

• プロジェクトにステータス表示が本当に必要な場合を除き、バッジは 3 個を超えないようにします。
• 画像の後に同じ機能一覧を繰り返しません。
• 「設計原則」「プロジェクト構成」「生成コンテンツ」をすべて README に詰め込まず、読者に役立つ部分だけを残します。
• ワークフロー図を 3 枚目の画像としてデフォルトで追加しません。2 枚の画像で、作品としての魅力と核心情報を十分に伝えられます。
• 詳細な説明がある場合は docs/ に置き、README は入口として使います。

---

Phase 5: GitHub メタデータの提案

Repository Description と Topics は、GitHub 検索、Trending との関連付け、AI 検索での引用、そして人がすばやく判断するための入口です。README の内容ではないため、README.md には書かず、最終回答で独立した提案として出力します。

First-principles の目標

• Description では、このプロジェクトが誰にどんな成果をもたらすかを説明します。
• Topics では、このプロジェクトをどの検索カテゴリに含めるべきかを示します。
• 推奨数 はシグナルの質で決め、多さを追い求めません。質の高い 7～9 個は、通常、20 個を並べるより効果的です。
• Trending / SEO / GEO のバランスを取り、人気の検索語を含めつつ、プロジェクトの事実に忠実で、AI が引用しやすい内容にします。

Description の生成ルール

候補を 3 つ生成し、それぞれを採点します。

[Verb] [specific outcome] for [audience] — [1-3 precise keywords]

必須条件：

• 英語を優先し、160 文字以内にします。
• 動詞で始めます：Design / Generate / Build / Create / Convert / Automate。
• プロジェクトの最も重要なキーワードを 2～3 個含めます。
• 絵文字、感嘆符、宣伝用の形容詞は使いません。
• プロジェクトの事実で裏付けられない機能は書きません。

採点：

項目	点数	判断基準
正確性	40	プロジェクトの実際の機能に忠実か
検索価値	25	GitHub / Google でよく検索される語を含んでいるか
AI による引用のしやすさ	20	ChatGPT / Claude / Perplexity が直接理解できるか
簡潔さ	15	誇張や無駄な表現がないか

星の評価：

点数	評価
90-100	星 5 つ。推奨
80-89	星 4 つ。使用可能だが、さらに簡潔にできる
70-79	星 3 つ。代替案としてのみ適切
< 70	推奨しない

Topics の生成ルール

まず候補を集め、その後、最終的な推奨項目を選びます。

候補の出典：

• プロジェクトの種類：agent-skill、cli-tool、developer-tools、documentation
• 主要な技術：nodejs、playwright、codex、image-generation
• 適用分野：readme、github-readme、open-source、portfolio
• 現在のトレンド：AI agent、image generation、developer tooling、documentation automation
• プロジェクトの実際のファイルや README の説明に登場するキーワード

選定ルール：

• 7～9 個を推奨し、プロジェクトが複数の明確な分野にまたがる場合を除き、10 個を超えないようにします。
• Topic は小文字で、英字、数字、ハイフンのみを使用します。
• 抽象的すぎる語を削除します：software、tool、app、github、project、ai。
• 重複する語を削除します：readme と github-readme は併用できますが、open-source と opensource はどちらか一方だけ残します。
• トレンドを追うために、実態に合わない topic を追加しません。

各 topic に星の評価と理由を付けます。

評価	意味
星 5 つ	関連性が強く、検索価値が高い。追加すべき
星 4 つ	関連性と発見されやすさがあり、追加してよい
星 3 つ	ある程度関連しているが、中心的ではない
星 2 つ	関連性が弱く、通常は推奨しない
星 1 つ	ノイズとなるため、追加しない

出力形式：

GitHub Description 推荐：

1. ★★★★★ <description>
   理由：...

2. ★★★★☆ <description>
   理由：...

最终推荐：<description>

GitHub Topics 推荐：

加入：
- ★★★★★ github-readme — 精准描述项目用途
- ★★★★★ agent-skill — 符合项目形态
- ★★★★☆ image-generation — 当项目支持 Image Gen 时加入

不建议加入：
- ★★☆☆☆ ai — 太泛，搜索噪音大
- ★★☆☆☆ github — 太泛，不能帮助分类

任意の gh CLI による更新

ユーザーが gh をインストールしていて、現在のディレクトリが Git リポジトリであり、GitHub remote を解析できる場合は、gh repo edit を使った更新をエージェントに依頼する方法を提案できます。ユーザーに無断で更新してはいけません。実行する内容を先に提示し、ユーザーの確認を待つ必要があります。

確認：

gh --version
git remote -v

推奨コマンド形式：

gh repo edit OWNER/REPO \
  --description "<final-description>" \
  --add-topic topic-one \
  --add-topic topic-two \
  --add-topic topic-three

古い topics を置き換える必要がある場合は、まず現在の topics を読み込み、明確に非推奨と判断できる項目だけを削除します。

gh repo view OWNER/REPO --json description,repositoryTopics
gh repo edit OWNER/REPO --remove-topic old-topic --add-topic new-topic

说明：git 不能更新仓库元信息

git 命令不能修改 GitHub 仓库的 Description 或 Topics。原因：Description 和 Topics 是 GitHub 平台元信息，不是 Git 仓库里的 commit、branch、tag 或 remote 配置。

git remote -v 只能用来识别 OWNER/REPO，不能用来更新元信息。

如果没有 gh，只给出推荐值，让用户到 GitHub 页面手动更新；不要提供复杂备选命令。

不要用 README 文件保存这些推荐；它们属于交付时对用户的操作建议。

---

Phase 6: 验证和交付

交付前必须验证：

node --version
npm run showcase
file assets/banner.webp assets/features.webp
git status --short

如果改了模板或实际图片，必须重新生成 WebP 并打开检查。

最终汇报只说清楚：

• 改了什么。
• 结果怎样。
• 哪些验证跑过。
• 是否还有需要用户决定的点。

不要把实现细节和冗长过程写给用户。