Claude Code Skills for Frontend: How to Write a SKILL.md

Published October 2, 2026 · 12 min read · by the CSS DNA team

Quick answer: A Claude Code skill is a folder containing a SKILL.md file: YAML frontmatter, where description is the only recommended field, followed by Markdown instructions. Save it as .claude/skills/<name>/SKILL.md and Claude loads it when your request matches the description, or when you type /<name>. For front-end work, the most useful skill makes Claude read your DESIGN.md or tokens.json before it writes any UI.

Skills are the part of Claude Code that fixes the generic-looking UI problem without bloating every session. Instructions in CLAUDE.md load into every conversation, including the ones about database migrations. A skill’s full text loads only when the work calls for it. This guide covers the frontmatter as Anthropic documents it today, a complete design-system skill you can copy, and a builder that validates your SKILL.md as you type.

The correction: the description limit isn’t 1,024 characters

Most skill tutorials say the description field is capped at 1,024 characters and that name is required. Both rules are real, but they come from the Agent Skills specification, which governs uploads to claude.ai and the Skills API. Claude Code works differently.

Per the Claude Code skills reference, every frontmatter field is optional, name defaults to the directory name, and the combined description plus when_to_use text is truncated at 1,536 characters in the skill listing Claude sees. That cap was raised from 250 characters in v2.1.105 (April 13, 2026), which is why older posts say 250, and you can change it with the skillListingMaxDescChars setting.

One more behavior worth knowing before you write frontmatter: Claude Code ignores a field it doesn’t recognize without reporting an error. Type disable_model_invocation with underscores and the skill loads normally, with the setting off. Field names use hyphens, with one exception, when_to_use.

Where skills live

When two skills share a name, enterprise beats personal and personal beats project. A skill also beats a file of the same name in .claude/commands/, the older format that still works. Project skills load from the directory you start in and every parent up to the repo root, so a session started in packages/web/ still sees root skills.

SKILL.md frontmatter, field by field

These are the fields that matter for front-end skills. The full reference also lists arguments, disallowed-tools, background, hooks, shell, metadata, license and compatibility.

Three parsing details from the docs. Frontmatter is only read when the opening --- is the file’s first line. If the YAML between the markers doesn’t parse, the skill still loads, with no fields set, so /name works but automatic matching doesn’t. Booleans accept yes, no, on, off, 1 and 0 as well as true and false.

If you plan to upload the same skill to claude.ai or the Skills API, only six fields are allowed there: name, description, license, compatibility, metadata and allowed-tools. Anything else fails with a hard “Unexpected key(s) in SKILL.md frontmatter” error, and the spec’s naming rules apply: 1–64 characters, lowercase letters, digits and single hyphens, matching the folder name.

A complete design-system skill

Here is the skill we would add to any project where Claude writes UI. It assumes two files at the repo root: a DESIGN.md that explains the design system in prose, and a tokens.json holding the raw values in the W3C design tokens format. Both are what you would get from extracting a site’s tokens or writing them by hand.

.claude/skills/design-system/
└── SKILL.md

DESIGN.md        # prose: which token for what, and what never to do
tokens.json      # values: colors, type scale, spacing, radii, shadows

And the skill itself:

---
name: design-system
description: Applies this project's design tokens and UI rules. Use when creating, restyling or reviewing components, pages, CSS or Tailwind classes.
when_to_use: Requests like "build a settings page", "make this look better", "fix the spacing", "add dark mode".
paths:
  - "src/**/*.{tsx,jsx,css}"
---

# Design system

Before writing or changing any UI code, read DESIGN.md at the project root.
tokens.json holds the exact values; DESIGN.md says when to use each one.
These rules apply to every UI edit for the rest of the task, not only the first.

## Checklist for every UI change

- Colors: use a token (CSS variable or Tailwind theme key). Never a raw hex,
  rgb() or a default palette class such as bg-indigo-500.
- Type: font sizes come from the type scale steps in DESIGN.md. Take
  line-height and weight from the same step. No arbitrary px or rem values.
- Spacing: padding, margin and gap use the spacing scale only. An off-scale
  value like 13px or 18px is a bug.
- Radii and shadows: use the named tokens.
- Contrast: body text at least 4.5:1 against its background; large text
  (24px, or 18.66px bold) and UI component borders at least 3:1. Check
  every color pair you introduce.
- States: interactive elements get hover, focus-visible and disabled styles.
- Reuse components from src/components/ui before creating new ones.

## Before you finish

List any token you needed but could not find, and any raw value you kept,
with the reason. Do not invent new tokens.

A few choices in that file are deliberate.

The description leads with the use case, because the docs say to put the key use case first: it’s what survives truncation, and it’s what Claude matches against. The trigger phrases live in when_to_use, which is appended to the description in the listing.

paths scopes automatic loading to UI files. Without it, Claude may load the skill for any request that sounds visual. With it, Claude loads it automatically only when it’s working with matching files, and you can still run /design-system by hand.

The line about applying the rules “for every UI edit for the rest of the task” comes straight from Anthropic’s troubleshooting advice. Skill content stays in the conversation after it loads, but Claude Code doesn’t re-read the file, so one-time phrasing (“check the tokens”) tends to get applied once. After auto-compaction, only the first 5,000 tokens of each invoked skill are carried forward, which is another reason to keep the checklist near the top and the file short. The docs suggest staying under 500 lines and moving reference material into separate files in the skill folder.

The skill reads DESIGN.md instead of pasting the tokens in. That keeps the skill small, and it means the token file stays the single source of truth for every agent, including the ones that don’t support skills. For how that file is structured, see DESIGN.md for AI coding agents.

Then comes the slow part: filling tokens.json with values that are actually right. Pulling forty colors, a type ramp and a spacing scale out of DevTools by hand, element by element, takes an afternoon, and one wrong hex teaches the agent the wrong palette.

Skills vs CLAUDE.md vs subagents vs MCP

All four can make Claude better at UI, and they get confused constantly. This table follows Anthropic’s features overview.

The docs’ rule of thumb: if Claude should always know it, it goes in CLAUDE.md; if it’s reference material Claude needs sometimes, or a workflow you trigger by name, it’s a skill. Keep CLAUDE.md under 200 lines, and move anything bigger out. Our CLAUDE.md vs AGENTS.md guide covers how those files load.

Skills and subagents also combine in two directions. A skill with context: fork runs its body as the task for a subagent, which doesn’t see your conversation, so the body must be a complete instruction and not a list of guidelines. The docs warn that a forked skill containing only conventions “returns without meaningful output.” Going the other way, a custom subagent in .claude/agents/ can preload skills through its skills field, which injects their full content at startup. A design-audit subagent that preloads design-system is a sensible pairing.

MCP and skills pair the same way, per the docs: MCP provides the connection, and a skill teaches Claude how to use it well.

How to make Claude Code’s UI look better

The skill does most of the work, but only if the values behind it are specific. A model with no design system in context returns the average of its training data, which is how every AI-generated UI ends up looking the same. Adjectives like “modern” or “clean” in a skill don’t change that, because they describe the average. Concrete tokens, a short list of things never to do, and one named reference site do. If you’re basing the look on an existing site, check its fonts with the Font Finder before you write them into DESIGN.md.

How to check and debug a skill

• Ask Claude “What skills are available?” If yours isn’t listed, the folder is in the wrong place or named synced or anthropic-skills, both of which are reserved.
• Run claude plugin validate .claude/skills (v2.1.233 or later) to find a SKILL.md whose frontmatter doesn’t parse, or start with --debug to see the parse error.
• If it never triggers, put words users actually say into description or when_to_use. If it triggers too often, make the description narrower or add disable-model-invocation: true.
• Check the Skills row in /context for the listing’s real size, and run /doctor to see which skills cost the most. /skill-doctor shows how often each one is used.
• If Claude follows a rule at first and drops it later, reword it to apply to the whole task. If the rule must hold every time, make it a hook; the docs point out you can define one in the skill’s own hooks frontmatter.