gr-readme について
GitHub プロジェクトのメンテナー向け README 作成スキルです。冒頭の位置づけからクイックスタート、機能紹介、コミュニティ案内までの構成を示します。具体的で検証可能な情報を重視し、README とスキル説明の設計を結び付けています。
主な機能
- 01冒頭の位置づけとタグライン設計
- 02README のセクション構成
- 03クイックスタートの指針
- 04ユーザー課題に沿った機能整理
- 05AI エージェント連携の記載案
活用シーン
- 01GitHub プロジェクトの README を改稿
- 02対象読者と冒頭の内容を明確化
- 03実行可能なセットアップ手順を作成
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/gr-readmeを入力して読み込まれたか確認します。
詳細
GitHub README のライティングシステム
AFFiNE を 0 から 60K スターまで成長させた経験をもとに構築しました。最初の 30 日間、README は製品を説明するだけでなく、製品そのものでした。
—（AFFiNE の事例、Iris Wei @WeiYipei、ep01/ep03/ep06）
二重の視点 / Dual Frame：README のライティング ＝ スキルの説明文のライティング
README の作成にそのまま応用できる、Claude Code Skills から得た洞察を紹介します。
「Claude は
descriptionフィールドを使って、そのスキルをいつ適用するかを判断します。」
README のタグラインも、まったく同じロジックで機能します。適切な読者が自分に関係があると判断できる、一文の説明です。 スキルの description を読んでも Claude がいつ使うべきか判断できないなら、README を読んだ訪問者も、なぜその製品が必要なのか判断できません。
以下の表は、その対応関係を示しています。
| README の要素 | スキルのフロントマターのフィールド | 共通する原則 |
|---|---|---|
| タグライン（最初の行） | description の最初の文 | 具体的で、ひと目で把握でき、適切な読者の関心を引く |
| 補足説明（2〜3 文） | description の本文 | 問題＋解決策＋差別化要因 |
| README 内のトリガーフレーズ | when_to_use | 他のものではなく、これ をいつ使うかを明確にする |
| アーキテクチャ／仕組み | 補足ファイル（reference.md） | 常にコンテキストに含めるのではなく、必要に応じて詳細を確認できる |
| クイックスタートのコマンド | allowed-tools ＋シェルブロック | 具体的で、実行可能で、検証できる |
これは単なる比喩ではなく、実用的なテストです。スキルの description と同じ基準を満たす一文のタグラインを README に書けないなら、README はまだ改善が必要です。
核心原則 / Core Principles
原則 1：README は製品の最初のランディングページです
README の役割はひとつです。GitHub の訪問者が最初にスクロールしてから 3 秒以内 に、スター、フォーク、インストールのいずれかにつなげることです。それ以外はすべて二の次です。
原則 2：製品が未完成でも、README は優れたものにできます
AFFiNE のオープンソース公開時、製品はまだ「皮をかぶせただけ」のデモでしたが、README を適切に書けば、それでも話題になりました。 —（AFFiNE の事例、Iris Wei @WeiYipei、ep03/ep06）
README はストーリーを伝えるものです。売り込むのは、現在の機能一覧ではなく、ビジョンと解決する課題 です。「なぜ必要なのか」が明確な README を持つ完成度 30％の製品は、機能を羅列した完成済みの製品を上回ります。
原則 3：英語を優先し、最初の画面を 3 秒未満で理解できるようにします
README は英語を中心にし、最初の画面を 3 秒未満で理解できるようにします。 —（AFFiNE の事例、Iris Wei @WeiYipei、ep03）
GitHub ページの最初のスクロール範囲は約 600〜800px です。ファーストビューに表示される内容はすべて、次の質問に答える必要があります。これは何か。なぜ重要なのか。誰のためのものか。
原則 4：具体的で検証可能な指示は、ありきたりな主張よりも効果的です
Anthropic のプロンプトエンジニアリング と CLAUDE.md の効果的な指示 より：
「インデントには 2 つのスペースを使う」は、「コードを適切に整形する」より効果的です。 「コミットする前に
npm testを実行する」は、「変更をテストする」より効果的です。
README の文章にも同じ基準を当てはめてください。
- 「オフラインで動作します。インターネット接続は不要で、すべてのデータをローカルに保存します」✅
- 「強力なオフラインサポート」❌
README のすべての文は、読者の思考に対する指示です。検証できるほど具体的にしてください。
README 構成のフレームワーク / README Structure Framework
insforge（エージェント型コーディングのバックエンド）、dify（60K 以上のスターを獲得した LLM プラットフォーム）、および AFFiNE の 0→60K の成長分析をもとにしています。
[Logo + Project Name]
[One-line Tagline] ← most critical, non-skippable
[Badges] ← signals, not decoration
[Hero image / Demo video] ← show product in <30 seconds
[What is this? 2–3 sentences] ← first screen core
[Quick Start] ← shorter = better; just get it running
[Key Features] ← sorted by user pain, not tech checklist
[Architecture / How it works] ← optional; use for complex projects
[Deployment options] ← cloud / local / one-click
[Claude Code / AI Agent Integration] ← new section; see below
[Contributing] ← short, link to CONTRIBUTING.md
[Community & Support] ← Discord / X / Discussions
[License]
[Star CTA GIF] ← ❗️ FIRST 3 SCREENS — inline with hero or after Quick Start
[Star History] ← social proof, bottom (optional extra)
首画面の 3 秒ルール / 最初の画面の 3 秒ルール
ルール： 最初のスクロールより上にあるすべての情報で、読者が考えなくても次の 3 つの質問に答えられるようにします。
| 質問 | 回答する場所 |
|---|---|
| これは何ですか？ | タグライン（1 文） |
| なぜ気にかけるべきですか？ | 補足説明または問題提起（2～3 文） |
| 実在し、信頼できますか？ | バッジ：スター数、ライセンス、ダウンロード数、最終コミット |
insforge の優れた点： ロゴ → 1 行のタグライン → デモ動画 → 3 文の補足説明。すぐに要点を把握できます。動画は言葉を使わずに製品を紹介しています。
dify の優れた点： ヒーロー画像 → 最小限のバッジ列 → 7 つの具体的な機能を平易な言葉で挙げた 1 段落の説明 → すぐにクイックスタート。
よくある失敗： ビジュアル要素の前に、冗長な「このプロジェクトについて」の段落を置くこと。開発者は導入文ではなく、手がかりを探して読みます。
各セクションの書き方ガイド
Section 1: タグライン
README 全体で最も重要な一行です。
優れたタグラインは、次の 3 つを同時に伝えます。
- 製品が何であるか（カテゴリ）
- 誰を対象としているか（対象ユーザー）
- 解決する課題は何か（問題）
タグラインの公式（いずれかを選択）：
[Adjective] [category] for [audience]
→ "Open-source backend platform for AI coding agents"
[Category] without [pain point]
→ "Note-taking without the cloud lock-in"
[Familiar reference] + [key differentiator]
→ "Open source Notion alternative — offline-first, privacy-focused"
[Outcome verb phrase]
→ "Ship full-stack apps from your AI agent, end to end"
AFFiNE の事例：
タグライン：「オープンソースの Notion 代替」 6 語で 3 つの課題に対応しています：Notion がオフラインで使えない、データのエクスポートが不十分、プライバシーの問題。 — （Iris Wei @WeiYipei、ep01）
このタグラインは Notion のブランド認知度を活用し（説明不要）、さらに「代替」という言葉で、オープンソースであること、セルフホスト可能であること、「嫌な点を除けば同じ機能が使えること」を一度に伝えています。
ルール：
- 12 語以内
- プロジェクトについての事前知識が必要な専門用語は使わない
- 文脈がなくても意味が通じること。この一行だけを誰かが目にする場面を想像してください
- 「高性能な…」や「素晴らしい…」で始めないでください。製品の特別な点を把握していない書き手だという印象を与えます
スキル設計との関連： これは Skills docs の description フィールドのルールと同じです。「主要なユースケースを最初に書く」。スキル一覧や GitHub の検索結果では、最初の文が途中で切り詰められます。
Section 2: ヒーロー画像／デモ動画
説明する前に見せましょう。
30～60 秒のデモ動画を使えば、認知負荷を約 80% 軽減できます。動画がない場合、UI 製品には実際の使用状況を示す高品質なスクリーンショットまたは GIF が不可欠です。
CLI／SDK ツールの場合は、mermaid のアーキテクチャ図とインストールコマンドが同等の役割を果たします。
ルール：
- 動画は 60 秒以内にし、字幕を付けること（対象ユーザーには英語を母語としない人も多く含まれます）
- スクリーンショットには、空の状態ではなく、製品の使用中の様子を表示すること
- GitHub 独自の CDN にホストすること。外部 CDN ではなく、課題のエディターにドラッグしてください
- 対応している場合は、ダークモードとライトモードの両方のバリエーションを用意すること
Section 3: クイックスタート
このセクションの目的は、ユーザーができるだけ早く実行中のインスタンスを使えるようにすることだけです。
# 3–5 commands max. No explanations between commands.
git clone https://github.com/yourorg/yourrepo
cd yourrepo
docker compose up -d
# → open http://localhost:3000
ルール：
- セットアップに 5 個を超えるコマンドが必要なら、問題は README ではなくオンボーディングにあります
- 前提条件はコマンドの上に記載し、脚注に埋もれさせないこと
- 代替手段として、クラウド版／ホスト版へのリンクを提示すること。「セルフホストしたくない場合は、cloud.yourproject.com をお試しください」
- コマンドは新しいマシンで実際に動作する必要があります。必ずテストしてください。
dify の優れた点： クイックスタートは、説明の直後にある文字どおり2 番目のセクションです。最小システム要件（CPU／RAM）を示し、その後に 4 つのコマンドを並べています。最初にアーキテクチャを長々と説明することはありません。まず実行できる状態にし、その後で説明します。
Section 4: 主な機能
技術的な実装ではなく、ユーザーの課題に沿って並べましょう。
❌ 悪い例（技術的な一覧）：
- WebSocket support
- Plugin architecture
- REST API
- TypeScript SDK
✅ 良い例（課題を優先）：
- Works offline — no internet required, all data stored locally
- Export everything — Markdown, PDF, raw JSON, always your data
- Self-hostable — deploy to your own server in 5 minutes
- Plugin API — extend with your own tools
ルール：
- メインの一覧には 7 つ以内の機能を記載すること。7 つを超えると、「自分たちが何者なのかわかっていない」という印象を与えます
- 各箇条書きでは、課題を先に、実装の詳細を後に書くこと
- キーワードを太字にすること。GitHub では機能一覧の太字が表示され、階層を無料で作れます
- スター数が多い場合は、「X 人の開発者に利用されています」のようにさりげなく触れ、機能セクションで社会的証明を示すこと
Section 5: アーキテクチャ／仕組み（任意）
次の場合に含めます：
- プロジェクトのコンポーネント構造が分かりにくい場合（バックエンドプラットフォーム、分散システムなど）
- コントリビューターになるかどうかを判断するために、開発者がアーキテクチャを理解する必要がある場合
- 利用するだけでなく、統合する開発者を対象にする場合
ルール：
- GitHub でネイティブにレンダリングされる
mermaidを使用します。図 1 つにつき 200 語分です。 - 図のノード数は 8 以下にします
- このセクションはクイックスタートの後に配置します
graph TD
A[User / AI Agent] --> B[Your Product Core]
B --> C[Service A]
B --> D[Service B]
B --> E[Service C]
Section 6: デプロイオプション
開発者の 3 つの利用形態すべてに対応します：ローカル開発、セルフホストの本番環境、クラウド。
| Method | Link | When to use |
|--------|------|-------------|
| Cloud (hosted) | [yourproject.com](link) | Zero setup, try now |
| Docker Compose | [Quick Start](#quick-start) | Self-hosted, recommended |
| Railway / Render | [one-click deploy](link) | Self-hosted, no Docker |
| From source | [Dev Guide](link) | Contributing |
ワンクリックデプロイボタン（Railway、Render、Zeabur、Sealos）は、信頼性を示す強力な指標となり、Docker を使わないユーザーの導入の手間をなくします。
Section 7: Claude Code／AI エージェントとの連携 ← 新しいセクション
プロジェクトが次のいずれかに該当する場合、このセクションを追加します：
- Claude Code のスキルまたは MCP プラグインとして使用できる
- AI エージェントが呼び出せる CLI がある
- エージェント型ワークフローが呼び出す API を公開している
## Claude Code / AI Agent Integration
Install as a skill (Claude Code):
\```
npx skills add your-project-name
\```
Or reference directly in your `CLAUDE.md`:
\```markdown
@your-project/README
\```
For MCP integration:
\```json
{
"mcpServers": {
"your-project": {
"command": "npx",
"args": ["-y", "@your-org/your-mcp-server"]
}
}
}
\```
重要な理由：
- Claude Code のスキルは
~/.claude/skills/または.claude/skills/から読み込まれます。スキルシステムがプロジェクトの機能を理解するために、最初に README を読むことがよくあります（スキルのドキュメント） - バンドルされた
/runと/verifyのスキルは README から起動方法を推測します。明確なクイックスタートのセクションがあると、AI エージェントの導入が直接改善されます - GEO（Generative Engine Optimization）：構造化された機械可読な README セクションにより、AI システムがプロジェクトを正確に引用する可能性が高まります
Section 8: コントリビューション
簡潔にします。詳しいガイドは CONTRIBUTING.md に記載します。
## Contributing
PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup.
Questions? Join [Discord](link) or open a [Discussion](link).
README にコントリビューションガイドを丸ごと載せないでください。読み進める流れが妨げられ、CTA が文章の中に埋もれてしまいます。
Section 9: コミュニティとサポート
チャンネルをアクションの種類に合わせます。目的を説明せずにチャンネルを列挙しないでください：
## Community & Support
- **Discord** — questions, help, show what you built
- **GitHub Discussions** — feature requests, long-form questions
- **GitHub Issues** — bugs only
- **X / Twitter** — announcements, follow for updates
- **Email** — security issues, enterprise inquiries
Section 10: Star 履歴グラフ
一番下に配置します。これはソーシャルプルーフであり、ナビゲーションではありません。
[](https://star-history.com/#yourorg/yourrepo&Date)
急激な右肩上がりの曲線は、「このプロジェクトは実在する」ことを示します。投資家もこれを利用します。
投资人专门写爬虫查 Star 真假，说明真实口碑就是你最有力的信号。 —（AFFiNE の事例、Iris Wei @WeiYipei、ep03）
セクション 11：スターを促す GIF — 最も活用されていないコンバージョン施策
マウスで★の Star ボタンをクリックする様子を短い GIF で見せると、通りすがりの人がスターを付けてくれるようになります。ささいなことに思えるかもしれませんが、効果があります。
効果がある理由：
- 迷いをなくします。初めて訪れた人の多くは、スターを付けるにはどこをクリックすればよいのか分かりません。
- 小さなコミットメントを促します。アニメーションを見ることで、行動を起こしやすくなります。
- 大きく目立つ「PLEASE STAR US」というテキストとは違い、押し付けがましくなく、人間味があります。
GIF の作成方法（3 つの選択肢）：
| 選択肢 | ツール | 時間 | 品質 |
|---|---|---|---|
| 画面を録画して変換 | QuickTime (Mac) + Gifox / LICEcap / ScreenToGif | 5 分 | ★★★★ |
| ブラウザー拡張機能 | Screencastify または Loom → GIF としてエクスポート | 3 分 | ★★★ |
| オンライン録画ツール | Giphy Capture (Mac) | 3 分 | ★★★ |
録画する内容（手順）：
- ブラウザーでリポジトリを開き、ズームを 125% にします
- マウスをゆっくり★の Star ボタン（右上付近）に移動します
- 1 秒間停止します
- クリックし、アニメーション（スターが黄色に変わる様子）を再生させます
- 全体の長さは 3～5 秒にし、途切れずにループするようにします
GIF の仕様：
- サイズ：幅 400～600px、高さは自動調整
- 長さ：3～5 秒、ループ再生
- ファイルサイズ：1MB 未満にします（スムーズな読み込みのための GitHub CDN の上限）
- 1MB を超える場合は、Ezgif で最適化します
README での配置場所：最初の 3 画面内。最下部には置かない
❗️ ほとんどのリポジトリでは、スターを促す CTA を最下部に埋もれさせています。その頃には、訪問者の 80% 以上がすでに離れています。 実際に目に入る場所に置きましょう。
オプション A — ヒーローと一緒に配置（推奨）： タグラインとバッジの直後、Quick Start の前に置きます。関心を持つかどうかをまだ判断している段階の訪問者に届きます。
## About
Open source Notion alternative. [tagline...]
⭐ **If this looks useful, star it** — it helps others find the project.
オプション B — Quick Start の後に配置（次善策）： ユーザーがプロジェクトを正常に実行できた直後に配置します。熱意があるうちに促しましょう。
## Quick Start
```bash
npm install yourproject
効果がありましたか？ ⭐ このリポジトリにスターを付ける — 2 秒で完了します。
**Option C — Star History at the bottom (in addition to A or B, not instead):**
```markdown
## ⭐ Star History
[](https://star-history.com/#yourorg/yourrepo&Date)
ルール：必ず A または B を使います。C は追加の選択肢です。
GIF をリポジトリに保存する：
yourrepo/
└── assets/
└── star-demo.gif ← commit this
文面のガイドライン：
- ✅
"このプロジェクトがお役に立ったら、スターを付けていただけるとうれしいです" - ✅
"スターを付けて最新情報を受け取りましょう" - ❌
"PLEASE GIVE US A STAR!!!" - ❌
"Don’t forget to star!"（義務を感じさせます）
GIF がお願いしてくれるので、テキストでお願いする必要はありません。
バッジの使用原則 / バッジの使用原則
バッジは装飾ではなく、シグナルです。それぞれのバッジが、開発者の疑問に答えます。
| バッジの種類 | 答える質問 | 含めるか |
|---|---|---|
| ライセンス | 「商用利用できますか？」 | 必ず含める |
| スター | 「人気がありますか／メンテナンスされていますか？」 | 必ず含める |
| 最終コミット | 「放置されていますか？」 | 含める |
| ビルド／CI ステータス | 「実際に動作しますか？」 | 含める |
| ダウンロード数（npm/docker/pypi） | 「実際に使っている人はいますか？」 | 1K を超える場合に含める |
| コードカバレッジ | 「コード品質は本当に高いですか？」 | 70% を超える場合のみ |
| バージョン | 「安定しているのはどれですか？」 | ライブラリでは含める |
| 「Made with X」パートナーバッジ | — | 必須でない限り省く |
ルール：
- 最初の行に置くバッジは 8 個以下にします。それ以上は視覚的なノイズになります。
- 意味ごとにまとめます：プロジェクト情報 → 健全性 → コミュニティ
- 失敗を示すバッジは使いません。赤い CI バッジは、CI バッジがないよりも悪い印象を与えます。
よくある失敗パターン / アンチパターン（README の失敗パターン）
❌ 失敗パターン 1：課題を説明せずに機能を羅列する
Features:
- Real-time collaboration
- Markdown support
- Plugin system
- REST API
- Mobile app
- Dark mode
誰向けなのか、なぜ必要なのかがまったく分かりません。
改善策： まず課題から説明します。「[X が起きて] 作業を失ったことがあるなら、MyApp が解決します。」
❌ 失敗パターン 2：Quick Start を奥に追いやる
2 回目のスクロール位置より下に Quick Start があると、開発者の 60% はすでに離れています。
改善策： Quick Start は第 2 セクションか第 3 セクションに置きます。それより後にはしません。
❌ 死亡パターン 3：ありきたりなキャッチフレーズ
A powerful, flexible, and extensible framework for modern developers.
「パワフル」「柔軟」「拡張可能」——どのプロジェクトもこうした主張をしています。これはノイズです。
改善策： 具体的な課題を挙げます。具体的なカテゴリを示します。具体的なユーザーを示します。
プロンプトエンジニアリングとの共通点： Anthropicのガイダンスにあるように、曖昧な指示（「コードを適切にフォーマットしてください」）は一貫性のない結果を生みます。同じ原則です。曖昧なキャッチフレーズは、読者の行動に一貫性がない状態を生みます。
❌ 死亡パターン 4：スクロールせずに見える範囲にビジュアルがない
テキストの壁 → テキストの壁 → テキストの壁。開発者は流し読みします。じっくり読むわけではありません。
改善策： キャッチフレーズの直後にヒーロー画像かデモ GIF を配置します。UI 製品では必須です。
❌ 死亡パターン 5：README が現地語のみ
README は英語を主言語にし、最初の画面だけで3秒以内に理解できるようにする。 —（AFFiNE の事例、Iris Wei @WeiYipei、ep03）
中国語のみ、または日本語のみの README では、アプローチできるオーディエンスが限られます。GitHub Trending、HN、Reddit はすべて、英語を優先するプラットフォームです。
改善策： 英語を主要なドキュメントにします。翻訳版はバッジまたは /i18n/ フォルダーから利用できるようにします。
❌ 死亡パターン 6：コントリビューションセクションがテキストの壁
README の ## Contributing が400行にわたると、文章に埋もれて誰にも読まれません。
改善策： 1段落と CONTRIBUTING.md へのリンクにします。README はランディングページです。
❌ 死亡パターン 7：スターを虚栄の指標として扱う
スターは拡散のシグナルです。GitHub Trending、検索順位、投資家によるデューデリジェンスでは、スターの増加速度が信頼性を測る代替指標として使われます。
AFFiNE は1週目に6Kスター、1か月目に10Kスターを獲得し、合計で60K以上に達しました。2週間にわたる熱心なコミュニティ対応により、GitHub Trending に28回連続で掲載されました。 —（Iris Wei @WeiYipei、ep01/ep06）
コンバージョン率の高い README はスターの増加を促し、Trending への掲載を促し、さらなるスター獲得につながります。README はこのループの入り口です。
❌ 死亡パターン 8：AI エージェント／Claude Code のセクションがない（2025年以降）
2025年現在、GitHub の訪問者のかなりの割合を、AI コーディングエージェントや、Claude Code、Cursor、または類似ツールを通じてプロジェクトを使おうとするユーザーが占めています。AI エージェントとの連携セクションがない README は、急成長しているインストール経路を逃しています。
改善策： セクション 7：Claude Code／AI エージェントとの連携を追加します。
AFFiNE の主要データ／参考用 AFFiNE データポイント
すべて Iris Wei（@WeiYipei）のポッドキャストエピソード（ep01／ep03／ep06）から引用しています。
| 指標 | 値 | 出典 |
|---|---|---|
| 1週目のスター数 | 6,000 | ep01/ep03 |
| 1か月目のスター数 | 10,000 | ep01 |
| スター総数 | 60,000+ | ep01/ep03 |
| GitHub Trending への掲載回数 | 28回連続 | ep06 |
| キャッチフレーズの戦略 | 「オープンソースの Notion 代替」— オフライン利用／データエクスポート／プライバシーの課題を対象 | ep01 |
| ローンチ時の製品の状態 | 「ラッパーのデモ」（不完全なラッパーデモ） | ep03/ep06 |
| Trending 掲載の継続につながった要因 | 最初の2週間にわたる熱心なコミュニティ返信 | ep06 |
| 初回ローンチにつながった要因 | ローンチ前に開発者向けドキュメント、トラフィック経路、コンテンツを準備 | ep01 |
| 投資家からのシグナル | 投資家はスターの信頼性を検証するためにクローラーを作成 | ep03 |
重要な洞察： ローンチ時の製品はラッパーデモでした。README は適切な課題に焦点を当てました。その結果、1週目に6,000スターを獲得しました。README は製品機能ではなく、マーケティング層です。そして、製品の完成度とは独立して効果を発揮します。
公開前のセルフチェックリスト
README の公開または大幅な更新の前に毎回実行します。
最初の画面（スクロール不要）
- ロゴ／プロジェクト名が見やすく、明確に表示されている
- キャッチフレーズは12語以内で、「何を」「誰に」「どんな課題を」解決するかに答えている
- 最初の画面内にヒーロー画像、GIF、またはデモ動画がある
- バッジの列があり、バッジは8個以内
- ビジュアル要素が表示される前にテキストの壁がない
コンテンツ
- クイックスタートが上位3セクション以内にある
- クイックスタートのコマンドが5個以下で、新しいマシンでも動作する
- 機能は技術的な実装方法ではなく、ユーザーの課題の大きさ順に並んでいる
- 各機能の箇条書きは仕組みではなく、メリットから始まっている
- コントリビューションのセクションは1段落以内で、CONTRIBUTING.md へのリンクがある
言語とトーン
- 主な使用言語は英語
- 「powerful」「flexible」「amazing」「robust」は使わず、具体的な表現に置き換えている
- 「オープンソースを信じています」という前置きはなく、要点から始まっている
- タグラインが「A」や「An」で始まっていない
信頼性を示す要素
- ライセンスバッジがある
- CI／ビルドステータスのバッジがあり、パスしている
- 一番下にスター履歴チャートがある
- 最初の3画面以内にスターを促すGIFがある（assets/star-demo.gif、1MB未満、3〜5秒のループ）— 一番下には置かない
- README に Discord／コミュニティへのリンクがある
- スター数が500を超えている場合、バッジで見えるようになっている
技術面
- すべてのリンクをテスト済み（404がない）
- 画像はGitHub CDNにホストされている（外部ホストではない）
-
mermaidの図がGitHubプレビューで正しく表示される - ワンクリックデプロイボタンをテスト済み（該当する場合）
- READMEがモバイルで正しく表示される（GitHubモバイルで確認）
AI時代に向けた追加項目
- スキル対応： 明確な
npx skills addまたはMCPのインストールコマンドがあるか？ - GEO対応： READMEには、AIシステムが正確に引用できる、構造化された機械可読なセクション（表、見出し、コードブロック）があるか？
- エージェントに親切なクイックスタート： Claude Codeの
/runスキルは、カスタムスキルを設定しなくてもREADMEから起動コマンドを推測できるか？
クイック診断 / Quick Diagnosis
2026年のアクティベーション基準
READMEは宣伝資料ではなく、ユーザーの利用開始を促す場です。最初の画面で、明確な価値提案を目に見えるデモと最短の実行手順につなげてください。日付付きコホートで README visit → install/start → first successful outcome → return を追跡します。スターは付くのに、ユーザーが約3分以内に最初の成果へ到達できない場合は、流入を増やす前に、前提条件、コピー＆ペーストできるコマンド、期待される出力、トラブルシューティング、統合例を改善してください。ベンチマークには日付を付け、自己申告のエビデンスにはその旨を明記します。
READMEのレビューを依頼されたら、次の順に確認します。
-
最初の画面だけを読む（スクロールしない状況を想定）。 プロダクトについて何が分かりますか？ 誰を対象としていますか？ なぜ重要なのでしょうか？ 3つすべてに答えられない場合は、タグラインまたはヒーローセクションを書き直す必要があります。
-
クイックスタートを見つける。 何番目のセクションにあるか数えます。5番目以降の場合は、上に移動する必要があります。
-
タグラインを声に出して読む。 人が話すような売り文句に聞こえますか、それとも機能の羅列に聞こえますか？ 後者なら、課題を先に示す方式で書き直します。
-
機能の数を数える。 箇条書きが7個を超える場合、「このうち、どの3つがインストールの決め手になるか」を考えます。その3つを残し、ほかは削除します。
-
長文の段落がないか確認する。 コントリビューションセクションより前に5行を超える段落があれば、図やデモのほうがうまく説明できる内容である可能性があります。
-
言語を確認する。 主な使用言語は英語ですか？
-
AIとの統合を確認する。 Claude Code／AIエージェントのセクションはありますか？ クイックスタートは自動インストールに対応していますか？（2025年に追加。）
参考資料
Claude Code 公式ドキュメント / Claude Code Official Docs
- スキル — frontmatter の仕様、context:fork、allowed-tools、when_to_use
- メモリ — CLAUDE.md の4層スコープ、効果的な指示、具体性のルール
- プロンプトエンジニアリングの概要
- Claude Code ドキュメントのトップページ
- サブエージェント
Anthropic のコース / Courses
プロンプトエンジニアリング
コミュニティ
ケーススタディの README
- AFFiNE — 0→60K スターのケーススタディ（主な参考資料）
- Dify — 60K 以上のスターを獲得した LLM プラットフォーム。クイックスタートを積極的に配置
- InsForge — エージェント型コーディングのバックエンド。簡潔なタグラインと Mermaid によるアーキテクチャ図
Iris（生姜 Iris）著 · AFFiNE 元 COO（0 → 60k★）
OSS 全体の成長戦略については、gr-oss-marketing または gingiris-opensource をご利用ください
README の執筆に特化したスキルはこちらです
海外展開コミュニティへの参加と資料パックの購入 · コミュニティとリソース
-
海外展開コミュニティへの参加： WeChat で staywildgrow を追加し、「加入社群」とメッセージを送ってください。
-
資料パックの購入： WeChat で staywildgrow を追加し、Gingiris 海外展開資料パックの購入についてお問い合わせください。価格は 599 元（人民元） です。
-
海外展開コミュニティへの参加： WeChat で staywildgrow を追加し、「加入社群」（コミュニティに参加）とメッセージを送ってください。
-
資料パックの入手： WeChat で staywildgrow を追加すると、Gingiris 海外展開資料パックを 599 CNY で購入できます。
コミュニティと有料の資料パックは任意です。オープンソースのこのスキルのインストールや使用に必要なものではありません。
コミュニティと有料の資料パックは任意であり、オープンソースのこのスキルのインストールや使用にどちらも必要ありません。