Turning a one-project pattern into a reusable Claude Code skill

The case for packaging it

The first rebuild we ran this methodology on took about a day, including the audit, the wiring, the reconciliation, and the docs. After it shipped, we had two more projects queued up that needed the same pattern. Doing it from scratch each time would have been a waste, same questions, same decisions, same files. So we packaged it.

The economics are simple. Running the methodology by hand costs roughly a day per project: an hour for the audit, time to decide on structure and token approach, a few hours to scaffold components and write specs, and documentation at the end. Fine once. Across five or six engagements, it compounds fast.

Package it once. The packaging costs a day. Each subsequent run costs about thirty minutes of actual human input, mostly to confirm project-specific details. The more projects you run it on, the better the ratio gets.

“

A methodology that's repeatable in principle isn't repeatable in practice until it's tooling.

There's a secondary cost too: drift of a different kind. Every time you reconstruct a methodology from memory, you reconstruct it slightly differently. Decisions made carefully the first time get fuzzy. The packaging codifies those decisions, so you're not relitigating them per project, and the next engineer on your team isn't guessing how the last one did it.

What a Claude Code skill is

Claude Code supports skills: self-contained agent capabilities you install once and invoke across any project. A skill lives in ~/.claude/skills/ on your machine. The runtime discovers it, reads the description field in SKILL.md, and makes the skill available whenever natural language triggers match.

The folder structure for the design system scaffold skill looks like this:

~/.claude/skills/
└── design-system-scaffold/
    ├── SKILL.md
    └── references/
        ├── audit-checklist.md
        ├── templates.md
        ├── flavor-marketing.md
        ├── flavor-app.md
        ├── stack-vue-nuxt.md
        ├── stack-react-next.md
        ├── stack-agnostic.md
        └── spec-deep-dive.md

SKILL.md has two jobs: describe the skill to Claude via the description field, and define the four-phase execution flow. The references folder holds everything else.

The description field went through about five revisions. Too short and it missed trigger phrases. Too long and it started reading like documentation for documentation. The job is to cover enough natural language patterns that Claude routes correctly, without the field becoming a paragraph that Claude has to parse.

The first version of SKILL.md was 8 KB. It tried to teach the entire methodology inline, including audit logic, token decisions, and the spec format. That was wrong. An 8 KB instruction file is hard to prioritize correctly, and it put every decision in front of Claude at once instead of sequencing them. We cut it to 3 KB by moving the methodology into the references folder. Phase 1 now triggers the right references at the right time. The model loads what it needs for each phase, not everything at once.

The four-phase flow

“

Audit → plan → confirm → build. Each phase has a job. Don't skip phases.

This is the load-bearing structure of the skill. Each phase has a specific job and specific outputs. They run in order. Skipping Phase 3 to save time is how you end up with a scaffold that doesn't match the project, the team's conventions, or both.

Phase 1: audit

Claude reads the project to understand what exists before anything is written. The inputs are:

• package.json (dependencies, version constraints, framework signals)
• Tailwind config (v3 or v4, any existing theme extensions)
• CSS entry files and any SCSS variable files
• Existing component directory (names, structure, patterns)
• Routes or pages directory (for structural signal about project type)
• Brand assets (for naming patterns and visual vocabulary)

The output is .agents/design-system-audit.md, written into the project at the end of Phase 1. It maps what the audit covers: color primitives, spacing scales, typography, existing component inventory, and any token patterns already in use. This file becomes the source of truth for Phase 2.

During this phase, Claude loads audit-checklist.md from the references folder. Nothing else. The methodology lives in references; Phase 1 only loads what Phase 1 needs.

Phase 2: plan

Claude reads the audit output and produces a plan: what the design system will contain, how it will be structured according to the five-tier model, where files will live, which tokens will be explicit CSS custom properties, and which will stay in the Tailwind config. This gets written to .agents/design-system-plan.md as a draft.

Phase 2 also produces a set of signals pointing toward a flavor recommendation. If the audit finds routes named /dashboard and /settings, components named DataTable and Modal, and an auth package in package.json, Claude notes in the plan that this looks like an app project. But it doesn't lock anything in. That happens in Phase 3.

The plan document is readable. You can open .agents/design-system-plan.md after Phase 2 and see exactly what Claude is proposing before you approve anything. That's deliberate. Blind execution on a plan you haven't seen is how mistakes compound.

Phase 3: confirm

The skill pauses. Claude does not proceed to build without explicit answers to the confirm-phase questions. This is where AskUserQuestion runs.

“

The confirm phase is what keeps it safe.

The confirm phase exists because the decisions it covers are genuinely not Claude's to make. Flavor, folder location, stack adapter, voice rules, and token approach all depend on team conventions, client preferences, and architectural constraints that no amount of file-reading will reliably surface. Claude can guess. Guesses at this level produce scaffolds that need to be ripped out and redone. Five questions up front is faster.

Phase 4: build

Claude builds from the confirmed plan. The outputs follow the structure from Phase 2, with all values and paths locked in from Phase 3. This is where the design token wiring happens, where component spec stubs get written in the format the series has been building toward, and where any drift between design values and existing component code gets documented. Not fixed. Documented. The reasoning for that choice is in Article 6, and it's baked into Phase 4's constraints.

Phase 4 is non-destructive. That isn't a setting. It's how Phase 4 was written.

What the skill asks in Phase 3

The confirm phase runs five questions. Claude doesn't guess at any of them.

Flavor: "Is this a marketing site, a product app, or both?" The answer loads the right flavor reference for Phase 4. Marketing and app projects have genuinely different component needs. Getting this wrong means the scaffold points in the wrong direction from the start.

Folder location: "Where should the design system files live? Default: src/design-system/." Claude will not pick this unilaterally. Some teams want src/ui/. Some want design-system/ at the repo root. Some have constraints from monorepo setup that make the default wrong. The skill asks.

Stack adapter: "Which stack adapter should I use: Vue/Nuxt, React/Next, or framework-agnostic?" The adapter controls import syntax, component wrapper format, and SSR-specific annotations. Using the Vue adapter on a Next project produces output that needs manual correction everywhere.

Voice rules: "Are there brand voice guidelines to apply to documentation? Paste or point to them." The skill writes documentation as part of the build. Voice rules shape how that documentation reads. If a brand guide exists, the spec stubs and component documentation can match its tone. If it doesn't, the skill flags the docs as needing a voice pass later.

Token approach: "Tokens in tokens.css as CSS custom properties, extended Tailwind config, or both?" This is an architectural decision with real downstream consequences. The token article covers the tradeoffs. Phase 3 captures the answer. Claude does not decide.

Two flavors

The first version of the skill had a single flavor. It worked for marketing sites. When the next project was a product app, the single-flavor guidance produced a reasonable but wrong scaffold: too much landing-page orientation, not enough for interactive states, complex forms, and navigation patterns.

Adding the app flavor doubled the references folder. Worth it. The two project types are genuinely different, and the difference starts with component vocabulary.

Signal detection in Phase 1

Claude builds a flavor recommendation by reading signals during the audit:

Claude surfaces these signals in the Phase 2 plan document. The user confirms or overrides in Phase 3.

Folder trees by flavor

Marketing:

src/design-system/
├── tokens/
│   ├── tokens.css
│   └── typography.css
├── components/
│   ├── Button/
│   ├── Card/
│   ├── Hero/
│   ├── Nav/
│   └── Footer/
├── layouts/
└── docs/
    └── specs/

App:

src/design-system/
├── tokens/
│   ├── tokens.css
│   └── typography.css
├── components/
│   ├── Button/
│   ├── Input/
│   ├── Select/
│   ├── Modal/
│   ├── Toast/
│   ├── DataTable/
│   └── Sidebar/
├── patterns/
│   ├── forms/
│   └── navigation/
├── layouts/
└── docs/
    └── specs/

The token layer is identical. The component set is not. The patterns/ directory in the app flavor exists because app UX involves multi-component flows (forms, navigation sequences, modal interactions) that don't have natural parallels in a marketing context.

Three stack adapters

The references folder includes stack-vue-nuxt.md, stack-react-next.md, and stack-agnostic.md. We built all three because client work spans both frameworks, and having an agnostic option covers projects mid-migration.

What's the same across adapters

• Token file structure (CSS custom properties are framework-agnostic by design)
• Component spec format (follows the AI-readable spec pattern)
• Audit output format
• Documentation shape and section naming

What changes

The prefix decision

Whether to prefix primitive components with Ds for auto-import collision avoidance (e.g., DsButton instead of Button) is a real decision that we resolved during development of the skill.

We tried both approaches. The prefixed version is safer in projects with many third-party components where names collide. The unprefixed version is cleaner in isolated design systems. We decided not to prefix by default. The Ds prefix option is documented in the skill for projects where collision is a genuine risk. If you're pulling in Radix, Headless UI, and a custom design system simultaneously, the prefix is worth the verbosity.

What's automated and what isn't

“

Non-destructive isn't a feature you add at the end. It's a constraint.

Phase 4 builds the scaffolding. What it doesn't do is as important as what it does.

Automated:

• Writing the token file from values found in the audit
• Creating component directories and spec stubs
• Generating .agents/design-system-audit.md and .agents/design-system-plan.md
• Producing initial documentation shaped by confirmed voice rules
• Logging any detected drift between design values and existing component styles

Not automated:

• Reconciling drifting tokens (documented, user decides)
• Choosing flavor or folder location (Phase 3, always)
• Modifying any existing component file
• Deleting any file, anywhere

We tried auto-reconciling drifting tokens during Phase 4. If the audit found a --color-brand-primary custom property in the CSS entry but the Tailwind config used a hardcoded hex for the same color, the first version tried to normalize them. We backed that out. Reconciliation logic that touches existing files is fragile, and reconciliation that modifies production CSS without review violates the whole principle. The approach to drift is to document it clearly and surface it to the developer. That decision is theirs. The skill's job is to make the situation visible, not to resolve it.

If a target file already exists when Phase 4 runs, the skill logs the conflict and skips it. No silent overwrites.

What a run looks like

Here's a hypothetical walk-through on a project similar to the production marketing site (Nuxt + Tailwind v4) that started all of this.

Example:

Project: A B2B SaaS marketing site with Nuxt 3, Tailwind v4, four content pages, no existing design system, brand guidelines available in a Figma file.

Trigger: "Set up our design system scaffold" in Claude Code.

Phase 1 (audit, ~3 minutes): Claude reads package.json, finds Nuxt 3 and Tailwind v4, no auth packages, no dashboard routes. Reads the CSS entry file: a handful of custom properties defined ad hoc, no naming convention. Reads the components directory: HeroSection.vue, PricingCard.vue, TestimonialBlock.vue. Writes .agents/design-system-audit.md.

Phase 2 (plan, ~2 minutes): Claude reads the audit. Signals point strongly to marketing flavor. Proposes a five-tier structure with tokens.css as the token layer. Writes .agents/design-system-plan.md. Notes two existing custom properties that will need reconciliation with new token names.

Phase 3 (confirm, user input required):

• Flavor: marketing (user confirms)
• Folder: src/design-system/ (user confirms default)
• Adapter: Vue/Nuxt (user confirms)
• Voice rules: pasted from Figma brand doc
• Token approach: CSS custom properties in tokens.css, Tailwind config references them via @theme

Phase 4 (build, ~8 minutes): Scaffold written to src/design-system/. Token file created with values extracted from audit. Component directories created for Button, Card, Nav, Footer, Hero. Spec stubs written in each. Documentation written under docs/specs/ using the pasted voice rules. Drift log: two custom properties in the old CSS entry don't match the new token names. Logged to .agents/design-system-audit.md, not touched.

Total human effort: About 5 minutes of input. Phase 3 confirmation is the deliberate part. The mechanical work is gone.

What's next for the skill

The skill is at v1. Three things are on the roadmap for the next projects we run it on.

Re-runs on existing projects. The skill currently assumes a greenfield design system install. A re-run mode would read an existing .agents/design-system-audit.md, diff it against the current project state, and report what's changed since the last run. Useful after major dependency bumps or design handoffs.

Token build pipeline. The confirm phase captures the token approach but doesn't yet wire up a step to ingest a Figma token export and generate tokens.css from it. That's a separate integration. The file structure supports it. We haven't built it.

More adapters. SvelteKit is next. Solid and Remix are on the list. The agnostic adapter covers the gap until they exist.

Open source and how to use it

The skill lives on GitHub as part of clearlydesign/design-skills, an umbrella repo that will hold this and future design-focused Claude Code skills.

Install pattern: clone the repo once to a holding location, then symlink each skill you want active into ~/.claude/skills/. Two lines, transparent about what's happening:

git clone https://github.com/clearlydesign/design-skills.git ~/.clearlydesign/design-skills
ln -s ~/.clearlydesign/design-skills/design-system-scaffold ~/.claude/skills/design-system-scaffold

Restart Claude Code. The skill is available across every project on your machine. To update later, cd ~/.clearlydesign/design-skills && git pull.

If you're a consultant or agency engineer running this methodology across multiple clients, install the skill once. The confirm phase handles everything project-specific. The skill handles the rest.

If you're a founder with multiple products, the flavor system is what makes it worth it. A marketing site and a product app under one methodology, same audit format, same spec format, same documentation shape, different component scaffolds.

We built this in public because the methodology is more useful shared. If you find an edge case the skill handles poorly, or a stack adapter that's missing, open an issue or a PR. The references folder was designed to be extended. Star the repo to follow as we ship re-runs, the token build pipeline, the SvelteKit adapter, and the next skills in the design-skills umbrella.

This is the last article in the AI-Ready Design Systems series. The methodology is documented. The tool is shipped.