The `primer-react` skill

The skill you run in Generate. It was built ahead of time by the meta-skill extract-ds-skill, pointed at the installed @primer/react package, the primer.style docs, and a reference project that uses Primer in production. This skill ships pre-built in your starter at .claude/skills/primer-react/, so you don't extract it live. This page is what's inside.

The skill is portable. Drop it into any project that installs @primer/react and the contract holds.

What it does

Run the workshop prompt with the skill in a fresh Claude session:

/primer-react implement prompts/pr-merged-switch-dark-mode.md

The skill loads its SKILL.md plus references, reads the prompt, and generates UI against the design system's contract:

Verified props only. Every prop claim is grounded in the installed package's type files: the skill cites node_modules/@primer/react/.../<Component>.d.ts lines, and anything unverifiable carries a literal [VERIFY] marker.
Token usage. Spacing, colour, radius from @primer/primitives: no hex codes, no arbitrary px.
SSR hydration mismatch on first paint prevented. ThemeProvider is wired so the server-rendered markup matches the first client paint: no flash, no hydration warning.
Shell parity. Page background, theme provider mounting, and both color modes follow the reference project's wiring, re-checked after any layout edit.
Craft. A DS-agnostic design-craft reference (layout, hierarchy, motion, restraint) ships inside the skill and shapes the output silently. The DS always wins on conflict.

File layout

.claude/skills/primer-react/
  SKILL.md                       # loadable contract: headline rules,
                                 # shell invariants, provenance,
                                 # post-generation report.
  AGENTS.md                      # cross-agent stub for non-Claude agents.
  references/
    components/                  # one file per component, 19 in all:
                                 # button.md, text-input.md,
                                 # state-label.md, ...
    tokens.md                    # @primer/primitives token names + values.
    foundations/                 # cited Primer foundation rules:
                                 # accessibility, primitives, octicons.
    examples/                    # composition exemplars from the
                                 # reference project, pattern-not-data.
    anti-patterns.md             # named agent failure modes: the payload.
    design-craft.md              # DS-agnostic craft reference, shipped
                                 # verbatim by the extractor.

The shape is fixed by extract-ds-skill: the meta-skill never invents structure, it fills slots.

The payload: `references/anti-patterns.md`

This is the highest-value file in the skill. The component files tell the agent what's true; anti-patterns.md tells it the named ways it goes wrong: the mistakes a generic model makes by default, written down so the agent stops making them. Each row is a failure mode it has seen, paired with the rule that prevents it.

Everything else holds the floor. This file raises it. When you grow the skill later, this is where most new lines land: every PR comment that reveals a missing rule becomes one anti-pattern row.

Why each file exists

SKILL.md: the loadable contract. Headline rules up top, shell invariants from the reference project, a provenance block recording what was typechecked and cited, and the post-generation report the agent must print.
AGENTS.md: the lowest-common-denominator surface (agents.md) pointing non-Claude agents at the skill.
references/components/: one file per component across the 19-component slate, every public prop, each claim cited to the installed types. Without it, every agent re-derives the API on every run.
references/tokens.md: the closed set the agent picks from. If a value isn't in this file, the agent shouldn't be writing it.
references/foundations/: Primer's own rules, each carrying its citation so the rule never decays into a paraphrase.
references/examples/: short verbatim snippets showing the shape of a correct composition without giving the agent data to copy.
references/anti-patterns.md: the payload, above. Named failure modes, each tied to the rule that prevents it.
references/design-craft.md: generic taste: density, hierarchy, motion vocabulary, anti-slop restraint. Copied byte-for-byte by the extractor, never edited per-DS.

How it differs from a generic Primer integration

Most "use Primer with an AI tool" setups are an AGENTS.md line saying "this project uses @primer/react": the manifest level. primer-react is the runtime-contract level: these props, these tokens, and the named ways it goes wrong. The self-report the agent prints after every generation is what makes that difference legible.

Taking the skill home

primer-react is MIT-licensed and ships in the starter at .claude/skills/primer-react/. To re-use the shape on your own design system, read how it was built in Extraction, then follow the meta-skill:

Read extract-ds-skill: the meta-skill that produces this one.
Identify your design system's docs root URL and one reference project using the DS in production.
Run its three phases (Discovery → Validate → Persist) in fresh claude sessions, confirming the operator gates.
Commit the produced .claude/skills/<your-ds>/. That's your portable skill.

After that, you're in Cultivation mode: every PR comment that reveals a missing rule becomes one MUST line in SKILL.md and one row in anti-patterns.md.

Next: Articles

The primer-react skill