Claude Code skills: teach Claude to work your way

A Claude Code skill is a folder containing a SKILL.md file. Its header says what the skill does and when to use it; its body is the step-by-step procedure. Claude reads only the header until a request matches, then loads the instructions. You write a workflow down once and Claude follows it every time after.

This site's repository has ten skills in .claude/skills/, covering copywriting, copy editing, SEO audits and a few more. The content plan behind this blog was drafted with three of them. Below I explain how skills work, then build a small one for design work from scratch. Every field and path was checked against the official docs on 5 October 2026.

What is a skill in Claude Code?

The Claude Code docs describe skills as a way to bundle instructions, reference material and automation. They suggest creating one when you keep pasting the same instructions or checklist into the chat.

Designers have plenty of those: checking colour contrast, writing microcopy in a brand voice, catching components that use raw hex instead of tokens, drafting handoff notes. Each is a routine you already know by heart. A skill gives Claude the same routine.

Skills aren't exclusive to Claude Code. Anthropic calls the format Agent Skills, and it also works on claude.ai and through the API. Each surface keeps its own copy, though: skills in Claude Code live on disk and don't sync to claude.ai or the API by themselves.

How do skills compare with CLAUDE.md, prompts and MCP?

In this repo, AGENTS.md (imported by CLAUDE.md) holds rules like "no box-shadow anywhere" and "text uses weight 400 or 500 only". Claude needs those on every turn, so they belong there. The procedure for auditing a blog post's SEO is only needed during an SEO audit, so it is a skill. MCP solves a different problem, which I cover in What is MCP?.

How does Claude decide when to use a skill?

The Agent Skills docs call it progressive disclosure:

1. At startup, Claude reads only each skill's name and description, about 100 tokens per skill.
2. When a request matches, Claude reads the body of SKILL.md. The docs list this level as typically under 5,000 tokens.
3. When it needs more, Claude opens supporting files in the skill folder that SKILL.md points to.

So the description does most of the work. It has to say what the skill does and when to use it, in the words you actually type. Claude Code truncates it at 1,536 characters (combined with the when_to_use field), so put the key use case first.

You can also call a skill yourself by typing /skill-name at the start of a message. The docs note that old command files in .claude/commands/ now behave exactly like skills.

Where do skills live?

There are also skills deployed by an organisation and skills enabled on your claude.ai account. When names clash, enterprise wins over personal, and personal over project.

Here's the shape of a real skill in this repo:

.claude/skills/copywriting/
├── SKILL.md
├── references/
│   ├── ai-tells.md
│   ├── copy-frameworks.md
│   └── natural-transitions.md
└── evals/
    └── evals.json

SKILL.md holds the main procedure. Files in references/ are opened only when needed, such as the list of AI writing patterns to avoid.

What goes into a SKILL.md file?

YAML frontmatter starting on the very first line, then Markdown. The fields I find designers actually need:

The docs list more (model, context, paths, hooks and others). Your first skill won't need them.

How do you build a contrast-check skill?

I picked contrast because the thresholds are unambiguous and I check it constantly. On this site, magenta #ff009d reaches only 3.66:1 on white: fine as a button fill, a fail for body-size text. Grey #717171 hits 4.88:1 on white but drops to 4.60:1 on the #f8f8f8 section band. Re-checking pairs like these by hand after every palette change is exactly where things slip.

1. Create the folder as a personal skill, so it works in every project:

   Copy

   mkdir -p ~/.claude/skills/contrast-check

2. Create SKILL.md inside it:

   Copy

   ---
   name: contrast-check
   description: Audit text and background colour contrast against WCAG level AA in a component, CSS file or token file. Use when the user asks about contrast, legibility, whether a text colour passes, or wants a colour accessibility review.
   argument-hint: [file-path]
   allowed-tools: Read Grep
   ---
   
   # Contrast check
   
   Check the file $ARGUMENTS. If no argument is given, ask which file to check.
   
   ## WCAG AA thresholds
   - Normal text: at least 4.5:1.
   - Large text (24px and up, or 18.66px and up when bold): at least 3:1.
   - Borders, icons and focus rings of UI components: at least 3:1.
   
   ## Steps
   1. Read the project's colour token file to map each token to its value.
   2. Find every text colour and background colour that actually appear together in the file.
   3. Compute the ratio with the WCAG relative luminance formula, rounded to 2 decimals.
   4. Check secondary surfaces too, such as grey section bands and hover states, not only the main background.
   5. Do not edit any file. Report only.
   
   ## Report
   One table with columns: Location, Text colour, Background, Ratio, Text size, Pass or Fail, Suggested replacement token.
   End with one line giving the number of failing pairs.

3. Open Claude Code in a project and try it: /contrast-check components/blog/mdx/note.tsx. Or ask normally, something like "does the text in this file have enough contrast?", and see whether Claude loads the skill on its own.

4. Tune the description. If the skill doesn't trigger, the docs suggest adding the words you naturally use. If it triggers too often, make it narrower.

A few notes on that file. Claude Code replaces $ARGUMENTS with whatever you type after the skill name. allowed-tools: Read Grep lets Claude read and search files without asking during that turn. It doesn't restrict anything: your normal permission settings still apply. The thresholds come from WCAG success criteria 1.4.3 and 1.4.11, linked below.

A microcopy skill follows the same pattern, with voice rules and a few right and wrong examples in place of contrast thresholds. On the Car From Japan inquiry form I redesigned the button label, the form content and the confirmation screen, and the wording in that work is what I'd turn into a skill today. The project is in the inquiry form case study.

Is it safe to install someone else's skill?

Anthropic's Agent Skills docs are direct about it: use skills only from trusted sources, meaning ones you created or got from Anthropic. A skill can include instructions and code, so a malicious one can direct Claude to call tools or run code in ways that don't match its stated purpose, up to leaking data.

When I read an unfamiliar skill, I look for three things the Claude Code docs call out:

1. Broad allowed-tools. A skill can grant itself permission to run shell commands. The docs advise reviewing this field in repository skills before running Claude Code in a repo you don't trust.
2. Injected commands. The !`command` syntax in a SKILL.md runs a command on your machine before Claude even reads the content.
3. Content fetched from external URLs. The Agent Skills docs warn that fetched content can carry malicious instructions, and that a trustworthy skill can turn bad if its external dependencies change.

This applies when you clone someone else's repository too: its .claude/skills/ folder is picked up when you open Claude Code there.

Where should you start?

Pick something you've explained to Claude three times already. Write it as a SKILL.md in ~/.claude/skills/, run it a few times, then tune the description. If Claude Code isn't installed yet, start with installing Claude Code. Writing a SKILL.md is much like writing a good prompt, so how to write prompts for Claude applies straight away. For where skills fit in a full design-to-code workflow, read Claude Code for designers. And if your skill needs to know your design system, point it at your DESIGN.md instead of copying the rules into the skill.

If you want to talk about bringing a design system into an AI workflow, my about page has the ways to reach me.

Sources

• Anthropic, Use Skills in Claude Code
• Anthropic, Agent Skills overview
• Anthropic, Skill authoring best practices
• W3C, Understanding SC 1.4.3: Contrast (Minimum)
• W3C, Understanding SC 1.4.11: Non-text Contrast

Folder paths, frontmatter fields and security guidance checked against these pages on 5 October 2026.