# shieldcn-badges

Adopt this skill: https://proskills.md/skills/other/jal-co-shieldcn-skills-shieldcn-badges

Page: https://proskills.md/skills/other/jal-co-shieldcn-skills-shieldcn-badges
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/shieldcn-badges/SKILL.md
size: 8000
upstream: https://github.com/jal-co/shieldcn/blob/main/skills/shieldcn-badges/SKILL.md

````text
---
name: shieldcn-badges
description: Create polished shieldcn README badges, badge groups, charts, headers, sponsors grids, and full README hero sections. Use when a user wants shadcn/ui-styled badges, Shields.io replacement, npm/GitHub/CI/status badges, download charts, README header banners, contributor/sponsor images, or README Studio guidance. Triggers include "add badges", "add shields", "README badges", "npm badge", "GitHub stars badge", "CI badge", "download chart", "README header", "README banner", "contributors grid", "sponsors grid", "build a README", "README Studio", "shieldcn", and requests to make a project README look better.
metadata:
  author: jal-co
  version: "1.0.0"
---

# 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 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
[![alt](https://shieldcn.dev/{provider}/{params}.svg)](https://link)

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

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}
````

## File: README.md
upstream: https://github.com/jal-co/shieldcn/blob/main/README.md

````text
<p align="center">
  <picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/header/graph.svg?title=shieldcn&amp;subtitle=EVERYTHING+for+your+readme&amp;logo=shieldcn&amp;logoColor=848484&amp;mode=dark&amp;align=left&amp;font=geist-mono&amp;border=false" /><img alt="shieldcn" src="https://shieldcn.dev/header/graph.svg?title=shieldcn&amp;subtitle=EVERYTHING+for+your+readme&amp;logo=shieldcn&amp;logoColor=848484&amp;mode=light&amp;align=left&amp;font=geist-mono&amp;border=false" /></picture>
</p>

<div align="center">

Before anyone reaches your docs, they land on your README, the front door of every open-source project. **shieldcn** makes that first impression count: badges, charts, headers, and sponsor walls, rendered as real [shadcn/ui](https://ui.shadcn.com) components. A [shields.io](https://shields.io) alternative.

<div align="center">

[Homepage](https://shieldcn.dev) · [Docs](https://shieldcn.dev/docs) · [Studio](https://shieldcn.dev/studio) · [𝕏](https://x.com/jalcowastaken)

</div>

</div>

<p align="center">
  <a href="https://github.com/jal-co/shieldcn"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/group/github/jal-co/shieldcn/stars+github/jal-co/shieldcn/license+github/jal-co/shieldcn/contributors+github/jal-co/shieldcn/last-commit.svg?variant=branded&amp;size=xs" /><img alt="shieldcn stats" src="https://shieldcn.dev/group/github/jal-co/shieldcn/stars+github/jal-co/shieldcn/license+github/jal-co/shieldcn/contributors+github/jal-co/shieldcn/last-commit.svg?variant=branded&amp;size=xs&amp;mode=light" /></picture></a>
</p>

<p align="center">
  <a href="https://vercel.com/oss"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/Vercel_OSS_Program_Member.svg?variant=branded&amp;size=xs&amp;logo=vercel" /><img alt="Vercel OSS Program Member" src="https://shieldcn.dev/badge/Vercel_OSS_Program_Member.svg?variant=branded&amp;size=xs&amp;mode=light&amp;logo=vercel" /></picture></a>
  <a href="https://openpanel.dev?ref=justinlevine.me"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/analytics%20by-openpanel.svg?variant=branded&amp;size=xs&amp;logo=openpanel" /><img alt="analytics by openpanel" src="https://shieldcn.dev/badge/analytics%20by-openpanel.svg?variant=branded&amp;size=xs&amp;mode=light&amp;logo=openpanel" /></picture></a>
  <a href="https://neon.com/?utm_source=shieldcn.dev"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/powered%20by-Neon-37C38F.svg?variant=branded&amp;size=xs&amp;logo=neon&amp;logoColor=fff" /><img alt="Powered by Neon" src="https://shieldcn.dev/badge/powered%20by-Neon-37C38F.svg?variant=branded&amp;size=xs&amp;mode=light&amp;logo=neon&amp;logoColor=fff" /></picture></a>
</p>

## Usage

Drop a badge into any README and it renders as a real shadcn Button.

```md
![npm](https://shieldcn.dev/npm/react.svg)
![stars](https://shieldcn.dev/github/vercel/next.js/stars.svg)
![views](https://shieldcn.dev/views/repo/shieldcn/shieldcn.svg)
```

## Agent skill

Install the `shieldcn-badges` skill from [skills.sh](https://skills.sh) so your
coding agent can add shieldcn badges, charts, and headers to READMEs:

```bash
npx skills add jal-co/shieldcn -a claude-code # installs to Claude Code
npx skills add jal-co/shieldcn -a cursor # installs to Cursor
```

See [`skills/shieldcn-badges/SKILL.md`](skills/shieldcn-badges/SKILL.md) for
prompt examples and options.

## Star history

Hosted star charts use GitHub's privacy-safe weekly history API. Embed
`https://shieldcn.dev/chart/github/stars/{owner}/{repo}.svg` for any public
repository, or use `.png` and `.json` at the same path.

To commit a light/dark SVG pair to your repo, use the **shieldcn starchart**
GitHub Action:

```yaml
- uses: jal-co/shieldcn@v1
  with:
    theme: violet
    pull-request: true
```

PR mode needs `contents: write`, `pull-requests: write`, and permission for
Actions to create pull requests in repository settings.

[**GitHub Action docs →**](https://shieldcn.dev/docs/charts/star-history) ·
[action reference](packages/action/README.md)

<p align="center">
  <a href="https://github.com/jal-co/shieldcn/stargazers"><picture><source media="(prefers-color-scheme: dark)" srcset=".github/shieldcn/star-chart-dark.svg" /><img alt="Star history of jal-co/shieldcn" src=".github/shieldcn/star-chart-light.svg" /></picture></a>
</p>

## Sponsors

<p align="center">
  <picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/sponsors/jal-co.svg?title=false&amp;preset=transparent&amp;size=80&amp;names=false&amp;special=usenotra&amp;separator=line&amp;mode=dark&amp;border=false" /><img alt="sponsors" src="https://shieldcn.dev/sponsors/jal-co.svg?title=false&amp;preset=transparent&amp;size=80&amp;names=true&amp;special=usenotra&amp;separator=line&amp;mode=light&amp;border=false" /></picture>
</p>

## Contributors

<p align="center">
  <a href="https://github.com/jal-co/shieldcn/graphs/contributors"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/contributors/jal-co/shieldcn.svg?title=false&amp;preset=transparent&amp;border=false&amp;mode=dark" /><img alt="contributors" src="https://shieldcn.dev/contributors/jal-co/shieldcn.svg?title=false&amp;preset=transparent&amp;border=false&amp;mode=light" /></picture></a>
</p>

<div align="center">

[MIT](https://github.com/jal-co/shieldcn/blob/main/LICENSE) · Built by [Justin Levine](https://justinlevine.me) · [Contribute](https://github.com/jal-co/shieldcn)

</div>
````
