shieldcn-badges

# shieldcn Badges Use [shieldcn](https://shieldcn.dev) to add beautiful shadcn/ui-styled badges, badge groups, charts, headers, sponsors grids, and contributor images to READMEs and docs. Base URL: `https://shieldcn.dev` ## Install this skill Install from the shieldcn repository with the Skills CLI: ```bash npx skills add jal-co/shieldcn ``` Useful variants: ```bash # Install globally instead of only the current project npx skills add jal-co/shieldcn --global # Install for a specific agent supported by the Skills CLI npx skills add jal-co/shieldcn --agent AGENT_NAME # Use once without installing npx skills use jal-co/shieldcn@shieldcn-badges ``` Verify installation: ```bash npx skills list ``` ## What to ask your agent Copy one of these prompts after installing the skill. Replace bracketed values with the real project details. ### Great badge rows ```text Add a polished shieldcn badge row to my README for [owner/repo]. Include npm version/downloads if this package is published as [package], GitHub stars, license, CI status, and last commit. Center the row, make badges clickable, and use a subtle shadcn style that works on GitHub light and dark themes. ``` ```text Replace the existing Shields.io badges in this README with shieldcn equivalents. Keep the same links where possible, remove stale or duplicate badges, and keep the final row to 3-6 high-signal badges. ``` ```text Migrate the existing Shields.io badges in this README to shieldcn, but undo any split-style/two-tone badges. Use single-surface shieldcn badges instead: remove split=true, labelColor, and other split-label styling unless a split badge is explicitly needed for readability. ``` ```text Create a compact shieldcn badge group for [owner/repo] with stars, license, contributors, and last commit. Use one grouped image when that is cleaner than separate badges. ``` ```text Add release-quality README badges for a TypeScript library named [package]. I want npm version, monthly downloads, license, types, GitHub stars, CI, and a small branded static badge if it improves the visual hierarchy. ``` ### Headers and hero sections ```text Design the top of my README using shieldcn: add an adaptive header banner for [project name], a one-sentence tagline, and a centered badge row. Use GitHub <picture> markup so the header and badges adapt to light/dark mode. ``` ```text Add a left-aligned shieldcn header to my README with title [title], subtitle [subtitle], logo [simple-icons slug], and a graph/grid style that fits a technical open-source project. ``` ### Charts and visual proof ```text Add a shieldcn star-history chart for [owner/repo] below the intro. Make it transparent so it blends into GitHub, and link it to the repository stargazers. ``` ```text Add a shieldcn npm download chart for [package] to the README. Use a concise caption and choose chart dimensions that work well on GitHub mobile. ``` ```text Add a shieldcn lifetime commit chart for [github username]. If multiple users are listed, compare them in one chart and explain what the chart shows. ``` ### Bigger README work ```text Improve this README's above-the-fold impression with shieldcn. Keep the content accurate, add a header, badges, and one chart only where they help, and avoid visual clutter. ``` ```text I want to generate a whole README visually. Point me to shieldcn README Studio and explain which blocks I should use for this project. ``` ## Agent workflow When this skill is loaded for a README/docs task: 1. Inspect the existing README and package metadata before editing. 2. Identify the project type: library, app, CLI, docs site, template, or skill. 3. Choose only high-signal badges. Default to 3-6 badges above the fold. 4. Use real values for `owner`, `repo`, package names, workflow names, and links. 5. Prefer SVG for Markdown images. Use PNG only when the target host blocks SVG. 6. Make badges clickable with `<a>` wrappers when they represent an external page. 7. Use `<p align="center">` for centered rows in GitHub READMEs. 8. Use GitHub `<picture>` markup when a header/chart/badge needs explicit light and dark URLs. 9. Avoid leaving placeholders in the user's README. Placeholders are fine only in examples or drafts. 10. If the user wants a full README rather than a few assets, suggest README Studio at `https://shieldcn.dev/studio`. ## URL basics ```text https://shieldcn.dev/{provider}/{...params}.svg SVG badge/image https://shieldcn.dev/{provider}/{...params}.png PNG badge/image https://shieldcn.dev/{provider}/{...params}.json raw resolved data https://shieldcn.dev/{provider}/{...params}/shields.json Shields.io-compatible JSON ``` Markdown patterns: ```md [](https://link)  ``` Adaptive GitHub pattern: ```md <p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/header/graph.svg?title=Acme&subtitle=Build+faster&logo=react&mode=dark" /> <img alt="Acme" src="https://shieldcn.dev/header/graph.svg?title=Acme&subtitle=Build+faster&logo=react&mode=light" /> </picture> </p> ``` ## Common badge endpoints ### GitHub Both route styles work: `/github/{topic}/{owner}/{repo}` and `/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`. ### Package registries | Badge | Endpoint | Example | |---|---|---| | npm version | `/npm/{package}` | `/npm/react` | | npm version tag | `/npm/v/{package}/{tag}` | `/npm/v/next/canary` | | npm weekly downloads | `/npm/dw/{package}` | `/npm/dw/react` | | npm monthly downloads | `/npm/dm/{package}` | `/npm/dm/react` | | npm yearly downloads | `/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` | | PyPI version | `/pypi/{package}` | `/pypi/flask` | | PyPI monthly downloads | `/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` | For npm scoped packages, keep the full scope: `/npm/v/@scope/package`. ### Social, quality, and skills | Badge | Endpoint | Example | |---|---|---| | Discord online | `/discord/{serverId}` | `/discord/1316199667142496307` | | Discord members 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 subscribers | `/youtube/subscribers/{channelId}` | `/youtube/subscribers/UCxxxxxx` | | Mastodon followers | `/mastodon/followers/{instance}/{acct}` | `/mastodon/followers/mastodon.social/Gargron` | | Hacker News karma | `/hackernews/{userId}` | `/hackernews/pg` | | 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` | | 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 skill rank | `/skills/trending/{owner}/{repo}/{skill}` | `/skills/trending/vercel-labs/agent-skills/vercel-react-best-practices` | | Hot skill rank | `/skills/hot/{owner}/{repo}/{skill}` | `/skills/hot/vercel-labs/agent-skills/vercel-react-best-practices` | ### Custom and grouped 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 a JSON endpoint | | Badge group | `/group/{badge1}+{badge2}.svg` | `/group/github/vercel/next.js/stars+github/vercel/next.js/license.svg` | Badge groups render several badges as one joined shadcn ButtonGroup-style image. Use them when a README row is visually busy or when the badges share one link. ## Badge styling options Append query params 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` | Explicit color mode |