README Badges

Name: README Badges
Author: jal-co

By jal-co· jal-co/shieldcn· 0

Generate shadcn/ui-styled status badges for project documentation.

Installation

1
Make sure Claude is on your device and in your terminal.
Skills load from ~/.claude/skills/ when Claude Code starts up — so you need it on your machine first. If you don't have it yet, install it once with the command below, then run claude in any terminal to verify.
One-time setup
```
npm i -g @anthropic-ai/claude-code
```
Already have it? Skip ahead.

Paste into Claude Code or into your terminal.

Install

git clone ht•••••••••••••••••••••••••••••••••••• ••••••••••••••••••••• •• ••••• •• ••••••••••••••••••••••••••••••••••••••• •• •• •• •••••••••••••••••••••••••••••••••••••••••••••• ••••••••••••••••••••••••••••••••••••••••

This copies the whole skill folder into ~/.claude/skills/shieldcn-badges-jal-co/ — the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Safe default: works for every skill.

Faster alternative (instruction-only skills)

Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates — they won't be downloaded and the skill will fail when it tries to load them.

Quick install (SKILL.md only)

mkdir -p ~/.•••••••••••••••••••••••••••••••••••• •• •••• ••••• •••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• •• ••••••••••••••••••••••••••••••••••••••••••••••••

Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from ~/.claude/skills/). New skills are picked up on startup.
Just ask Claude.
Skills auto-activate when your request matches the skill's description — no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the “What this skill does” section above.

Prefer to read the source first? Open on GitHub.

When Claude uses it

Add beautiful shadcn/ui-styled README badges to projects using shieldcn. Use when adding badges, shields, or status indicators to README files, docs, or markdown. Triggers include "add badges", "add shields", "readme badges", "npm badge", "GitHub stars badge", "CI badge", "shieldcn", or any request to add project status badges to documentation.

What this skill does

shieldcn Badges

Add beautiful shadcn/ui-styled badges to READMEs and docs using shieldcn — a free, open-source shields.io alternative.

Base URL: https://shieldcn.dev

Badge URL format

https://shieldcn.dev/{provider}/{...params}.svg     → SVG (default, for READMEs)
https://shieldcn.dev/{provider}/{...params}.png     → PNG
https://shieldcn.dev/{provider}/{...params}.json    → raw data

Markdown pattern

[![alt](https://shieldcn.dev/{provider}/{params}.svg)](https://link)

<!-- or without link -->
![alt](https://shieldcn.dev/{provider}/{params}.svg)

Providers & endpoints

Package registries

Provider	Endpoint	Example
npm version	`/npm/{package}`	`/npm/react`
npm version (tag)	`/npm/v/{package}/{tag}`	`/npm/v/next/canary`
npm downloads/wk	`/npm/dw/{package}`	`/npm/dw/react`
npm downloads/mo	`/npm/dm/{package}`	`/npm/dm/react`
npm downloads/yr	`/npm/dy/{package}`	`/npm/dy/react`
npm total downloads	`/npm/dt/{package}`	`/npm/dt/react`
npm license	`/npm/license/{package}`	`/npm/license/react`
npm types	`/npm/types/{package}`	`/npm/types/react`
npm dependents	`/npm/dependents/{package}`	`/npm/dependents/react`
npm scoped	`/npm/v/@scope/pkg`	`/npm/v/@types/node`
PyPI version	`/pypi/{package}`	`/pypi/flask`
PyPI downloads/mo	`/pypi/dm/{package}`	`/pypi/dm/flask`
Crates.io version	`/crates/{crate}`	`/crates/serde`
Docker Hub pulls	`/docker/pulls/{image}`	`/docker/pulls/library/nginx`
JSR version	`/jsr/{@scope}/{name}`	`/jsr/@std/path`
Bundlephobia minzip	`/bundlephobia/minzip/{package}`	`/bundlephobia/minzip/react`
Homebrew version	`/homebrew/{formula}`	`/homebrew/node`
Maven version	`/maven/{groupId}/{artifactId}`	`/maven/org.apache.maven/maven-core`
Packagist version	`/packagist/v/{vendor}/{package}`	`/packagist/v/laravel/framework`
RubyGems version	`/rubygems/{gem}`	`/rubygems/rails`
NuGet version	`/nuget/{package}`	`/nuget/Newtonsoft.Json`
Pub.dev version	`/pub/{package}`	`/pub/flutter`
CocoaPods version	`/cocoapods/{pod}`	`/cocoapods/Alamofire`

GitHub

Both formats work: /github/{topic}/{owner}/{repo} or /github/{owner}/{repo}/{topic}

Badge	Endpoint	Example
Stars	`/github/stars/{owner}/{repo}`	`/github/stars/vercel/next.js`
Forks	`/github/forks/{owner}/{repo}`	`/github/forks/vercel/next.js`
License	`/github/license/{owner}/{repo}`	`/github/license/vercel/next.js`
Release	`/github/release/{owner}/{repo}`	`/github/release/vercel/next.js`
CI status	`/github/ci/{owner}/{repo}`	`/github/ci/vercel/next.js`
Issues	`/github/issues/{owner}/{repo}`	`/github/issues/vercel/next.js`
Open PRs	`/github/open-prs/{owner}/{repo}`	`/github/open-prs/vercel/next.js`
Contributors	`/github/contributors/{owner}/{repo}`	`/github/contributors/vercel/next.js`
Last commit	`/github/last-commit/{owner}/{repo}`	`/github/last-commit/vercel/next.js`
Watchers	`/github/watchers/{owner}/{repo}`	`/github/watchers/vercel/next.js`
Downloads	`/github/dt/{owner}/{repo}`	`/github/dt/vercel/next.js`
Dependabot	`/github/dependabot/{owner}/{repo}`	`/github/dependabot/vercel/next.js`

CI supports ?workflow=name&branch=main query params.

Social

Provider	Endpoint	Example
Discord online	`/discord/{serverId}`	`/discord/1316199667142496307`
Discord by invite	`/discord/members/{inviteCode}`	`/discord/members/nextjs`
Reddit subscribers	`/reddit/subscribers/r/{subreddit}`	`/reddit/subscribers/r/reactjs`
Bluesky followers	`/bluesky/followers/{handle}`	`/bluesky/followers/bsky.app`
YouTube subs	`/youtube/subscribers/{channelId}`	`/youtube/subscribers/UCxxxxxx`
Mastodon followers	`/mastodon/followers/{instance}/{acct}`	`/mastodon/followers/mastodon.social/Gargron`
Hacker News karma	`/hackernews/{userId}`	`/hackernews/pg`

Code quality

Provider	Endpoint	Example
Codecov	`/codecov/{service}/{owner}/{repo}`	`/codecov/gh/vercel/next.js`
VS Code installs	`/vscode/installs/{publisher}/{ext}`	`/vscode/installs/esbenp/prettier-vscode`
WakaTime	`/wakatime/{username}`	`/wakatime/@user`

Agent skills (skills.sh)

Addressed as {owner}/{repo}/{skill} — the GitHub repo (skills.sh source) plus the skill slug.

Badge	Endpoint	Example
Skill installs	`/skills/installs/{owner}/{repo}/{skill}`	`/skills/installs/vercel-labs/agent-skills/vercel-react-best-practices`
Skill rank	`/skills/rank/{owner}/{repo}/{skill}`	`/skills/rank/vercel-labs/agent-skills/vercel-react-best-practices`
Trending rank	`/skills/trending/{owner}/{repo}/{skill}`	`/skills/trending/vercel-labs/agent-skills/vercel-react-best-practices`
Hot rank	`/skills/hot/{owner}/{repo}/{skill}`	`/skills/hot/vercel-labs/agent-skills/vercel-react-best-practices`

Custom badges

Type	Endpoint	Example
Static	`/badge/{label}-{message}-{color}`	`/badge/build-passing-brightgreen`
Dynamic JSON	`/badge/dynamic/json?url=...&query=...`	Fetch any JSON API
HTTPS endpoint	`/https/{hostname}/{path}`	Proxy any JSON endpoint

Query parameters

Append to any badge URL as ?key=value&key2=value2.

Param	Values	Default	Notes
`variant`	`default`, `secondary`, `outline`, `ghost`, `destructive`, `branded`	`default`	shadcn Button variant
`size`	`xs`, `sm`, `default`, `lg`	`sm`	Badge size
`mode`	`dark`, `light`	`dark`	Color mode
`split`	`true`, `false`	`false`	Two-tone label/value split
`logo`	SimpleIcons slug, `ri:Name`, `false`	auto	Icon source
`logoColor`	hex (no `#`)	auto	Icon color
`label`	string	auto	Override label text
`color`	hex (no `#`)	—	Background color
`labelColor`	hex (no `#`)	—	Label side bg (split mode)
`theme`	`zinc`, `slate`, `blue`, `green`, `rose`, `orange`, `violet`	—	Color theme
`font`	`inter`, `geist`, `geist-mono`	`inter`	Font family
`statusDot`	`true`, `false`	auto for CI	Show status indicator dot

Common recipes

Typical README badge row

<p align="center">
  <a href="https://www.npmjs.com/package/{pkg}"><img src="https://shieldcn.dev/npm/{pkg}.svg" alt="npm" /></a>
  <a href="https://github.com/{owner}/{repo}/stargazers"><img src="https://shieldcn.dev/github/stars/{owner}/{repo}.svg" alt="stars" /></a>
  <a href="https://github.com/{owner}/{repo}"><img src="https://shieldcn.dev/github/license/{owner}/{repo}.svg" alt="license" /></a>
  <a href="https://github.com/{owner}/{repo}/actions"><img src="https://shieldcn.dev/github/ci/{owner}/{repo}.svg" alt="CI" /></a>
</p>

Secondary variant (lighter)

![badge](https://shieldcn.dev/npm/react.svg?variant=secondary)

Branded variant (brand-colored bg)

![badge](https://shieldcn.dev/npm/react.svg?variant=branded)

Split badge (two-tone)

![badge](https://shieldcn.dev/npm/react.svg?split=true)

Light mode

![badge](https://shieldcn.dev/npm/react.svg?mode=light)

Custom icon

![badge](https://shieldcn.dev/npm/react.svg?logo=typescript)
![badge](https://shieldcn.dev/github/stars/owner/repo.svg?logo=ri:GoStarFill)

No icon

![badge](https://shieldcn.dev/npm/react.svg?logo=false)

Rules

Always use .svg for markdown images (best quality, smallest size)
Use <a> wrapper to make badges clickable links
Use <p align="center"> to center badge rows in GitHub READMEs
Replace {owner}, {repo}, {package} with actual values — never leave placeholders
Default variant (default) works on both light and dark GitHub themes
Icons are auto-resolved per provider — only set ?logo= to override
For npm scoped packages, use the full scope: /npm/v/@scope/package
Prefer variant=secondary for subtle badge rows
Keep badge rows to 3–6 badges for readability
Link each badge to its relevant page (npm registry, GitHub stars page, etc.)