extract-ds-skill

The meta-skill that turns a design system into an agent skill. It built the primer-react skill that ships in the starter you clone and use in Generate.

You do not run this during the workshop. It is taught as an overview, not run live. This page is the technical reference: how the skill was built, to read after the workshop, and how to run it on your own design system later. For the at-a-glance version, see Extraction.

What it does

extract-ds-skill is design-system-agnostic: it reads a design system in place and writes a self-contained, design-system-specific agent skill into .claude/skills/<slug>/.

You invoke it as a single line of free text: no labeled keywords, no node_modules paths, no enumerated sub-pages:

The skill sorts each URL itself. Foundation roots are crawled one level deep to find sub-pages. The reference project's framework is detected, and the design-system package is read from its package.json. Package names and versions are found on their own, and node_modules is installed if it is missing.

The three phases

The meta-skill runs across three fresh Claude sessions. Each one hands off to the next through a file written to .extract-ds-skill-scratch/handoffs/. The fresh-session reset is the proof: each phase has only what the phase before it wrote to disk, so the result is reproducible from the handoff files alone.

Phases 1 and 2 hard-stop at the end so the next phase starts with a clean context window. You resume in a new claude session. The keyword names the next phase; the path points at the handoff from the phase before:

validate: enters Phase 2. persist: enters Phase 3. No keyword means Phase 1 from scratch. To stay in one session, override the hard-stop with continue inline.

Nothing reaches the produced skill that wasn't typechecked, grep-resolved, or cited. Anything that cannot be verified ships as a literal [VERIFY] marker, never as a quiet claim.

The proof line at the Phase 2 gate reads like this: N props verified against source, M tokens grep-resolved, K assets grep-resolved, F foundation-rules extracted (X cited, Y [VERIFY]), 0 hallucinations, plus TOKEN_COVERAGE=PASS|NOOP|FAIL when a reference project is in scope. A FAIL blocks the approval gate until the gap is fixed or accepted.

The produced shape

Every skill extract-ds-skill writes uses this layout. The meta-skill never invents structure; it fills slots:

.claude/skills/<slug>/
  SKILL.md                       # loadable contract. Headline rules,
                                 # shell-invariant hard rules, a
                                 # provenance block (what was validated
                                 # against what), and a "common agent
                                 # failure modes" anti-pattern section.
  AGENTS.md                      # cross-agent stub for non-Claude agents.
  references/
    components/                  # one file per component, every prop cited.
    tokens.md                    # token names + values: the closed set.
    foundations/                 # one file per cited foundation area.
    examples/                    # composition examples, pattern-not-data,
                                 # lifted from the reference project.
    anti-patterns.md             # named agent failure modes.
    design-craft.md              # DS-agnostic craft reference, shipped
                                 # word for word, never extracted.

See primer-react for the produced version that ships in the starter.

anti-patterns.md is the payload

references/anti-patterns.md is the highest-value file the meta-skill writes. A component list and a token table tell the agent what exists. The anti-patterns tell it what to stop doing: the named failure modes it falls into without them. That is the most valuable thing a skill encodes: not the parts an LLM could guess, but the mistakes it keeps making until you write them down. Every gap you find later becomes one more row here.

probe-rendered.sh is optional take-home

scripts/probe-rendered.sh (Playwright) lives in this meta-skill. It is optional and off-stage: not part of the workshop's stage flow. It renders the generated UI in a real browser to audit pixels, which is slower and heavier than the static checks above. Run it later if you want that extra layer. It is separate from the Layer-1 verify-citations.sh check, which is part of Validate and checks the skill, not the rendered output. For the one deep dive on why you audit at all, see The Audit.

Running it on your own design system

After the workshop, extract-ds-skill is MIT-licensed and already on disk at .claude/skills/extract-ds-skill/. To run it on your own design system:

1. 1
   Copy .claude/skills/extract-ds-skill/ into your project as-is. It is the original and is design-system-agnostic.
2. 2
   Find your foundation docs root URL and one reference project that already uses the design system in production. Tokens and component APIs resolve from the installed packages: no local DESIGN.md, no local component copies.
3. 3
   Run /extract-ds-skill <foundation-root-url> <reference-project-github-url> and walk the three phases in three fresh claude sessions, confirming the operator gates at the end of Discovery and Validate.
4. 4
   Commit the resulting .claude/skills/<your-ds>/. That is your portable skill.

From there you are in cultivation: every PR comment that reveals a missing rule becomes one MUST line in SKILL.md and one row in anti-patterns.md.

Go deeper

Each piece of the skill has a focused walk-through in the Deep Dive section:

• How it works: the three phases and the single gate, end to end.
• Source-role taxonomy: the ten input roles and which one wins on conflict.
• Reading the proof-point: every field of the Phase 2 validation block.
• Anatomy of a produced skill: every file the skill writes, and when.
• The reflexive audit: the three self-audit layers.
• Handoffs and fresh sessions: why each phase resumes in a clean session.
• Rule shapes: the seven shapes a rule can take, and where each lands.
• Design craft, the shipped default: the one file that ships verbatim, not extracted.

Next: primer-react