Claude Code design skills for design systems
A skill is how you stop pasting design-system rules into every Claude Code chat. Install the open scaffold, or partner when taste, governance, and multiple repos are the real job.
Francois Brill
Designer + Builder
Sep 14, 2026
Last updated
AI generates components fast. It also drifts off-brand fast: wrong tokens, wrong spacing, wrong patterns. You need a persistent anchor. For Claude Code, that anchor is a skill: a SKILL.md that packages your design-system methodology so Claude follows it across projects without you pasting the same procedure into every chat.
On 9 Sep 2026, Google Search Console showed 6 clicks from 611 impressions on the article that documents this skill. Demand is real. We are not inflating it.
What a Claude Code skill is vs CLAUDE.md
Anthropic's skills docs are the source of truth for the runtime. The short version: a skill extends what Claude can do. You write a SKILL.md with YAML frontmatter and markdown instructions. Claude adds it to its toolkit, loads it when the conversation calls for it, or you invoke it with /skill-name.
Create a skill when you keep pasting the same checklist into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact. Unlike CLAUDE.md, the skill body loads only when it is used, so long reference material costs almost nothing until you need it.
CLAUDE.md always loads per project. It is the right place for facts: what the repo is, which stack you ship, which APIs are authoritative, what is off limits. A skill loads when triggered. That distinction matters when design documentation is large. You do not want several kilobytes of pattern docs burning context on every turn, whether or not the task involves the design system.
CLAUDE.md | Skill (SKILL.md) | |
|---|---|---|
| Loads when | Every session in that project | When you invoke it, or when Claude judges it relevant |
| Good for | Project facts, constraints, tooling | Procedures, methodologies, multi-step workflows |
| Context cost | Always present | Only when the skill is needed |
| Scope | Per-project | Personal (~/.claude/skills/) or in the repo (.claude/skills/) |
| How to invoke | Automatic | Automatic or /skill-name |
Claude Code global skills live at ~/.claude/skills/ and load across every local project on that machine. Claude skills in a repo live at .claude/skills/ and load for that project. Commit the repo copy so the team gets it. The install pattern for Clearly's public skills is clone-once, then symlink each skill you want active into the personal folder.
People searching how to create claude agents and skills often land on pages that mash two features together. Agents and subagents are isolated task contexts for splitting work. Skills are packaged instructions Claude can invoke. Both exist in Claude Code. This page is about skills.
How to create a design-focused skill
If you want to create a Claude Code skill a team will actually reuse, the load-bearing decision is what lives in SKILL.md versus what lives in references/.
The first SKILL.md we wrote for this methodology was 8 KB. It tried to teach the audit, the token decisions, and the spec format inline. That was wrong. An 8 KB instruction file is hard to prioritize, and it puts every decision in front of Claude at once. We cut it to about 3 KB by moving the methodology into references/. Each phase loads what that phase needs.
That is the shape worth copying if you are building Claude skills of your own: a lean trigger file, plus supporting docs the skill reads on demand.
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, so natural-language prompts route to it. Define the execution flow. Everything else (checklists, flavor trees, stack adapters, spec stubs) sits in references.
Keep SKILL.md lean
If a paragraph is only relevant in Phase 4, it does not belong in the file Claude reads on every trigger. Put it in a reference and tell the skill when to load it. We learned this the expensive way.
The full packaging story (frontmatter revisions, the five Phase 3 questions, a worked Nuxt run) is Turning a one-project pattern into a reusable Claude Code skill. This hub will not rewrite that article. Read it when you want the how-we-built detail. Start the series at how we structure design systems for AI.
Install design-system-scaffold
The skill is open. The Claude skills GitHub repo is ClearlyDesign/design-skills. MIT. Clone it once to a holding location, then symlink each skill you want active into ~/.claude/skills/. Two lines, transparent about what is 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 now available across every project on your machine. To update later: cd ~/.clearlydesign/design-skills && git pull. All symlinked skills update with that pull.
The README also has an install.sh if you want every skill in the repo at once. We still lead with clone plus symlink, because you can see exactly what landed on disk.
design-system-scaffold audits any frontend project and scaffolds an AI-ready design system in place. Four phases, in order, never skipped.
| Phase | Job | Writes |
|---|---|---|
| 1. Audit | Read package.json, Tailwind config, CSS entries, components, routes, brand assets | .agents/design-system-audit.md only |
| 2. Plan | Propose folder, flavor, stack adapter, token approach | .agents/design-system-plan.md (readable before anything is built) |
| 3. Confirm | Pause. Five questions via AskUserQuestion. Claude does not guess. | Updates the plan with your answers |
| 4. Build | Scaffold files, wire tokens, write spec stubs | New files only. Existing paths are skipped and logged |
Phase 3 asks flavor (marketing, app, or both), folder location (default src/design-system/), stack adapter (Vue/Nuxt, React/Next, or framework-agnostic), voice rules, and token approach (tokens.css as CSS custom properties, extended Tailwind config, or both). Those are not Claude's calls. Guesses at this level produce scaffolds you rip out.
Non-destructive is a constraint, not a setting. No existing file is modified or deleted. If a target already exists in Phase 4, the skill logs the conflict and skips the write. Drift between design values and existing component code is documented, not auto-reconciled.
Two flavors share a token layer and differ in component vocabulary. Marketing leans Hero, Card, Nav, Footer. App leans Input, Modal, Toast, DataTable, plus a patterns/ directory for forms and navigation. Three stack adapters cover Vue/Nuxt, React/Next, and a spec-only agnostic path. SvelteKit is on the roadmap in article 7. It is not shipped. Do not pretend it is.
Trigger it like this
In Claude Code, ask to set up the design system scaffold. Phase 1 reads the repo. Phase 2 writes a plan you can open. Phase 3 waits for you. Phase 4 builds. A worked run on a hypothetical Nuxt marketing site is in article 7.
Skills in a repo / team workflow
A skill on your laptop is not a team skill. Decide where it lives.
Personal / global. ~/.claude/skills/<name>/SKILL.md loads in every local project on that machine. Fine for a consultant running the same methodology across clients. Useless to the engineer who cloned the product repo yesterday.
In the repo. .claude/skills/<name>/SKILL.md loads for that project. Commit it. The next session, on the next laptop, gets the same procedure. Nested packages in a monorepo can carry their own skills. Claude Code will pick those up once the session is working in that directory.
Shared GitHub skills repo. The Clearly pattern (and the one we recommend if you publish skills): keep an umbrella repo, clone it to a holding path, symlink the skills you want into ~/.claude/skills/. One git pull updates everything. Symlinked folders are first-class. Claude reads SKILL.md from the target.
Cloud and Cowork sessions do not read ~/.claude/skills/ on your machine. If a routine or a teammate's cloud session needs the skill, commit it to .claude/skills/ or ship it as a plugin the repo enables. Otherwise Claude reports the skill was not found, and you spend the morning wondering why it worked on your laptop.
A sane default for product teams
Put project-specific rules in CLAUDE.md. Put reusable procedures in a committed skill. Put studio-wide methodology in a shared GitHub repo you symlink. Do not paste a 200-line design-system prompt into Slack and call it process.
When to partner
The open skill is the right first move when one repo needs a scaffold and you can answer the confirm-phase questions. It is the wrong move when the actual gap is taste, ownership, or surface area.
Taste Profile. Pasting brand guidelines into chat is describing the brand. A Taste Profile is the spec the AI reads: tokens, a DESIGN.md, a SKILL.md, voice, the decisions a designer would make without being asked. Guidelines get paraphrased every session. A spec stays put. If AI UI still looks "close" and never on-brand, you do not need another prompt. You need the brand encoded so agents cannot invent a new one.
Governance. A design system without an owner becomes a suggestion library. Who can add a component. What happens when a squad ships a one-off. How the skill and the token file stay in sync after a rebrand. The scaffold will not invent that process. Someone has to.
Multi-repo. One marketing site and one app is a good skill run. Five products, three stacks, and a design language that is supposed to feel like one company is a different job. Flavor and adapters help. They do not replace someone holding the thread.
If that is the work, we are a design partner for SaaS, not a request queue. Prototype-first. Slack and Looms. Standard $4,995/mo and Advanced $7,495/mo, pause or cancel. Confirm live pricing on clearly.design before you buy. If the scoped job is an AI-ready design system for a team shipping with Cursor, Claude Code, or v0, that offer is $8-12K and 2-4 weeks.
Stay on the open skill if you have one repo, you can confirm flavor and adapter yourself, and you want the methodology in your toolchain this afternoon. Book a call if the skill would only scaffold the easy part, and the hard part is still sitting with a founder.
Clone design-skills, or bring the messy version of the problem. We will tell you which path is honest.
Frequently asked questions
What is a Claude Code skill?
How is a Claude Code skill different from CLAUDE.md?
How do I create a Claude Code skill for a design system?
How do I install Clearly's design-system-scaffold skill?
What is the difference between Claude Code global skills and skills in a repo?
Where is the Claude skills GitHub repo for Clearly's design skills?
When should we partner instead of running the open skill ourselves?
Related Decision Guides
Design Partner for SaaS Startups
Looking for a design partner for your SaaS, not a request queue? Prototype-first embedded design at Standard $4,995/mo and Advanced $7,495/mo.
When to Invest in a Design System for Your SaaS
Is it too early for a design system? Too late? Here's how to know when a design system becomes a strategic investment vs. premature optimization for your SaaS.
Design Subscription vs Hiring a Designer
Compare design subscriptions, freelancers, and full-time hires: real cost ranges, when each fits, and when an embedded partner beats a request queue.