Phase 1 — Detect

Run the detection script via the Bash tool:

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

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.

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

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

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

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

安装