add-badges

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phase 1 — Detect

第一阶段 — 检测

Run the detection script via the Bash tool:

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

Parse the JSON output. The script detects: repo info, languages, package managers, frameworks, CI/CD, infrastructure, code quality, testing, docs, license, release, security, community, developer tooling, databases, monorepo signals, and existing badges.

If the script fails (uv unavailable, Python missing, script error, invalid JSON), fall back to manual detection:

Glob for manifest files (pyproject.toml, package.json, go.mod, Cargo.toml, etc.)
Read
```
.git/config
```
or run
```
git remote get-url origin
```
for owner/repo
Glob
```
.github/workflows/*.yml
```
for CI badge candidates
Read LICENSE first line for SPDX type
Check for Dockerfile, .pre-commit-config.yaml, codecov.yml, etc.

通过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等文件

Phase 2 — Select

第二阶段 — 选择

Read

references/badge-catalog-core.md

(always). Read

references/badge-catalog-extended.md

when detection reports any non-basic signals (any of: frameworks, infrastructure, code_quality linters/formatters/type_checkers, docs, release, security, monorepo, databases, developer_tooling, community).

Read

references/style-guide.md

for layout, ordering, and URL conventions.

Selection rules:

Prefer dynamic endpoints over static — never hardcode version numbers, coverage %, download counts
Include
```
?logo={slug}&logoColor={white|black}
```
on every badge with a Simple Icons slug
Match existing badge style if README already has badges (from
```
existing_badges.style
```
); default to
```
flat-square
```
If platform is GitLab or Bitbucket, use shields.io platform paths (
```
/gitlab/...
```
,
```
/bitbucket/...
```
)
```
--profile <name>
```
: preset badge selection by maturity.
```
new
```
(3-5 badges: status, license, language),
```
active
```
(8-12: core + quality, code-style, frameworks),
```
mature
```
(12-18: core + all extended except developer-tooling),
```
enterprise
```
(15-20: ALL 16 categories including OpenSSF). Overrides
```
--include
```
/
```
--exclude
```
. No profile = auto-select based on detected features
Target 8-15 badges; group by display super-groups: Status > Quality > Package > Tech Stack > Social

Display super-group → category mapping:

Super-group	Categories
Status	status
Quality	quality, code-style, security
Package	package, license
Tech Stack	language, frameworks, infrastructure, docs, release, databases, monorepo, developer-tooling
Social	social, community

Deduplicate against existing badges by comparing badge URL service/metric paths
For CI status: prefer native badge URL (e.g.,
```
github.com/{owner}/{repo}/actions/workflows/{file}/badge.svg
```
) — works for private repos. For repos with 5+ workflows, prioritize CI/test workflows; let user select others in Phase 3
If
```
repo.visibility
```
is
```
"private"
```
, skip badges marked
```
requires: public-api
```
and warn user. Prefer native URLs for CI and direct service URLs for coverage
If existing badges reference dead services (from
```
existing_badges.dead_services
```
), flag them and suggest catalog replacements
Custom badge support: if user requests a badge not in the catalog (Discord server, sponsor, custom API), construct from shields.io static badge API or endpoint badge API (
```
/badge/dynamic/json?url=...&query=...
```
). Ask for required params
If user requests forthebadge.com-style decorative badges, use forthebadge.com API. Note: forthebadge is decorative only — no dynamic data. For dynamic badges in large bold style, use shields.io
```
?style=for-the-badge
```

Flag handling:

```
--include <categories>
```
: only generate badges from named categories (comma-separated). Category names: status, quality, package, license, language, social, code-style, frameworks, infrastructure, docs, release, databases, monorepo, community, security, developer-tooling. Mutually exclusive with
--exclude
— error if both provided
```
--exclude <categories>
```
: skip named categories. Same names as
```
--include
```
. Also accepts display group alias:
```
tech-stack
```
expands to language,frameworks,infrastructure,docs,release,databases,monorepo,developer-tooling. Mutually exclusive with
--include
```
--style <style>
```
: override badge style (flat, flat-square, plastic, for-the-badge, social)
```
--layout <layout>
```
: badge arrangement — inline (default), centered, grouped, table, collapsible.
```
collapsible
```
wraps secondary groups (Tech Stack, Social) in
```
<details><summary>
```
elements — ideal for 15+ badges. See style-guide.md
```
--readme <path>
```
: target a specific file instead of auto-detected README
```
--dark-mode
```
: generate
```
<picture>
```
elements with
```
<source media="(prefers-color-scheme: dark)">
```
for theme-aware badges on GitHub. Produce HTML instead of pure markdown
```
--dry-run
```
: output proposed badge block and diff without modifying any file. Exit after preview
```
--yes
```
: skip approval prompt before modifying files
```
--replace
```
: replace content within markers AND consolidate scattered badges into the marker block

务必阅读

references/badge-catalog-core.md

。当检测到非基础信号（包括但不限于：框架、基础设施、代码质量检查工具/格式化工具/类型检查器、文档、版本发布、安全、单体仓库、数据库、开发者工具、社区）时，需额外阅读

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个：核心类别 + 所有扩展类别，除开发者工具外）、
```
enterprise
```
（15-20个：包含OpenSSF在内的全部16个类别）。该参数会覆盖
```
--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/测试工作流；剩余工作流可在第三阶段由用户选择
如果
```
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
```
会将次要分组（技术栈、社区）包裹在
```
<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 — Present

第三阶段 — 展示

Show grouped preview with category headers. Render badges as actual

[![alt](url)](link)

markdown so the user can see them.

Diff indicators when updating existing badges:

```
[+]
```
new badge being added
```
[=]
```
existing badge being kept
```
[-]
```
existing badge being removed

If scattered badges exist outside markers, show their locations and offer to consolidate into the marker block.

If user requests removal only (e.g., "remove social badges"), skip detection, read existing badge block, remove specified badges, present updated block.

Offer to reorder, add, or remove individual badges before finalizing. Accept natural language adjustments ("move stars before license", "drop the forks badge", "add a Discord badge").

Ask for approval before modifying files. Skip approval if

--yes

passed. Never skip prompts for missing required info (owner/repo, workflow file names, etc.) even with

--yes

--dry-run

, output the proposed block and exit without modifying files.

按类别分组展示预览，每个分组带有类别标题。将徽章渲染为实际的

[![alt](url)](link)

Markdown格式，以便用户直观查看。

更新现有徽章时使用差异标识：

```
[+]
```
表示即将添加的新徽章
```
[=]
```
表示保留现有徽章
```
[-]
```
表示即将移除的现有徽章

如果存在分散在标记外的徽章，需展示其位置并提议将其整合到标记块中。

如果用户仅请求移除操作（例如“移除社区类徽章”），跳过检测步骤，直接读取现有徽章块，移除指定徽章后展示更新后的内容。

在最终确认前，允许用户调整徽章顺序、添加或移除单个徽章。支持自然语言指令（例如“将星标徽章移到许可证徽章之前”、“移除forks徽章”、“添加Discord徽章”）。

修改文件前需征得用户同意。若传递了

--yes

参数则跳过确认。即使使用
--yes
，若缺少必要信息（如仓库所有者/仓库名、工作流文件名等），也必须提示用户补充，不得跳过。

如果使用

--dry-run

参数，输出拟添加的徽章块后直接退出，不修改任何文件。

Phase 4 — Insert

第四阶段 — 插入

Find existing

<!-- BADGES:START -->

<!-- BADGES:END -->

markers or create them.

Insert approved badges grouped by display super-group (Status, Quality, Package, Tech Stack, Social). Separate groups with a blank line. Add

<!-- generated by add-badges YYYY-MM-DD -->

comment inside the marker block.

Insertion point priority:

Existing markers (replace content between them)
After first
```
# Title
```
heading
Top of file if no heading found

If no README exists, create one with

# {repo-name}

heading then add badges.

--dark-mode

, wrap each badge in

<picture>

elements per style-guide.md.

--replace

consolidates any scattered badges found outside markers into the marker block. Show user exactly what will be moved — nothing silently deleted.

Preserve any manual content outside markers.

After insertion, optionally run

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

via Bash to verify all badge URLs return valid responses. Report any broken or slow badges to the user.

查找现有的

<!-- BADGES:START -->

<!-- BADGES:END -->

标记，若不存在则创建。

按展示分组（状态、质量、包管理、技术栈、社区）插入已确认的徽章。分组之间用空行分隔。在标记块内添加

<!-- generated by add-badges YYYY-MM-DD -->

注释。

插入优先级：

现有标记（替换标记之间的内容）
第一个
```
# 标题
```
之后
若未找到标题，则插入到文件顶部

如果README不存在，创建一个带有

# {repo-name}

标题的README，然后添加徽章。

如果使用

--dark-mode

参数，按照style-guide.md的要求将每个徽章包裹在

<picture>

元素中。

--replace

参数会将所有分散在标记外的徽章整合到标记块中。需向用户展示具体要移动的内容——不得静默删除任何内容。

保留标记外的所有手动编写内容。

插入完成后，可选择通过Bash运行

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

以验证所有徽章URL是否有效。若存在无效或加载缓慢的徽章，需向用户报告。

Style Rules

样式规则

Default style:

flat-square

. Match existing style if badges already present. Use

for-the-badge

for hero/landing sections. Use

social

style for star/follow count badges. Separate display groups with a blank line in the output.

默认样式：

flat-square

。如果已存在徽章，需匹配现有样式。在首页/着陆页使用

for-the-badge

样式。星标/关注数徽章使用

social

样式。输出中各个展示分组之间用空行分隔。

Error Handling

错误处理

No git remote: prompt for
```
owner/repo
```
. If user declines, generate only static language/framework/tooling badges (no remote-dependent badges)
No manifest files: static-only badges
RST/AsciiDoc README: use appropriate image syntax (see style-guide.md for format-specific syntax)
Mixed existing styles: recommend standardizing, ask user which style
Style-only change (
```
--style
```
with no other changes): preserve current badge set, update style param only
Private repo detected: skip
```
requires: public-api
```
badges, prefer native badge URLs, warn user
detect.py produces partial results: work with what is available, note missing sections

无Git远程仓库：提示用户输入
```
owner/repo
```
。若用户拒绝，仅生成静态的语言/框架/工具徽章（不生成依赖远程仓库的徽章）
无清单文件：仅生成静态徽章
README为RST/AsciiDoc格式：使用对应的图片语法（详见style-guide.md中的格式特定语法）
现有徽章样式不统一：建议标准化样式，并询问用户选择哪种样式
仅修改样式（使用
```
--style
```
参数且无其他变更）：保留当前徽章集，仅更新样式参数
检测到私有仓库：跳过标记为
```
requires: public-api
```
的徽章，优先使用原生徽章URL，并向用户发出警告
detect.py返回部分结果：基于已有内容继续操作，并告知用户缺少的部分

Tricky Icon Slugs

易混淆图标标识（Slug）

Common Simple Icons gotchas:

gnubash

not

bash

nodedotjs

not

node

vuedotjs

not

vue

nextdotjs

not

next

.env

dotenv

springboot

not

spring-boot

flydotio

not

fly

. Note:

nuxt

is now correct (was

nuxtdotjs

). For icons not in the catalog, use lowercase brand name; check simpleicons.org if unsure.

常见的Simple Icons易混淆标识：

gnubash

而非

bash

、

nodedotjs

而非

node

、

vuedotjs

而非

vue

、

nextdotjs

而非

next

、

.env

对应

dotenv

、

springboot

而非

spring-boot

、

flydotio

而非

fly

。注意：

nuxt

现在为正确标识（之前为

nuxtdotjs

）。如果图标不在目录中，使用小写品牌名；不确定时请查阅simpleicons.org。

Golden Example

最佳示例

markdown

<!-- BADGES:START -->
<!-- generated by add-badges 2025-01-15 -->
[![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})
<!-- BADGES:END -->

markdown

<!-- BADGES:START -->
<!-- generated by add-badges 2025-01-15 -->
[![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})
<!-- BADGES:END -->

Reference File Index

参考文件索引

File	Read When
`references/badge-catalog-core.md`	Always — provides base badge definitions for common categories
`references/badge-catalog-extended.md`	Detection reports non-basic signals (frameworks, infrastructure, linters, docs, etc.)
`references/style-guide.md`	Determining layout, ordering, URL conventions, and format-specific syntax

文件	读取时机
`references/badge-catalog-core.md`	始终需要读取——提供常见类别的基础徽章定义
`references/badge-catalog-extended.md`	检测到非基础信号（框架、基础设施、代码检查工具、文档等）时
`references/style-guide.md`	确定布局、排序、URL约定和格式特定语法时

Canonical Vocabulary

标准术语表

Canonical Term	Meaning
badge	A shields.io (or similar) image element displaying project metadata
shield	Synonym for badge; the rendered SVG from shields.io
style	Visual variant: flat, flat-square, plastic, for-the-badge, social
super-group	Display grouping: Status, Quality, Package, Tech Stack, Social
category	Classification of a badge type (e.g., license, language, frameworks)
marker	HTML comments ( `<!-- BADGES:START/END -->` ) delimiting the badge block
slug	Simple Icons identifier used in `?logo=` parameter (e.g., `gnubash` )
profile	Preset badge selection by project maturity: new, active, mature, enterprise
dynamic badge	Badge that fetches live data from an endpoint (version, coverage, downloads)
static badge	Badge with hardcoded text — avoid when a dynamic alternative exists

标准术语	含义
badge	由shields.io（或类似服务）生成的图片元素，用于展示项目元数据
shield	badge的同义词；shields.io生成的SVG渲染图
style	视觉变体：flat、flat-square、plastic、for-the-badge、social
super-group	展示分组：状态、质量、包管理、技术栈、社区
category	徽章类型分类（例如许可证、语言、框架）
marker	用于界定徽章块的HTML注释（ `<!-- BADGES:START/END -->` ）
slug	用于 `?logo=` 参数的Simple Icons标识符（例如 `gnubash` ）
profile	按项目成熟度预设的徽章选择方案：new、active、mature、enterprise
dynamic badge	从端点获取实时数据的徽章（如版本、覆盖率、下载量）
static badge	带有硬编码文本的徽章——有动态替代方案时请避免使用

Critical Rules

核心规则

Non-negotiable constraints for every badge operation:

Never hardcode dynamic values. Always use shields.io dynamic endpoints for versions, coverage, and download counts.
Always include logo parameters. Every badge with a Simple Icons slug must have
```
?logo={slug}&logoColor={white|black}
```
.
Respect existing style. Match the style of badges already present in the README; default to
```
flat-square
```
only when no badges exist.
Never modify content outside markers. Preserve all manual content outside
```

```
/
```

```
markers.
Always ask before writing. Never modify the README without user approval unless
```
--yes
```
was explicitly passed.
Check icon slugs carefully. Use the Tricky Icon Slugs list; verify against simpleicons.org when uncertain.
Skip private-incompatible badges. When
```
repo.visibility
```
is
```
"private"
```
, never generate badges marked
```
requires: public-api
```
.

所有徽章操作必须遵守以下不可协商的约束：

绝不硬编码动态值。版本、覆盖率和下载量必须使用shields.io的动态端点获取。
始终添加图标参数。每个带有Simple Icons标识（slug）的徽章必须包含
```
?logo={slug}&logoColor={white|black}
```
参数。
遵循现有样式。匹配README中已存在的徽章样式；仅当无现有徽章时默认使用
```
flat-square
```
。
绝不修改标记外的内容。保留
```

```
/
```

```
标记之外的所有手动编写内容。
修改前必须确认。除非明确传递
```
--yes
```
参数，否则修改README前必须征得用户同意。
仔细检查图标标识。参考“易混淆图标标识”列表；不确定时请验证simpleicons.org。
跳过私有仓库不兼容的徽章。当
```
repo.visibility
```
为
```
"private"
```
时，绝不生成标记为
```
requires: public-api
```
的徽章。