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、基础设施、代码质量、测试、文档、许可证、发布、安全、社区、开发者工具、数据库、monorepo 信号和现有徽章。

如果脚本失败（uv 不可用、缺少 Python、脚本错误、JSON 无效），则改为手动检测：

• 搜索清单文件（pyproject.toml、package.json、go.mod、Cargo.toml 等）
• 读取 .git/config 或运行 git remote get-url origin 获取所有者／仓库
• 搜索 .github/workflows/*.yml，查找 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。

读取 references/style-guide.md，了解布局、排序和 URL 约定。

选择规则：

• 优先使用动态端点，而非静态端点——绝不硬编码版本号、覆盖率百分比或下载次数
• 每个带有 Simple Icons slug 的徽章都应包含 ?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 个：核心 + 除 developer-tooling 以外的所有扩展类别）、enterprise（15-20 个：全部 16 个类别，包括 OpenSSF）。覆盖 --include/--exclude。未指定 profile 时，根据检测到的功能自动选择
• 目标为 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/测试工作流；其他工作流留待用户在 Phase 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：生成带有 <source media="(prefers-color-scheme: dark)"> 的 <picture> 元素，以便 GitHub 上的徽章适配主题。生成 HTML，而非纯 Markdown
• --dry-run：输出拟议的徽章块和差异，不修改任何文件。预览后退出
• --yes：修改文件前跳过审批提示
• --replace：替换标记范围内的内容，并将分散的徽章整合到标记块中

内部 Phase 3 — 展示

按分组显示预览，并添加类别标题。将徽章渲染为实际的 [![alt](url)](link) Markdown，以便用户查看。

更新现有徽章时使用以下差异标记：

• [+] 新增的徽章
• [=] 保留的现有徽章
• [-] 移除的现有徽章

如果标记范围外存在分散的徽章，则显示其位置，并询问是否将其整合到标记块中。

如果用户仅请求移除徽章（例如“移除社交徽章”），则跳过检测，读取现有徽章块，移除指定徽章，并展示更新后的块。

在完成前，允许用户调整顺序、添加或移除单个徽章。接受自然语言调整（“将 stars 移到 license 前面”、“删除 forks 徽章”、“添加 Discord 徽章”）。

修改文件前，先征求用户批准。如果传入 --yes，则跳过审批。即使传入 --yes，也绝不能跳过对缺少必要信息的询问（owner/repo、工作流文件名等）。

如果传入 --dry-run，则输出拟议的徽章块并退出，不修改文件。

内部阶段 4 — 插入

查找现有的 / 标记，或创建标记。

按显示超组（状态、质量、软件包、技术栈、社交）分组插入已批准的徽章。组间空一行。在标记块内添加 `` 注释。

插入位置优先级：

1. 现有标记（替换标记之间的内容）
2. 第一个 # Title 标题之后
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。如果已有徽章，则匹配现有样式。Hero/落地页区域使用 for-the-badge。星标/关注者数量徽章使用 social 样式。输出中的显示组之间空一行。

错误处理

• 没有 git 远程地址：提示用户提供 owner/repo。如果用户拒绝，则仅生成静态语言/框架/工具徽章（不包含依赖远程信息的徽章）
• 没有清单文件：仅生成静态徽章
• README 使用 RST/AsciiDoc：使用相应的图片语法（格式专用语法见 style-guide.md）
• 现有样式混杂：建议统一，并询问用户选择哪种样式
• 仅更改样式（使用 --style 且没有其他更改）：保留当前徽章集合，仅更新样式参数
• 检测到私有仓库：跳过 requires: public-api 徽章，优先使用原生徽章 URL，并警告用户
• detect.py 仅产生部分结果：使用已有内容，并说明缺失的部分

易错的图标别名

Simple Icons 中常见的易错项：gnubash 而不是 bash，nodedotjs 而不是 node，vuedotjs 而不是 vue，nextdotjs 而不是 next，.env 对应 dotenv，springboot 而不是 spring-boot，flydotio 而不是 fly。注意：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	显示分组：状态、质量、软件包、技术栈、社交
category	badge 类型的分类（例如许可证、语言、框架）
marker	用于界定 badge 区块的 HTML 注释（``）
slug	?logo= 参数中使用的 Simple Icons 标识符（例如 gnubash）
profile	按项目成熟度预设的 badge 选择：new、active、mature、enterprise
dynamic badge	从端点获取实时数据的 badge（版本、覆盖率、下载量）
static badge	文本硬编码的 badge——存在动态替代项时应避免使用

范围界定

适用范围： badge 检测、badge 选择、badge 预览、在 marker 区块内插入 badge，以及针对 badge 的 README 更新。

不适用范围： 常规 README 改写、更广泛的文档工作、CI/CD 设计或非 badge 文档更改。

关键规则

每次 badge 操作都必须遵守以下约束：

1. 绝不硬编码动态值。 版本、覆盖率和下载量始终使用 shields.io 动态端点。
2. 始终包含 logo 参数。 每个带有 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。