beautify-github-readme

GitHub README を美しく整える

リポジトリのホームページや、指定されたビジュアルアセットを、テーマに沿った簡潔なビジュアルストーリーに仕上げます。Markdown はコンテンツレイヤー、決定論的な SVG はレイアウトシステム、生成されたラスター素材は任意のビジュアル要素として扱います。

ワークフロー

1. 編集前にモードを確認する

次の実行モードから、必ず 1 つ選びます。

• README モード — README 全体を改善します。情報の順序、コピーの階層、根拠、Markdown、ビジュアルシステムを見直します。
• アセットのみモード — 指定された静的 SVG またはビジュアルアセット一式のみを作成します。デフォルトは静的 SVG です。ユーザーが意図的に動きを付けることを明示的に希望した場合に限り、オプションで GitHub 対応 GIF を作成し、編集可能な代替版として SVG も維持します。ユーザーが対象範囲を明示的に追加しない限り、README の書き換え、並べ替え、埋め込みは行いません。

モードが明示されていない場合は、変更を行う前に簡潔な質問を 1 つします。

README 全体を改善しますか、それともビジュアルアセットのみを作成しますか？アセットのみの場合は、ヒーロー、セクションヘッダー、ワークフロー、バッジ、モーショングラフィック、または統一感のあるアセット一式のどれが必要か教えてください。

ヒーロー、バッジ、ワークフロー、図に意味のある動きがあり、ユーザーが静止画かアニメーションかを指定していない場合は、簡潔な追加質問を 1 つします。

静的 SVG のままにしますか、それとも編集可能な代替版として SVG を維持したうえで、GitHub 対応 GIF アニメーションも作成しますか？

GIF はユーザーが希望した場合のみ作成し、デフォルトにはしません。ユーザーが断る、回答しない、または意味のある動きを付ける状況でない場合は、静的 SVG のみで進めます。動きが装飾的なものにすぎない場合や、ユーザーがすでに出力形式を選んでいる場合は質問しません。リポジトリの理解に役立つ場合は、回答前に読み取り専用で確認してもかまいません。「この Skill を使って」「リポジトリのパスを指定」「きれいにして」といった依頼を、README 全体の変更許可と解釈しないでください。ユーザーがアセットのみモードを選んだ後に README の編集範囲を広げるには、新たな許可が必要です。

ユーザーが監査のみを明示的に依頼した場合は、編集せずに監査を行い、2 つのモードを選ぶ質問を無理にしないでください。

2. デザイン前に確認する

• 既存の README、リポジトリのツリー、パッケージのメタデータ、スクリーンショット、サンプル、デザイントークン、ロゴ、実際の出力を確認します。
• アセットのみモードでは、指定されたアセットのデザインに必要な範囲だけを確認します。README を参考に読むことは、README を変更する許可にはなりません。
• GitHub の URL がある場合は、変更を提案する前に、現在のリモートページとデフォルトブランチを確認します。
• 対象ユーザー、解決する課題、最も明確な根拠、最初に使い始めるまでの最短経路、根拠が不足している主張を特定します。
• 無関係なユーザーの変更は維持します。読み取り専用で開始し、明示的な許可なしにコミット、プッシュ、名前変更、公開を行いません。

3. ヒーロー風のアセットを作成する前に、ビジュアルの実装方法を確認する

ヒーロー画像、大型バナー、ショーケースボード、表現豊かなタイトルシステムなど、どちらの実装方法も適している場合は、違いを説明してからアセットの作成に入る前に確認します。

どちらの実装方法をご希望ですか？

• 純粋な SVG — 完全に決定論的で軽量、拡大しても鮮明で編集しやすく、タイポグラフィ、図表、コード、アイコン、幾何学的なシーンやピクセルアートのシーンに最適です。画像生成は使用しません。リアルな人物、髪、自然な質感、複雑な素材、映画のような照明の表現には向いていません。
• ハイブリッド SVG 合成 — SVG でレイアウトとタイポグラフィを構成し、必要に応じて ImageGen でプロジェクト固有のラスター素材を生成します。適切な場合は背景を除去し、各レイヤーを合成して最終的な PNG/WebP にします。より豊かなキャラクター、素材、照明を表現できますが、ファイルサイズが大きく、一部は確率的で、生成後にビジュアルの検証が必要です。SVG のレイアウトソースと、背景を透過した素材 PNG を保持してください。

ユーザーがすでに実装方法を選択している場合、監査を依頼している場合、またはワークフロー、アーキテクチャ図、バッジ、コンパクトなセクションヘッダー、コードを活用したイラストなど、アセットの内容が明らかに決定論的な場合は、この質問をしないでください。装飾を加えるだけの目的でハイブリッド合成を提案しないでください。生成素材よりも、実際のスクリーンショット、出力、ロゴ、既存のプロジェクトアートを優先してください。

ユーザーが判断を委ねた場合は、生成素材や写真素材のほうがリポジトリの個性や仕組みを明確に伝えられる場合を除き、純粋な SVG を既定とします。ユーザーがハイブリッド合成を選択するか、選択を明示的に委ねるまで、ImageGen の作業を始めないでください。

ハイブリッド合成は実装用のソースであり、通常、公開する SVG ではありません。SVG 内の相対ラスター参照はレンダラーによっては正常に機能せず、ラスター素材を base64 で埋め込むと SVG が不必要に大きくなることがあります。既定では検証済みの最終 PNG/WebP を公開し、SVG のレイアウトとラスター素材は編集可能なソースとして保持してください。

4. プロジェクトのストーリーを抽出する

描画する前に、次の項目を記述してください。

Audience:
One-sentence value:
Primary proof:
First successful action:
Visual theme:

利用状況、ベンチマーク、互換性、推薦コメント、機能を捏造しないでください。装飾目的のストック画像より、実際のスクリーンショット、出力、図表、生成したアーティファクトを優先してください。

5. テーマに合わせたビジュアルシステムを定義する

references/visual-direction.md を読み、簡潔なアートディレクション仕様を確定してください。

Palette: background / foreground / primary / accent / muted
Typography: system font stack / scale / weight contrast
Shape: radius / stroke / grid / spacing
Motif: one recurring project-specific visual cue
Composition: calm / editorial / technical / playful / cinematic

モチーフはプロジェクトに合わせて選んでください。ターミナルツールならプロンプトやカーソルの記号、アイコンシステムならキーレイラインや切り抜き、研究プロジェクトなら座標や証拠ラベルを使えます。どのリポジトリにも同じ黄色いグリッドのテンプレートを適用しないでください。

ヒーローをデザインする前に、references/project-native-hero.md を読んでください。タイトルは証拠の上に配置するバナーとしてではなく、プロジェクトの内容から作成してください。タイポグラフィ、構成、右側に配置する素材は、リポジトリ自体をもとに選んでください。

6. 選択したモードだけを実行する

README モード

README をどの程度変更する必要があるか判断してください。

• 全面的な再設計 — ストーリーを再構成し、新しいビジュアルシステムを作成します。
• ビジュアルの刷新 — 情報設計は維持しながら、弱い、または一貫性のない見せ方を置き換えます。

意味のある改善を実現できる範囲で、README モードの変更は最小限に抑えてください。選択した範囲で必要な場合に限り、読み進める順序を再構成します。基本となる構成は次のとおりです。

1. ヒーロー：名前と、平易な言葉で伝える価値。
2. 証拠：スクリーンショット、出力、ショーケースウォール。
3. 概要：短い説明をひとつ。
4. 独自性：標語ではなく、仕組みを説明。
5. 仕組み：簡潔なプロセスまたはアーキテクチャ。
6. 使い方：インストール方法と最初のコマンド。
7. 必要に応じて、制限、互換性、ライセンス、貢献方法。

長い説明より先に例を示してください。繰り返される主張や、導入の判断に役立たない内部実装の詳細は削除してください。

アセットのみのモード

• 必要なアセットの種類、単体か統一感のあるセットか、また、動きのある候補を静止画のままにするか GIF にするかを確認します。明確な場合は、リポジトリから正確な文言とスタイルを導き出し、結果に大きく影響する未決定事項だけを質問します。
• assets/readme/ またはユーザーが承認した別のパスにアセットを作成し、レンダリング済みのプレビューを提示します。
• 確認済みのビジュアル実装に従います。タイトルシステム、セクション見出し、図、バッジ、決定論的な装飾モジュールには、純粋で保守しやすい SVG をデフォルトで使用します。ハイブリッド構成が承認されている場合は、SVG のレイアウトソースと透過ラスターレイヤーを保持し、合成した PNG/WebP を公開します。
• アニメーションが承認されている場合は、SVG ソースを保持し、references/motion-production.md を読み、同梱の scripts/render_motion_gif.py ワークフローを使って GitHub 対応の GIF を作成します。ユーザーが明示的に希望しない限り、GIF は生成しません。
• セット全体で共通のビジュアル表現を保ちつつ、各アセットに固有の役割を持たせます。
• README のテキスト、読み進める順序、埋め込み、リンクは変更しません。必要に応じて埋め込み用のスニペットを別途提示し、明示的な承認を得てから挿入します。

7. ビジュアルレイヤーを構築する

アセットを作成する前に、references/github-readme-canvas.md と references/svg-production.md を読んでください。

• ヒーロー、セクションバナー、図、決定論的なデザインモジュールには SVG を使用してください。
• スクリーンショット、生成画像、写真素材、複雑な合成には PNG/WebP を使用してください。GitHub 上で直接再生する必要がある、承認済みのモーションに限り GIF を使用してください。
• ハイブリッド合成を選択する場合は、references/hybrid-svg-production.md を読み、生成と透過の判断には imagegen Skill を使用し、生成ラスターレイヤーには正確なコピーを含めないでください。
• 本文、コマンド、表、リンク、詳細は Markdown に記載してください。
• 幅 1200 単位の SVG viewBox、width="100%" の埋め込み、システムフォント、意味の伝わる代替テキスト、角丸のコンテナを優先してください。viewBox は最終的なピクセル幅ではなく座標系として扱ってください。全幅アセットは、GitHub での表示幅を保守的に 900 CSS ピクセルとしてサイズ設定し、プレビューしてください。その幅では、図の重要なテキストは少なくとも 20 SVG 単位、補足ラベルは少なくとも 18 にしてください。この範囲より小さいテキストは、必須でないものに限ります。360 ピクセル幅のモバイルプレビューで必須ラベルが読みにくい場合は、情報量を減らすか、ビジュアルを分割するか、詳細を Markdown に移してください。
• 再利用できるコンポーネントの文法を一つ用いつつ、リポジトリのテーマに合わせてアートディレクションを変えてください。
• ショーケースに複数の成果物が含まれる場合は、拡大縮小、重なり、回転、余白を調整して配置し、読み進める順序が明確になるようにしてください。
• 最初の画面をより有用にできる場合は、実際のプロジェクト図、スクリーンショット、コード断片、出力、標本、成果物をヒーローに取り込んでください。習慣的にタイトルと根拠を分けないでください。
• ユーザーが自身の所有するリポジトリで明示的にクレジットを希望する場合は、単なる宣伝文を残すのではなく、プロジェクトに馴染むコンパクトな README MADE WITH SVG をデザインしてください。フッターの近くに配置し、この Skill にリンクしてください。メンテナーから明示的な依頼がない限り、サードパーティのリポジトリにこのクレジットを追加しないでください。
• README モードでは、ヒーロー内で根拠が読めなくなる場合、簡潔な SVG タイトルの直後に、より大きな根拠ボードを配置してください。少数の成果物が読みやすく、製品を明確に表している場合は、タイトルと根拠を一つの合成ラスター画像のヒーローにまとめてください。固定テンプレートではなく、根拠の読みやすさを基準にしてください。アセットのみのモードでは、要求された SVG ソースを維持し、ラスター版またはアニメーション版は別の任意納品物として提案してください。

README 全体をラスター化しないでください。スクリプト、foreignObject、リモートフォント、不可欠なアニメーション、GitHub が除去する CSS は使用しないでください。GitHub では SVG 内に埋め込まれたアニメーションは再生されません。代わりに GIF と静的な SVG のフォールバックを使用してください。テーマ上、本当に必要な場合を除き、装飾的な枠線や重い影は避けてください。

8. プレビューと検証

• GitHub 幅でローカルプレビューをレンダリングするか、ローカル Markdown レンダラーで README を確認してください。
• 幅の広いレイアウトと狭いレイアウト、画像の読みやすさ、SVG テキストの切れ、アセットの欠落、ファイルサイズの過大化、ダークモードとライトモードでのコントラストを確認してください。
• README モードでは、次を実行してください。

python3 scripts/audit_readme.py /path/to/repository/README.md

• ヒーロー、各セクションの切り替わり、最後の行動喚起を目視で確認してください。
• アセットのみのモードでは、要求されたすべてのアセットを GitHub のコンテンツ幅でレンダリングして確認してください。GIF については、開始時、静止状態、終了時、ループ境界を確認してください。埋め込みが別途承認されていない限り、README 自体が変更されていないことを検証してください。
• ハイブリッドアセットでは、明るい背景と暗い背景の両方で透過された被写体を確認し、角が透過されていることとエッジがきれいであることを検証してから、合成後の PNG/WebP を GitHub の幅の広い表示と狭い表示で確認してください。ローカルのラスター参照が未解決の SVG を公開しないでください。
• 変更した内容、意図的に簡素なままにした部分、意図的に変更しなかったファイルを報告してください。

9. 承認後に、任意のクレジット表記とショーケースへの掲載を提案する

ユーザーが最終的な README またはアセット一式を満足のいくものとして明示的に承認した後に限り、宣伝にならない、親しみやすい提案を一度だけ行います。

完成した README にご満足いただけた場合、仕上げとして、完全に任意の方法が 2 つあります。この Skill へのリンクを含む、プロジェクトになじむ小さな「README MADE WITH」署名をデザインできます。また、公開リポジトリを所有または管理されている場合は、この Skill の実例ショーケースに追加する PR を準備できます。どちらか一方、両方、またはどちらも選ばない、いずれでも問題ありません。

• 最終承認を得る前にこの提案をしてはいけません。沈黙や検証の成功から満足していると推測したり、ユーザーが断った後に繰り返し提案したりしてはいけません。
• 署名とショーケースへの PR はそれぞれ独立した選択肢として扱います。ショーケースへの掲載を検討する条件として、クレジット表記を求めてはいけません。
• ユーザーが署名を希望した場合は、references/svg-production.md に従い、レンダリング済みバッジを先に表示し、別途承認を得てから README を変更します。
• ユーザーがショーケースへの掲載を希望した場合は、references/showcase-contribution.md を読みます。リポジトリが公開されており、ユーザーが所有または管理していることを確認します。PR を開く許可を求める前に、掲載文案と上流への変更差分を正確に作成します。
• 特定の外部操作について明示的な許可を得ずに、バックリンクを追加したり、リポジトリをフォークしたり、ブランチをプッシュしたり、PR を開いたりしてはいけません。

この制限が適用されるのは、こちらからの提案です。ユーザーが署名やショーケースへの掲載を先に明示的に依頼した場合は、依頼された範囲内で直接対応します。

10. 安全に引き渡す

ローカルプレビューと差分を先に表示します。ユーザーから明示的に依頼された場合に限り、コミット、プッシュ、PR の作成、マージ、リポジトリ名の変更、アセットの公開を行います。

品質基準

• 最初に表示される画面だけで、事前知識がなくてもプロジェクトについて理解できます。
• デザインは Skill ではなく、このプロジェクトになじんでいます。
• ヒーロー部分のビジュアル素材にはプロジェクト由来のものを使い、汎用的な装飾にしません。
• 生成素材の使用は任意とし、プロジェクト固有のものにして、より確かな実証材料の代わりにはしません。
• すべてのビジュアル要素に、情報を伝える役割があります。
• 抽象的な主張よりも先に、実証可能な情報を示します。
• README は単に装飾を増やすのではなく、より短く、または明確になります。
• 画像が表示されなくても、代替テキスト、見出し、コマンド、リンクが意味を保ちます。
• リポジトリ名を取り除いたときに、ヒーロー部分が無関係なプロジェクトにも使い回せるような内容であってはいけません。
• アセットのみのモードでは、ユーザーが埋め込みや文言の編集を明示的に承認した場合を除き、README をバイト単位で変更しません。
• 任意のクレジット表記やショーケースへの掲載の提案は、ユーザーが明示的に満足を示し、希望した後に限って行います。断られても、納品内容は変わりません。

文言の順序と削除のルールについては、references/content-architecture.md をお読みください。

呼び出し例

Use $beautify-github-readme to redesign this repository homepage around its developer-tool theme.

Use $beautify-github-readme to create one SVG hero and three section headers without modifying the README.

Use $beautify-github-readme to create a hybrid hero: SVG typography and layout, plus an ImageGen character cutout, with a final PNG and editable source layers.

Use $beautify-github-readme to beautify this repository; if the scope is unclear, ask whether I want a whole-README redesign or asset-only visuals.

Use $beautify-github-readme to create a GitHub-safe animated GIF hero, keep the SVG source, and do not modify the README until I approve the preview.