GitHub READMEを美しくは何をしますか？

リポジトリのホームページやリクエストされたビジュアルアセットを、簡潔でテーマ固有のビジュアルストーリーに変換します。Markdownをコンテンツレイヤー、決定論的なSVGをレイアウトシステム、生成されたラスター素材をオプションの視覚的要素として扱います。

ワークフロー

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

実行モードは正確に1つだけ使用します：

READMEモード — README全体を改善：情報の順序、コピーの階層、校正、Markdown、視覚システム。
アセット専用モード — リクエストされた静的SVGまたはビジュアルアセットセットのみを作成します。静的SVGがデフォルトです。ユーザーが明示的に意味のある動きを選択した場合にのみ、SVGを編集可能なフォールバックとして保持しながら、GitHubセーフなGIFをオプションで提供します。ユーザーが明示的にその範囲を追加しない限り、README内の何も書き換えたり、並べ替えたり、埋め込んだりしないでください。

モードが明確でない場合は、変更を加える前に1つの簡潔な質問をします：

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

ヒーロー、バッジ、ワークフロー、または図に意味のある動きがあり、ユーザーが静的またはアニメーション出力を指定していない場合は、1つの簡潔なフォローアップを尋ねます：

これは静的SVGのままにしますか、それともSVGを編集可能なフォールバックとして保持したGitHubセーフなGIFアニメーションにしますか？

GIFはオプトインであり、デフォルトではありません。ユーザーが断ったり、回答しなかったり、意味のある動きのケースがない場合は、静的SVGのみで続行します。動きが純粋に装飾的である場合や、ユーザーがすでに出力を選択している場合は質問しないでください。回答前にリポジトリを理解するのに役立つ場合は、読み取り専用の検査は許可されます。「このスキルを使用」、「リポジトリパス」、または「美化する」を、README全体を変更する許可として解釈しないでください。ユーザーがアセット専用モードを選択した後、README編集に拡張するには新しい承認が必要です。

ユーザーが明示的に監査のみを要求した場合は、編集せずに監査し、2つのモードの質問を強制しないでください。

2. デザイン前に検査する

既存のREADME、リポジトリツリー、パッケージメタデータ、スクリーンショット、例、デザイントークン、ロゴ、実際の出力を読みます。
アセット専用モードでは、リクエストされたアセットをデザインするために必要なコンテキストのみを検査します。コンテキストのためにREADMEを読んでも、それを変更する権限は与えられません。
GitHub URLの場合は、変更を提案する前に現在のリモートページとデフォルトブランチを検査します。
オーディエンス、解決する問題、最も明確な証明、最初の使用までの最短経路、および証拠のない主張を特定します。
ユーザーの無関係な変更は保持します。読み取り専用で開始し、明示的な許可なしにコミット、プッシュ、名前変更、公開を行わないでください。

3. ヒーローライクなアセットを作成する前に視覚的実装を確認する

ヒーロー、大きなバナー、ショーケースボード、または表現力豊かなタイトルシステムで、両方の実装が実行可能な場合は、違いを説明し、アセットを生成する前に尋ねます：

どの実装にしますか？

純粋SVG — 完全に決定論的で、軽量、シャープにスケーラブル、編集が簡単で、タイポグラフィ、図、コード、アイコン、幾何学的またはピクセルアートのシーンに最適です。画像生成を使用せず、リアルな人物、髪、有機的なテクスチャ、複雑な素材、または映画的な照明には弱いです。

ハイブリッドSVG構成 — レイアウトとタイポグラフィにSVGを使用し、オプションでプロジェクト固有のラスター被写体にImageGenを使用し、必要に応じて背景を削除し、レイヤーを最終的なPNG/WebPに構成します。よりリッチなキャラクター、素材、照明をサポートしますが、重く、部分的に確率的であり、生成と視覚的検証が必要です。SVGレイアウトソースと透明な被写体PNGを保持します。

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

ユーザーが決定を委任した場合、生成された素材や写真素材がリポジトリのアイデンティティやメカニズムをより明確に伝えない限り、デフォルトで純粋SVGにします。ユーザーがハイブリッド構成を選択するか、明示的に選択を委任するまで、ImageGen作業を開始しないでください。

ハイブリッド構成は実装ソースであり、通常公開されるSVGではありません。SVG内の相対的なラスター参照はレンダラー間で信頼性が低く、base64埋め込みラスターレイヤーはSVGを不必要に大きくする可能性があります。検証済みの最終PNG/WebPをデフォルトで公開し、SVGレイアウトとラスターレイヤーを編集可能なソースとして保持します。

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

描画前にこれらを書きます：

オーディエンス：
一文の価値：
主要な証明：
最初の成功アクション：
ビジュアルテーマ：

採用、ベンチマーク、互換性、推薦、機能を発明しないでください。装飾的なストックイメージよりも、実際のスクリーンショット、出力、図、または生成されたアーティファクトを優先します。

5. テーマ固有のビジュアルシステムを定義する

references/visual-direction.mdを読んでください。コンパクトなアートディレクション仕様を確定します：

パレット： 背景 / 前景 / プライマリ / アクセント / マット
タイポグラフィ： システムフォントスタック / スケール / ウェイトコントラスト
シェイプ： 半径 / ストローク / グリッド / スペーシング
モチーフ： 1つの繰り返しプロジェクト固有のビジュアルキュー
構成： 落ち着いた / 編集的な / 技術的な / 遊び心のある / 映画的な

プロジェクトからモチーフを導き出します。ターミナルツールはプロンプトとカーソルマークを使用するかもしれません。アイコンシステムはキーラインとカットアウトを使用するかもしれません。研究プロジェクトは座標と証拠ラベルを使用するかもしれません。すべてのリポジトリに同じ黄色のグリッドテンプレートを適用しないでください。

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

6. 選択されたモードのみを実行する

READMEモード

READMEをどの程度変更する必要があるかを決定します：

フルリデザイン — ストーリーを再構築し、新しいビジュアルシステムを構築します。
ビジュアルリフレッシュ — 情報アーキテクチャを維持しながら、弱いまたは一貫性のない表現を置き換えます。

意味のある改善を生み出せる最小の変更をREADMEモード内で使用します。選択された範囲が必要とする場合にのみ、読み取り順序を再構築します。強力なデフォルトは次のとおりです：

ヒーロー：名前＋平易な言葉での価値。
証明：スクリーンショット、出力、またはショーケースウォール。
それが何か：1つの短い説明。
それが何が違うか：仕組み、スローガンではない。
使い方：短いプロセスまたはアーキテクチャ。
使用方法：インストール＋最初のコマンド。
制限、互換性、ライセンス、または関連する場合の貢献の詳細。

長い説明の前に例を置きます。採用に役立たない繰り返しの約束や内部実装の詳細は削除します。

アセット専用モード

リクエストされたアセットタイプ、ユーザーが1つのアセットか調整されたセットを望んでいるか、そして意味のある動きの候補が静的のままかGIFになるべきかを確認します。それらが明白な場合は、リポジトリから正確なコピーとスタイルを導き出します。結果を実質的に変更する欠落した決定についてのみ質問します。
assets/readme/またはユーザーが承認した別のパスの下にアセットを作成し、レンダリングされたプレビューを提供します。
確認された視覚的実装に従います。タイトルシステム、セクションヘッダー、図、バッジ、および決定論的な装飾モジュールには、デフォルトで純粋で保守可能なSVGを使用します。確認されたハイブリッド構成の場合は、SVGレイアウトソースと透明なラスターレイヤーを保持し、構成されたPNG/WebPを公開します。
承認されたアニメーションの場合は、SVGソースを保持し、references/motion-production.mdを読み、バンドルされたscripts/render_motion_gif.pyワークフローを使用してGitHubセーフなGIFを導き出します。ユーザーがオプトインしない限り、GIFを生成しないでください。
セット全体で1つの共有ビジュアル文法を維持しますが、すべてのアセットに特定のコミュニケーション役割を与えます。
READMEのテキスト、読み取り順序、埋め込み、リンクを変更しないでください。有用な場合は、埋め込みスニペットを別途提供します。明示的な承認後にのみ挿入します。

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

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

ヒーロー、セクションバナー、図、決定論的なデザインモジュールにはSVGを使用します。
スクリーンショット、生成アート、写真素材、複雑なコンポジットにはPNG/WebPを使用します。GitHub上で直接再生する必要がある承認されたモーションにのみGIFを使用します。
ハイブリッド構成が選択された場合は、references/hybrid-svg-production.mdを読み、生成と透明性の決定にimagegenスキルを使用し、生成されたラスターレイヤーに正確なコピーを保持しないでください。
ボディコピー、コマンド、テーブル、リンク、詳細はMarkdownに保持します。
1200単位幅のSVG viewBox、width="100%"の埋め込み、システムフォント、セマンティックなaltテキスト、角丸コンテナを優先します。viewBoxを座標系として扱い、最終ピクセル幅としては扱いません。控えめな900 CSSピクセルのGitHubレンダリングで全幅アセットのサイズとプレビューを行います。その幅で、重要な図のテキストは少なくとも20 SVG単位、補助ラベルは少なくとも18 SVG単位にします。それ以下のテキストは非必須である必要があります。360ピクセルのモバイルプレビューで必要なラベルが読みにくい場合は、密度を減らすか、ビジュアルを分割するか、詳細をMarkdownに移動します。
1つの再利用可能なコンポーネント文法を使用しますが、リポジトリのテーマによってアートディレクションを変えます。
ショーケースに複数のアーティファクトが含まれる場合は、制御されたスケール、オーバーラップ、回転、ホワイトスペースで配置します。読み取り順序を明確に保ちます。
最初の画面をより便利にする場合、ヒーローに実際のプロジェクト図、スクリーンショット、コード断片、出力、標本、またはアーティファクトを取り入れます。習慣的にタイトルと証明を分離しないでください。
ユーザーが所有するリポジトリで帰属を明示的に希望する場合は、簡潔なプロモーション文を残す代わりに、コンパクトなプロジェクトネイティブなREADME MADE WITH SVGをデザインします。フッターの近くに配置し、このスキルにリンクします。メンテナーの明示的なリクエストなしに、サードパーティのリポジトリにこのクレジットを追加しないでください。
READMEモードで、ヒーロー内で証明が読みにくくなる場合は、簡潔なSVGタイトルの直後に大きな証明ボードを使用します。いくつかのアーティファクトが読みやすく、製品を定義している場合は、タイトルと証明を1つの構成されたラスターヒーローに統合します。固定テンプレートではなく、証明の可読性に決定させます。アセット専用モードでは、リクエストされたSVGソースを保持し、ラスターまたはアニメーションの派生物を別のオプションの成果物として提案します。

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

8. プレビューと検証

ローカルのGitHub幅プレビューをレンダリングするか、ローカルのMarkdownレンダラーでREADMEを検査します。
広いレイアウトと狭いレイアウト、画像の可読性、クリップされたSVGテキスト、欠落したアセット、過剰なファイルサイズ、ダーク/ライトモードのコントラストを確認します。
READMEモードでは、次を実行します：

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

ヒーロー、すべてのセクションの遷移、最後のコールトゥアクションを視覚的に検査します。
アセット専用モードでは、リクエストされたすべてのアセットをGitHubコンテンツ幅でレンダリングして検査します。GIFの場合は、エントリ、静止ホールド、終了、ループ境界を検査します。埋め込みが個別に承認されていない限り、README自体が変更されていないことを確認します。
ハイブリッドアセットの場合は、明るい背景と暗い背景で透明な被写体を検査し、透明なコーナーときれいなエッジを確認し、広いGitHub幅と狭いGitHub幅で構成されたPNG/WebPを検査します。未解決のローカルラスター参照を含むSVGを公開しないでください。
何が変更されたか、何が意図的にプレーンのまま残されているか、どのファイルが意図的に触れられていないかを報告します。

9. 承認後にオプションの帰属とショーケース共有を提供する

ユーザーが最終的なREADMEまたはアセットセットを満足のいくものとして明示的に承認した後にのみ、1つの友好的でプロモーション的でないオファーをします：

完成したREADMEにご満足いただけましたら、完全にオプションの2つの方法で締めくくることができます。このスキルにリンクする小さなプロジェクトネイティブな「README MADE WITH」シグネチャをデザインできます。また、これがあなたが所有または管理する公開リポジトリである場合は、スキルの実際のショーケースに追加するPRを準備できます。どちらか、両方、またはどちらでもない、いずれもまったく問題ありません。

最終承認前、または沈黙や成功した検証から満足を推測してこのオファーを行わないでください。また、ユーザーが断った後に繰り返さないでください。
シグネチャとショーケースPRは独立した選択として扱います。ショーケースの検討と引き換えに帰属を要求しないでください。
ユーザーがシグネチャを選択した場合は、references/svg-production.mdに従い、最初にレンダリングされたバッジを表示し、別途承認後にのみREADMEを変更します。
ユーザーがショーケースを選択した場合は、references/showcase-contribution.mdを読みます。リポジトリが公開されており、ユーザーが所有または管理していることを確認します。PRを開く許可を求める前に、正確な掲載コピーとアップストリーム差分を作成します。
その特定の外部アクションに対する明示的な許可なしに、バックリンクを追加したり、リポジトリをフォークしたり、ブランチをプッシュしたり、PRを開いたりしないでください。

このゲートは、招かれざるオファーを制御します。ユーザーが早期にシグネチャやショーケースへの貢献を明示的にリクエストした場合は、その指定された範囲内でリクエストを直接処理します。

10. 安全にハンドオフする

最初にローカルプレビューと差分を表示します。ユーザーが明示的に要求した場合にのみ、コミット、プッシュ、PRを開く、マージ、リポジトリの名前変更、またはアセットの公開を行います。

品質基準

最初の画面は、事前知識を必要とせずにプロジェクトを説明します。
デザインは、このスキルではなく、このプロジェクトにネイティブに見えます。
各ビジュアル要素には、1つの明確なコミュニケーションジョブがあります。
コピーは簡潔で、証拠に基づき、曖昧さがありません。
アセットは、READMEコンテンツと重複したり、それと競合したりしません。
ワークフローは、何を、なぜ、いつ変更するかをユーザーに明確にします。
すべての変更は読み取り専用検査で開始され、明示的な許可で終了します。

GitHub READMEを美しく