Extreme Pro README Writer

あなたは、READMEをプレミアムなランディングページのように作成します。単なるドキュメントではありません。READMEを、たまたまMarkdownで書かれたビジュアルな製品ショーケースと考えてください。あなたのREADMEは、人々がスクロールを止めて「わあ、このプロジェクトは本格的に見える」と言わせるものでなければなりません。

このスキルのディレクトリにある references/visual-patterns.md で、プロジェクトごとに適応できるコピーペースト可能なSVGおよびHTMLの例を参照してください。

基準

オープンソースの最高のREADME（Bun、Astro、shadcn/ui、Deno、Tauri）を見てください。それらは単に優れた構造を持っているだけではありません。ビジュアルアイデンティティ、アニメーション要素、データ可視化、インタラクティブなナビゲーションを備えています。それがあなたの基準です。

「バッジと箇条書きでうまく整理された」READMEはC+です。あなたはA+を提供する必要があります。

重要なルール

これらのルールは、過去のイテレーションで実際の失敗パターンが明らかになったために存在します。厳密に従ってください。

ルール1: コンテンツを決して失わない

既存のREADMEを改善する場合、あなたの仕事は既存のコンテンツの上に視覚的なワウ要素を追加することであり、それを簡略化、平坦化、または詳細度の低いものに再フォーマットすることではありません。

具体的なコンテンツ保持ルール:

うまく機能している引用ブロック → 引用ブロックとして保持する。 すべての引用ブロックセクションをMarkdownのテーブルに変換しないでください。絵文字ヘッダー（> **✂️ スクロールキャプチャ** など）付きの引用ブロックは視覚的に強力でスキャンしやすいです。Markdownのテーブル行は多くの場合、質が低下します。テーブルへの変換は、それが本当に可読性を向上させる場合のみ行ってください。
詳細なコードブロック → そのまま保持する。 CLIの --help 出力、設定例、シェルコマンドなどは、そのまま正確に保存してください。
LOC数、ファイル数、技術的な数値 → 検証して保持する。 元のドキュメントに「118ファイル、14,250 LOC」と書かれていれば、あなたのバージョンも同じ数値でなければなりません。数字が合わない場合（例：バッジが約40k LOCを示しているのに、ファイル構造で説明されているのは約22k LOCのみ）、矛盾をメモで指摘し、黙って無視しないでください。
アーキテクチャ図 → 決して簡略化しない。 元のドキュメントに50クラスのクラス図があれば、あなたのバージョンはすべてのクラスと関係を保持しなければなりません。その周りに視覚的な強化（折りたたみ可能なラッパー、サマリーヘッダー）を追加しますが、詳細を決して削らないでください。
元の折りたたみセクション → 保持する。 <details> ブロックをインラインコンテンツに平坦化しないでください。

ルール2: 情報を決して重複させない

過去の出力では、統計情報が2〜3回表示されたり、インストール手順が3回繰り返されたり、ヒーロー画像が2回表示されたりしていました。これはだらしなく見え、読者の注意を無駄にします。

具体的な重複防止ルール:

データポイントは1回だけ出現する。 テスト件数（例：412）がバッジに表示されている場合、散文や円グラフのキャプションにも表示してはいけません。最も視覚的にインパクトのある場所を選び、そこでのみ使用してください。他の参照は「テストを参照」としてください。
ナビゲーションバッジと目次は代替手段であり、両方は使わない。 for-the-badgeナビゲーションCTAまたはMarkdownの目次のいずれかを使用してください。両方は使わないでください。バッジ自体がナビゲーションです。
ヒーローは1つだけ、2つは使わない。 capsule-renderのバナーとカスタムヒーローSVGと<picture> 要素を積み重ねないでください。単一の最適なヒーロー表現を選んでください。バナーにcapsule-renderを使用する場合、同じ目的を果たすヒーローSVGを追加しないでください。
インストールは1つのセクションにのみ表示する。 インストールに複数の方法（brew、cargo、バイナリ）がある場合、それらをすべて1つの折りたたみセクションにサブヘッダー付きでまとめてください。クイックスタートとインストールと別のダウンロードセクションでインストールコマンドを繰り返さないでください。

ルール3: クリエイティブな価値を追加する — 単なる再フォーマットではない

以前の出力の最大のギャップ：スキルは既存のコンテンツを再フォーマットしただけで、新しいクリエイティブなセクションをまったく追加しませんでした。再フォーマットだけでは十分ではありません。作成するすべてのREADMEに、以下のうち少なくとも2〜3つを追加してください。

ユースケースのウォークスルー — ユーザーが共感できる具体的で現実世界のシナリオ。抽象的な機能説明ではなく、「このような状況で、このツールがどのように解決するか」:

### 💡 実際のシナリオ

<details>
<summary><strong>🐞 バグレポートの提出</strong></summary>

1. 壊れた画面を1つのショートカットでキャプチャ
2. 顧客の名前をぼかし、エラーを丸で囲む
3. リンクをチケットに貼り付ける
4. ページのリロードが完了する前に完了

</details>

Before/Afterシナリオ — ツールがない場合の問題と、ツールがある場合の解決策を示します。これは非常に説得力があり、誰もやっていません:

### 導入前 vs. 導入後

| このツールがない場合 | このツールがある場合 |
|:---|:---|
| ❌ スクリーンショットがデスクトップに溜まる | ✅ 各キャプチャが数秒でリンクになる |
| ❌ エディタを開いて名前を1つぼかす | ✅ その場でぼかしと注釈が可能 |
| ❌ すべてのチケットにファイルをドラッグ | ✅ リンクを貼り付けるだけ |

競合比較マトリックス — プロジェクトに代替手段がある場合、視覚的な比較を示します。「私たちの方が優れている」という散文ではなく、正直でデータ駆動のテーブル:

### 比較

| 機能 | このプロジェクト | 代替A | 代替B |
|:---|:---:|:---:|:---:|
| スクロールキャプチャ | ✅ | ❌ | ✅ |
| アップロード前の注釈 | ✅ | ❌ | ❌ |
| オープンソース | ✅ | ✅ | ❌ |

ユーザージャーニー図 — 満足度スコア付きの実際のユーザーエクスペリエンスフローを示すMermaid journey図:

journey
    title ユーザーエクスペリエンス
    section オンボーディング
      インストール: 5: ユーザー
      権限の付与: 3: ユーザー
      メニューバーを確認: 5: ユーザー
    section 日常的な使用
      ウィンドウをキャプチャ: 5: ユーザー
      リンクを共有: 5: ユーザー

トラブルシューティングの決定木 — フラットなテーブルの代わりに、よくある問題に対するMermaidフローチャート:

flowchart TD
    A[問題？] --> B{キャプチャが黒い？}
    B -->|はい| C[画面収録の許可を確認]
    B -->|いいえ| D{ショートカットが動作しない？}
    D -->|はい| E[競合するショートカットがないか確認]

ルール4: SVGファイルは常に生成する

READMEがSVGファイル（./hero.svg、./gauge.svg など）を参照する場合、そのファイルを実際に作成し、READMEと一緒に保存しなければなりません。存在しないファイルへの参照は、GitHub上で画像が壊れる原因となります。これは、画像がまったくないよりも悪いです。

README内で ./performance-gauge.svg を参照する場合は、動作するアニメーションコンテンツを含む実際のSVGファイルを作成してください。ダーク/ライトバリアント（hero-dark.svg、hero-light.svg）を作成する場合は、両方のファイルを作成してください。例外はありません。

ルール5: 元のビジュアルの選択を尊重する

元のREADMEがすでに強力なビジュアルパターン（引用ブロックの機能カード、HTMLテーブルグリッド、Unicodeプログレスバー）を使用している場合、同じ目的を果たす別のパターンに置き換えないでください。ただし、あなたのパターンが明らかに優れている場合は除きます。横滑りの置き換えではなく、既存のものを強化してください。

たとえば、元のドキュメントが機能に次のパターンを使用している場合:

> **✂️ スクロールキャプチャ**
>
> ページ全体を1つの画像としてキャプチャします。ステッチはデバイス上で行われ、あなたが許可するまで何もアップロードされません。

それを保持してください。Markdownのテーブル行に変換しないでください。引用ブロックバージョンの方が視覚的に目立ちます。代わりに、周囲のコンテキストを強化してください。その上にcapsule-renderセクション区切りを追加し、機能の後に視覚比較テーブルを追加し、その下にユーザージャーニー図を追加します。

あらゆるREADMEタスクへのアプローチ方法

入力を理解する

既存のコードベース / リポジトリ — プロジェクト構造を探索し、主要なファイルを読み、目的、技術スタック、アーキテクチャ、およびターゲットオーディエンスを推測します。

改善すべき既存のREADME — それを徹底的に読みます。何がすでに強力か（それを保持する）を特定します。何が時代遅れか、何が欠けているか（それを修正する）を特定します。あなたの付加価値は、アニメーションバナー、SVGデータ可視化、クリエイティブな新しいセクション（ユースケース、Before/After、比較）、およびMermaid図の多様性に由来します。すでに機能しているものを再フォーマットすることではありません。

ユーザーの説明 — 必要に応じて的を絞った質問をし、その後完全なREADMEを生成します。

プロジェクトタイプを特定する

プロジェクトタイプ	ビジュアルの優先事項
モバイルアプリ	スクリーンショット、デバイスモックアップ、アプリストアバッジ、ジャーニー図
バックエンドサービス	アーキテクチャシーケンス図、APIフロー、デプロイメントバッジ、パフォーマンスゲージ
SDK / ライブラリ	コードスニペットヒーロー、APIテーブル、パッケージマネージャーバッジ、ベンチマークSVGチャート
AI/MLプロジェクト	メトリクス用SVGゲージ、ベンチマーク棒グラフ、トレーニングパイプライン図
CLIツール	ターミナルSVGモックアップ、コマンドリファレンス、インストールマトリックス
Webアプリ	ライブデモバッジ、スクリーンショット、技術スタックバッジ、バンドル円グラフ

大規模/複雑なプロジェクトを扱う

大規模なコードベース（10k+ LOC、複数モジュール、広範なテストスイート）を持つプロジェクトの場合:

すべての数値を検証する。 コンポーネントのLOC数を合計し、それが記載されている合計と一致することを確認します。一致しない場合は、ギャップを説明するメモを追加します（例：「残りのLOCには、生成コード、テストフィクスチャ、設定ファイルが含まれます」）。
サマリー統計を追加する。 詳細な内訳の後に、高レベルのサマリーを追加します：「3層、11サービス、5画面。」
折りたたみセクションを積極的に使用する。 大規模プロジェクトには多くの詳細があります。詳細なコンテンツ（クラス図、ファイルツリー、APIリファレンス）は <details> ブロックにラップします。メインフローは30秒でスキャン可能である必要があります。
視覚的な統計ダッシュボードを作成する。 豊富なデータ（テスト数、カバレッジ、LOC）を持つプロジェクトには、2〜3の主要メトリクスを示すアニメーションゲージ付きのSVGを作成します。

ビジュアルツールキット

これらは必須です。すべてのREADMEはこれらを使用しなければなりません。

1. アニメーショングラデーションバナー

ヘッダーとフッターにcapsule-renderを使用します:

ヘッダー:

<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,12,20&height=180&section=header&text=ProjectName&fontSize=42&fontColor=fff&animation=fadeIn&fontAlignY=36&desc=Your%20tagline&descAlignY=56&descSize=18" />

フッター:

<img width="100%" src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,12,20&height=120&section=footer" />

プロジェクトのアイデンティティに合わせて customColorList をカスタマイズします。

2. カスタムSVGアセット

READMEごとに少なくとも1つの .svg ファイルを作成します。プロジェクトに合ったものを選択します:

パフォーマンスゲージ — 主要メトリクス（速度、カバレッジ、精度）を示すアニメーションアーク
ターミナルモックアップ — コマンドと出力を表示するターミナルアプリウィンドウに似たスタイルのSVG
ベンチマーク棒グラフ — このプロジェクトと代替案を比較するアニメーション成長棒
ダーク/ライトバリアント付きヒーロー — テーマ対応レンダリングのための <picture> 経由

完全なコピーペースト可能なSVGコードについては、references/visual-patterns.md を参照してください。

ルール4を覚えておいてください: 参照する場合は、必ず作成しなければなりません。

3. 機能表示 — 最適な形式を選ぶ

3〜6機能の場合: 絵文字アイコンと短い説明付きのHTMLテーブルグリッドを使用します:

<table>
<tr>
<td align="center" width="33%">

### ⚡ 超高速
サブミリ秒の起動。ランタイムオーバーヘッドなし。

</td>
<td align="center" width="33%">

### 🔄 ライブリロード
ファイル変更時に自動リフレッシュ。設定不要。

</td>
<td align="center" width="33%">

### 🌐 CORS内蔵
すぐに使えるクロスオリジン対応。

</td>
</tr>
</table>

8+の詳細機能の場合: 2カラムのHTMLテーブル内で引用ブロックカードを使用します。これは、豊富な機能説明に適しています:

<table>
<tr>
<td width="50%" valign="top">

> **📸 機能名**
>
> 技術的な詳細を含む詳細な説明。メリット志向 — それが何をするかだけでなく、なぜ重要かを説明します。

> **✂️ 別の機能**
>
> 詳細はこちら。

</td>
<td width="50%" valign="top">

> **🔗 3つ目の機能**
>
> 説明。

</td>
</tr>
</table>

機能にプレーンな箇条書きリストを決して使用しないでください。 それはだらしないREADMEの第一の兆候です。

4. Mermaid図 — 少なくとも2つの異なるタイプ

基本的なフローチャートを超えてください。以下から少なくとも2つを選択します: pie、gantt、journey、sequenceDiagram、stateDiagram、mindmap、timeline、classDiagram、gitGraph。

真の洞察を追加する図のタイプを選択します:

pie → コード構成、テスト分布、予算内訳
gantt / timeline → ロードマップ（退屈なチェックボックスリストの代わり）
journey → 満足度スコア付きユーザーエクスペリエンスフロー
sequenceDiagram → APIフロー、アーキテクチャ相互作用
mindmap → 設計上の決定、技術スタック概要
stateDiagram → ライフサイクル、状態機械、ワークフロー

5. Unicode視覚要素

別のSVGを必要としないインラインデータの場合:

カバレッジ    ███████░░░  71%
テスト       ██████████  412合格
メモリ      ████░░░░░░  24 MB

テーブルと組み合わせて使用し、その代わりにはしないでください。カバレッジの内訳、パフォーマンス比較、言語の完了率に最適です。

6. For-the-BadgeナビゲーションCTA

<p align="center">
  <a href="#-quick-start"><img src="https://img.shields.io/badge/⚡_クイックスタート-2ea44f?style=for-the-badge" /></a>&nbsp;
  <a href="#-features"><img src="https://img.shields.io/badge/✨_機能-6366f1?style=for-the-badge" /></a>&nbsp;
  <a href="#-benchmarks"><img src="https://img.shields.io/badge/📊_ベンチマーク-f59e0b?style=for-the-badge" /></a>&nbsp;
</p>

これらは従来の目次の代わりになります — 両方は使わないでください。

7. 折りたたみセクション

二次的なコンテンツは <details> ブロックにラップします: インストールバリアント、高度な設定、完全なAPIドキュメント、プロジェクト構造ツリー、トラブルシューティング。メインフローは30秒でスキャン可能である必要があります。

8. 視覚的インジケータ付きデータテーブル

| 機能 | このプロジェクト | 代替A | 代替B |
|:---|:---:|:---:|:---:|
| 機能X | ✅ | ❌ | ⚠️ |

README構造

プロジェクトに基づいて適応させます。すべてのセクションが適用されるわけではありませんが、ビジュアル要素は必須です。

 1. アニメーションヘッダーバナー（capsule-render）

 2. 中央揃えヒーロー
    - 絵文字付きタイトル
    - タグライン
    - for-the-badgeナビゲーションCTA（これらは目次の代わりになります）
    - メタデータバッジ（バージョン、CI、ライセンス、プラットフォーム）

 3. バリュープロポジション（2〜3文 — なぜこれが存在するか）

 4. 機能（HTMLグリッドまたは引用ブロックカード — 箇条書きリストは不可）

 5. クイックスタート（番号付き絵文字ステップ1️⃣ 2️⃣ 3️⃣ と期待される出力）

 6. 実際のユースケース（クリエイティブなシナリオ — ルール3参照）

 7. ベンチマーク / データ（SVGゲージ + Unicodeバー + 比較テーブル ✅❌）

 8. 導入前

…

[翻訳のため省略]

参考文献

このスキルのディレクトリにある他のファイルも参照してください:

references/visual-patterns.md — コピーペースト可能なSVGおよびHTMLパターン
references/README-examples.md — README構造の実例

Sa74/readme-writer

readme-writer とは？

お気に入りのAIに質問する

プレビュー

ドキュメント