How to create a skill in Claude Code for your design system

Give Claude Code a clear prompt, and it can document a component library or flag design token mismatches.

According to our State of the Designer 2026 report, 89% of designers already say AI tools help them work faster. The challenge is that Claude Code doesn’t inherently know your conventions, so outputs vary depending on who’s running it and what context they include.

Claude Code Skills gives the tool persistent context, so your standards stay consistent across every session and teammate.

Read on to learn:

• What a Claude Code Skill is and how it differs from a prompt
• How to decide when your design system needs a skill
• How to build a design system skill step by step
• How to write instructions Claude will follow consistently

What is a Claude Code Skill?

Claude Code Skills are reusable instruction files that live in your project and give Claude a set of standing instructions. While a prompt is session-specific, a skill’s description loads every time Claude Code starts, and Claude pulls in the full instructions whenever your work matches it.

In practice, that might look like a skill that understands your design system’s token-naming syntax and writes component annotations in the format your team expects. Or one that formats developer handoff notes the way your engineering team uses them, so output is consistent whether you’re writing or a teammate is.

When to build a skill vs. use a prompt

Not every workflow needs a skill. A good way to decide is to think about how often you’re giving Claude the same context and whether the outputs are consistent enough to act on.

Build a skill when:

• You give Claude the same context or constraints every session
• Outputs shift depending on who writes the prompt
• A new team member can’t reproduce your results without copying your exact setup
• You need the whole team working from the same baseline

Stick with a prompt when the task is a one-off, or the context is specific to this session and won’t repeat.

How to create a Claude Skill

Once you’ve decided a skill is the right call, adding one to your Claude Code workflow is simple. Here’s how to build one.

Step 1: Set up your skills folder

Skills live in a claude/skills folder at the root of your Claude Code project. Each skill gets its own subfolder containing a SKILL.md file. The name should reflect what the skill does. For example, a skill for formatting handoff notes might be called “handoff-notes,” and one for applying brand voice conventions might be called “brand-voice.” Once the folder is in place, Claude Code automatically picks it up.

If you’d rather not start from a blank file, Claude’s skill generator can handle the initial scaffolding. Describe what you want the skill to do, and it’ll produce a draft with the right structure that you can refine from there.

Step 2: Write your skill description

At the top of your skill file, you’ll add a short block that includes two fields: a name and a description. The name is just a label. The description is what really matters. Claude reads the description to decide whether to load your skill for a given task, so it needs to explain what the skill does and when to use it.

“Helps with writing tasks” gives Claude too little to go on. “Use this skill when writing developer handoff notes or summarizing design decisions in the team’s standard format” gives it a clear trigger.

Step 3: Write the instruction block

The body of the skill is where you write the instructions Claude follows. Be specific about what good output looks like and give Claude enough role context to orient itself. Claude reads this section like a system prompt, so vague language will produce vague results.

If Claude drifts from what you expected, the fix is almost always in the instruction block. Either a rule is missing, or it isn’t specific enough. Including a short example of correct output next to an incorrect one is usually all it takes.

Step 4: Save and activate

Before you close the file, check that the markdown is valid. Broken formatting or syntax errors in the frontmatter can prevent the skill from loading. Make sure the description field isn’t empty—Claude won’t trigger the skill reliably without it.

If you’re building this for a team, make sure to save the folder to a shared repo so everyone pulls from the same version.

Step 5: Test and refine

A quick round of testing before you share a skill can save a lot of back and forth later. Test your skill with several realistic inputs to make sure it behaves the way you expect. Here’s what to look for:

• Does Claude apply the skill at the right moments, or does it need to be invoked manually?
• Does the output match the format and conventions you defined?
• Are the results consistent across different inputs, or do they vary?
• Does the skill stay out of the way on unrelated tasks?

When something’s off, find where Claude deviated, trace it back to a vague or missing instruction, tighten the language, and re-test. Most skills get meaningfully better after one or two of these loops.

Tips for writing skills your whole team can use

A skill that works perfectly in your hands can fall apart the moment someone else uses it. Here are a few practices that make the difference:

• Write instructions for the newest person on your team. Experts fill gaps automatically, but new teammates don’t. If the skill can’t guide someone with less context, it won’t hold up at scale.
• Keep each skill focused on one workflow. A skill that tries to cover too much becomes hard to trigger reliably and harder to maintain. When in doubt, split it into two.
• Be specific in the description, but not so narrow that it misses. A description that only activates on exact phrasing will fail on paraphrased requests. Test it against a few variations before sharing with the team.
• Version-control your skill alongside the work it references. If your conventions change, the skill should change with them. Letting them drift apart is how skills stop working.
• Treat updates like code changes. A changelog keeps everyone aligned and makes it easier to trace issues back to specific edits.

Start building with Figma

Learning how to create a skill in Claude Code is a one-time investment that pays off every session after. Figma’s tools give those skills somewhere to land, from the components in Figma Design to the specs developers work from in Dev Mode.

Here’s how to bring it all together:

• Map out the conventions and workflows you want to encode in FigJam before you start writing.
• Use Figma Design to build and maintain the components, tokens, and conventions your Claude Code skill references.
• Switch to Dev Mode to give developers direct access to accurate specs and live updates.
• Browse Figma Community skills for pre-built starting points you can adapt to your team’s workflow.