readme-badger

readme-badger

Badge design and selection knowledge base for AI documentation agents. This skill provides the decision logic, URL patterns, icon slugs, layout templates, and project-type recommendations needed to choose the right badges for the right context. It is not a badge insertion tool -- it is the knowledge an agent needs to produce correct, well-designed badge markup on the first pass.

SOURCE: Research synthesized from shields.io, Simple Icons, and conventions observed in major open-source repositories (accessed 2026-03-03).

Badge URL Pattern

All shields.io static badges follow this URL structure:

https://img.shields.io/badge/{LABEL}-{MESSAGE}-{COLOR}

Three encoding rules apply within the path segment:

Input	Output
_ (single underscore)	Space
__ (double underscore)	Literal underscore _
-- (double dash)	Literal dash -

Building a Badge Step by Step

Goal: a badge reading "Claude Code | compatible" in Anthropic orange with a Claude logo.

1. Label: Claude Code -- encode spaces as underscores: Claude_Code
2. Message: compatible
3. Color: Anthropic brand orange D97757
4. Assemble path: Claude_Code-compatible-D97757
5. Add logo: ?logo=claude&logoColor=white
6. Full URL:

https://img.shields.io/badge/Claude_Code-compatible-D97757?logo=claude&logoColor=white

1. Wrap in Markdown with link:

[![Claude Code](https://img.shields.io/badge/Claude_Code-compatible-D97757?logo=claude&logoColor=white)](https://claude.ai/code)

For the complete query parameter reference (style, logo, logoColor, logoSize, label, labelColor, color, cacheSeconds, link), see Shields.io API Reference.

Style Selection

flowchart TD
    Start([Choose badge style]) --> Q1{Badge purpose?}
    Q1 -->|Hero / project identity| FTB["for-the-badge<br>28px tall, uppercase, bold"]
    Q1 -->|Tech stack / metadata row| FS["flat-square<br>20px tall, sharp corners"]
    Q1 -->|General purpose / default| F["flat<br>20px tall, subtle gradient"]
    Q1 -->|GitHub social proof| S["social<br>20px tall, count-bubble look"]
    Q1 -->|Legacy project, existing style| P["plastic<br>18px tall, glossy pill"]
    FTB --> Apply["Append ?style=for-the-badge"]
    FS --> Apply2["Append ?style=flat-square"]
    F --> Apply3["No parameter needed (default)"]
    S --> Apply4["Append ?style=social"]
    P --> Apply5["Append ?style=plastic"]