add-badges

バッジを追加

一般的な README の編集に範囲を広げずに、README のバッジブロックを生成、更新します。

ディスパッチ

$ARGUMENTS	アクション
空	空の状態／ヘルプ用ギャラリーを表示し、対象のリポジトリまたは README のパスを尋ねます
フラグまたは自然言語によるバッジのリクエスト	バッジのワークフロー全体を実行します：検出 -> 選択 -> 提示 -> 挿入
任意のリクエストと --dry-run	プレビューまで実行し、ファイルの編集前に停止します
削除のみのリクエスト	検出をスキップし、既存のバッジブロックを確認して、削減後のセットを提示します

空の状態／ヘルプ用ギャラリー

$ARGUMENTS が空の場合、主な使用方法と例を表示します：

• /add-badges --profile active --dry-run
• /add-badges --include status,package --readme README.md
• /add-badges --replace --yes
• /add-badges remove social badges

主なフェーズと書き込みの境界を示します：

• リポジトリと既存のバッジの状態を検出します
• フラグと検出されたシグナルに基づいて、バッジとレイアウトを選択します
• 提案するブロックと差分の表示内容を提示します
• --yes が明示的に指定されていない限り、承認後にのみ挿入します

段階的な情報開示

• SKILL.md は、ルーティング、フェーズの順序、承認の境界、フラグの意味に焦点を絞ります。
• 実行のたびに references/badge-catalog-core.md を読み込みます。
• 基本以外のシグナルが検出された場合にのみ、references/badge-catalog-extended.md を読み込みます。
• レイアウト、形式固有の構文、またはダークモード出力が関係する場合にのみ、references/style-guide.md を読み込みます。
• リポジトリの検出には scripts/detect.py を使用し、検証が要求された場合は挿入後にのみ scripts/validate-badges.py を使用します。

内部フェーズ 1 — 検出

Bash ツールを使用して検出スクリプトを実行します：

uv run python skills/add-badges/scripts/detect.py <path>

JSON 出力を解析します。スクリプトは、リポジトリ情報、言語、パッケージマネージャー、フレームワーク、CI/CD、インフラストラクチャ、コード品質、テスト、ドキュメント、ライセンス、リリース、セキュリティ、コミュニティ、開発者ツール、データベース、モノレポのシグナル、既存のバッジを検出します。

スクリプトが失敗した場合（uv が利用できない、Python がない、スクリプトエラー、無効な JSON）、手動での検出に切り替えます：

• マニフェストファイル（pyproject.toml、package.json、go.mod、Cargo.toml など）を Glob で検索します
• .git/config を読み取るか、git remote get-url origin を実行して owner/repo を確認します
• .github/workflows/*.yml を Glob で検索し、CI バッジ候補を探します
• LICENSE の先頭行を読み取り、SPDX タイプを確認します
• Dockerfile、.pre-commit-config.yaml、codecov.yml などを確認します

内部フェーズ 2 — 選択

references/badge-catalog-core.md を読み込みます（常に）。検出結果に基本以外のシグナル（以下のいずれか：frameworks、infrastructure、code_quality の linters/formatters/type_checkers、docs、release、security、monorepo、databases、developer_tooling、community）が含まれる場合は、references/badge-catalog-extended.md を読み込みます。

レイアウト、順序、URL の規則については references/style-guide.md を読み込みます。

選択ルール：

• 静的なものより動的なエンドポイントを優先します。バージョン番号、カバレッジ率、ダウンロード数をハードコードしてはいけません
• Simple Icons のスラッグがあるすべてのバッジに ?logo={slug}&logoColor={white|black} を含めます
• README に既存のバッジがある場合は、そのスタイル（existing_badges.style）に合わせます。既定値は flat-square です
• プラットフォームが GitLab または Bitbucket の場合は、shields.io のプラットフォームパス（/gitlab/...、/bitbucket/...）を使用します
• --profile <name>：成熟度に応じてバッジをプリセット選択します。new（3-5 個のバッジ：ステータス、ライセンス、言語）、active（8-12 個：コア + 品質、コードスタイル、フレームワーク）、mature（12-18 個：開発者ツールを除くコア + 拡張すべて）、enterprise（15-20 個：OpenSSF を含む 16 カテゴリーすべて）。--include/--exclude より優先されます。プロファイルが指定されていない場合は、検出された機能に基づいて自動選択します
• バッジ数は 8-15 個を目標とし、表示用のスーパーグループで分類します：ステータス > 品質 > パッケージ > 技術スタック > ソーシャル

表示用スーパーグループ → カテゴリーの対応：

スーパーグループ	カテゴリ
ステータス	status
品質	quality, code-style, security
パッケージ	package, license
技術スタック	language, frameworks, infrastructure, docs, release, databases, monorepo, developer-tooling
ソーシャル	social, community

• バッジ URL のサービス／メトリックのパスを比較して、既存のバッジと重複しないようにします
• CI ステータスには、ネイティブのバッジ URL（例：github.com/{owner}/{repo}/actions/workflows/{file}/badge.svg）を優先します。プライベートリポジトリでも動作します。ワークフローが 5 つ以上あるリポジトリでは、CI／テストのワークフローを優先し、その他はフェーズ 3 でユーザーに選択してもらいます
• repo.visibility が "private" の場合は、requires: public-api とマークされたバッジをスキップし、ユーザーに警告します。CI にはネイティブ URL を、カバレッジにはサービスの直接 URL を優先します
• 既存のバッジが停止中のサービス（existing_badges.dead_services）を参照している場合は、その旨を示し、カタログ内の代替候補を提案します
• カスタムバッジのサポート：ユーザーがカタログにないバッジ（Discord サーバー、スポンサー、カスタム API）をリクエストした場合は、shields.io の静的バッジ API またはエンドポイントバッジ API（/badge/dynamic/json?url=...&query=...）を使って作成します。必要なパラメーターを確認します
• ユーザーが forthebadge.com 風の装飾的なバッジをリクエストした場合は、forthebadge.com API を使用します。注：forthebadge は装飾専用で、動的データは表示しません。大きく太字のスタイルで動的バッジを作成する場合は、shields.io の ?style=for-the-badge を使用します

フラグの処理：

• --include <categories>：指定したカテゴリのバッジのみを生成します（カンマ区切り）。カテゴリ名：status, quality, package, license, language, social, code-style, frameworks, infrastructure, docs, release, databases, monorepo, community, security, developer-tooling。--exclude とは併用できません。両方が指定された場合はエラーになります
• --exclude <categories>：指定したカテゴリをスキップします。カテゴリ名は --include と同じです。表示グループの別名も使用できます：tech-stack は language,frameworks,infrastructure,docs,release,databases,monorepo,developer-tooling に展開されます。--include とは併用できません
• --style <style>：バッジのスタイルを上書きします（flat, flat-square, plastic, for-the-badge, social）
• --layout <layout>：バッジの配置方法です。inline（デフォルト）、centered、grouped、table、collapsible を指定できます。collapsible は、サブグループ（Tech Stack、Social）を <details><summary> 要素で囲みます。15 個以上のバッジがある場合に最適です。style-guide.md を参照してください
• --readme <path>：自動検出された README ではなく、指定したファイルを対象にします
• --dark-mode：GitHub でテーマに応じたバッジを表示するため、<source media="(prefers-color-scheme: dark)"> を含む <picture> 要素を生成します。純粋な Markdown ではなく HTML を出力します
• --dry-run：ファイルを変更せずに、提案するバッジブロックと差分を出力します。プレビュー後に終了します
• --yes：ファイルを変更する前の承認プロンプトをスキップします
• --replace：マーカー内のコンテンツを置き換え、マーカー外に分散しているバッジもマーカーブロックにまとめます

内部フェーズ 3 — 提示

カテゴリ見出し付きでグループ化したプレビューを表示します。ユーザーが確認できるように、バッジは実際の [![alt](url)](link) 形式の Markdown としてレンダリングします。

既存のバッジを更新する場合の差分表示：

• [+] 新たに追加されるバッジ
• [=] 維持される既存のバッジ
• [-] 削除される既存のバッジ

マーカーの外に分散しているバッジがある場合は、その場所を示し、マーカーブロックにまとめるかどうかを確認します。

ユーザーが削除のみをリクエストした場合（例：「ソーシャルバッジを削除して」）、検出をスキップし、既存のバッジブロックを読み込み、指定されたバッジを削除して、更新後のブロックを提示します。

確定前に、バッジの並べ替え、追加、個別削除を提案します。自然言語での調整（「スターをライセンスの前に移動して」「フォークのバッジを削除して」「Discord バッジを追加して」など）を受け付けます。

ファイルを変更する前に承認を求めます。--yes が渡された場合は、承認をスキップします。--yes が指定されていても、不足している必須情報（owner/repo、ワークフローファイル名など）の確認は必ず行います。

--dry-run が指定された場合は、提案するブロックを出力し、ファイルを変更せずに終了します。

内部フェーズ 4 — 挿入

既存の / マーカーを探すか、新たに作成します。

承認済みバッジを表示グループ（ステータス、品質、パッケージ、技術スタック、ソーシャル）ごとにまとめて挿入します。グループ間には空行を入れます。マーカーブロック内に `` コメントを追加します。

挿入位置の優先順位：

1. 既存のマーカー（マーカー間の内容を置き換えます）
2. 最初の # タイトル 見出しの後
3. 見出しが見つからない場合はファイルの先頭

README が存在しない場合は、# {repo-name} 見出しを含む README を作成し、バッジを追加します。

--dark-mode の場合は、style-guide.md に従って各バッジを <picture> 要素で囲みます。

--replace は、マーカー外にある散在したバッジをマーカーブロックにまとめます。何を移動するかをユーザーに正確に示します。何も黙って削除しません。

マーカー外の手動作成コンテンツは保持します。

挿入後、必要に応じて Bash 経由で uv run python scripts/validate-badges.py <readme-path> を実行し、すべてのバッジ URL が有効な応答を返すか検証できます。壊れているバッジや応答が遅いバッジがあれば、ユーザーに報告します。

停止条件

次のいずれかに該当する場合は、書き込みを行わずに停止して確認します。

• 対象の README パスが不明確
• 動的バッジに必要なリポジトリ識別情報が不足している
• ワークフローファイル名またはバッジ固有のパラメーターが不足している
• ユーザーが書き込みを承認しておらず、--yes も指定されていない
• --replace により、ユーザーがまだ確認していない散在バッジの移動または統合が行われる

書き込み操作の場合：

• --dry-run はプレビューと差分を表示した時点で必ず停止します
• --yes が明示的に指定されていない限り、挿入前に承認を得る必要があります
• --yes が指定されても、必須情報の不足を無視することはできません
• README 内のマーカー以外のコンテンツはすべて保持し、要求された変更に README のより広範な編集が必要な場合は停止します

スタイルルール

既定のスタイルは flat-square です。バッジがすでにある場合は既存のスタイルに合わせます。ヒーローセクションやランディングセクションには for-the-badge を使用します。スター数やフォロー数のバッジには social スタイルを使用します。出力では表示グループ間に空行を入れます。

エラー処理

• Git リモートがない場合：owner/repo を確認します。ユーザーが指定を拒否した場合は、静的な言語／フレームワーク／ツールのバッジのみを生成します（リモートに依存するバッジは含めません）
• マニフェストファイルがない場合：静的バッジのみ
• README が RST／AsciiDoc の場合：適切な画像構文を使用します（形式ごとの構文は style-guide.md を参照）
• 既存のスタイルが混在している場合：統一を提案し、ユーザーにスタイルを確認します
• スタイルのみの変更（他の変更を伴わない --style）：現在のバッジ構成を保持し、スタイルパラメーターのみを更新します
• プライベートリポジトリを検出した場合：requires: public-api のバッジはスキップし、ネイティブのバッジ URL を優先して、ユーザーに警告します
• detect.py の結果が一部のみの場合：利用できる情報で作業し、不足しているセクションを伝えます

注意が必要なアイコンスラッグ

Simple Icons でよくある注意点：bash ではなく gnubash、node ではなく nodedotjs、vue ではなく vuedotjs、next ではなく nextdotjs、.env は dotenv、spring-boot ではなく springboot、fly ではなく flydotio です。注：nuxt は現在正しいスラッグです（以前は nuxtdotjs でした）。カタログにないアイコンには、小文字のブランド名を使用します。不明な場合は simpleicons.org で確認してください。

模範例

[![CI](https://github.com/{owner}/{repo}/actions/workflows/ci.yml/badge.svg)](https://github.com/{owner}/{repo}/actions)
[![PyPI](https://img.shields.io/pypi/v/{package}?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/{package}/)
[![License](https://img.shields.io/github/license/{owner}/{repo}?style=flat-square)](https://github.com/{owner}/{repo}/blob/main/LICENSE)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/{owner}/{repo}/badge)](https://scorecard.dev/viewer/?uri=github.com/{owner}/{repo})

参照ファイル一覧

ファイル	読むタイミング
references/badge-catalog-core.md	常に — 一般的なカテゴリの基本的なバッジ定義を提供します
references/badge-catalog-extended.md	検出結果に基本以外のシグナル（フレームワーク、インフラストラクチャ、リンター、ドキュメントなど）が含まれる場合
references/style-guide.md	レイアウト、順序、URL の規則、形式ごとの構文を判断する場合

標準用語

標準用語	意味
badge	プロジェクトのメタデータを表示する shields.io（または類似サービス）の画像要素
shield	badge の同義語。shields.io からレンダリングされる SVG
style	視覚的なバリエーション：flat、flat-square、plastic、for-the-badge、social
super-group	表示グループ：Status、Quality、Package、Tech Stack、Social
category	badge の種類の分類（例：ライセンス、言語、フレームワーク）
marker	badge ブロックを区切る HTML コメント（``）
slug	?logo= パラメーターで使用する Simple Icons の識別子（例：gnubash）
profile	プロジェクトの成熟度に応じた badge のプリセット選択：new、active、mature、enterprise
dynamic badge	エンドポイントからライブデータ（バージョン、カバレッジ、ダウンロード数）を取得する badge
static badge	テキストがハードコードされた badge。動的な代替手段がある場合は使用を避けてください

対象範囲

対象： badge の検出、選択、プレビュー、marker ブロック内への挿入、および badge に特化した README の更新。

対象外： README 全般の書き換え、より広範なドキュメント作業、CI/CD の設計、badge 以外のドキュメントの変更。

重要なルール

すべての badge 操作で必ず守る制約：

1. 動的な値をハードコードしないでください。 バージョン、カバレッジ、ダウンロード数には、必ず shields.io の動的エンドポイントを使用してください。
2. 必ずロゴパラメーターを含めてください。 Simple Icons の slug があるすべての badge に、?logo={slug}&logoColor={white|black} を指定してください。
3. 既存のスタイルを尊重してください。 README にすでにある badge のスタイルに合わせてください。badge がない場合に限り、デフォルトで flat-square を使用してください。
4. marker の外側にあるコンテンツを変更しないでください。 / marker の外側にある手動のコンテンツはすべて保持してください。
5. 書き込み前に必ず確認してください。 --yes が明示的に指定されていない限り、ユーザーの承認なしに README を変更しないでください。
6. アイコンの slug を慎重に確認してください。 Tricky Icon Slugs の一覧を使用し、不確かな場合は simpleicons.org で確認してください。
7. 非公開リポジトリと互換性のない badge はスキップしてください。 repo.visibility が "private" の場合、requires: public-api とマークされた badge は生成しないでください。