Skill Files
Give Claude domain expertise with drop-in markdown files.
The Problem
When you ask Claude to build a UI, it produces something that works — but it’s generic. The spacing is inconsistent, the animations feel arbitrary, the accessibility is an afterthought. Claude is a great builder, but it doesn’t know your standards unless you tell it.
Your CLAUDE.md solves half of this. It tells Claude what your project is — the tech stack, the current state, what you’re building. But it doesn’t tell Claude how to build well in a specific domain.
That’s what skill files are for.
What Are Skill Files?
Skill files are .md files you place in your project root alongside CLAUDE.md. They contain domain expertise — reusable knowledge about how to do something well.
Think of it this way:
- CLAUDE.md = “Here’s my project” (project context)
- Skill files = “Here’s how to do this well” (domain knowledge)
Your CLAUDE.md tells Claude you’re building a weather app in React. A skill file tells Claude how to use a consistent spacing scale, or how to make the UI accessible, or how to animate things tastefully.
How Claude Reads Them
Claude Code automatically reads any file named CLAUDE.md in your project root. For skill files, you add them to your CLAUDE.md so Claude picks them up. Add a section like this at the bottom of your CLAUDE.md:
## Skill Files
Read these files for domain conventions:
- accessibility.md
- design-system.md
- animation.mdWhen you start a session, Claude reads your CLAUDE.md, sees the references, and has access to those files when it needs them.
Alternatively, you can paste skill file content directly into your CLAUDE.md under a relevant heading — whatever works for your workflow.
Available Skill Files
We’ve written fifteen skill files covering the most common areas where Claude’s default output falls short. Each page has the full markdown content ready to copy.
| Skill File | Filename | What It Teaches Claude |
|---|---|---|
| Design System | design-system.md | Consistent spacing, color tokens, typography, component patterns |
| Accessibility | accessibility.md | Semantic HTML, contrast, focus states, ARIA, keyboard navigation |
| Apple HIG | apple-hig.md | SF Symbols, system fonts, native navigation, platform conventions |
| SwiftUI Patterns | swiftui-patterns.md | Clean view composition, state management, navigation, persistence |
| Responsive | responsive.md | Mobile-first breakpoints, fluid layouts, touch targets, responsive type |
| Animation | animation.md | Duration/easing defaults, what to animate, reduced motion, performance |
| Deploy Ready | deploy-ready.md | Meta tags, env vars, error boundaries, performance, deployment gotchas |
| Dark Mode | dark-mode.md | Semantic color tokens, system preference, elevation, image handling |
| Forms | forms.md | Validation, error states, multi-step flows, input types, mobile UX |
| UI Copy | ui-copy.md | Microcopy, error messages, empty states, CTAs, tone and voice |
| Image Handling | image-handling.md | Aspect ratios, lazy loading, responsive images, galleries |
| Local-First Data | local-first.md | Simple persistence patterns — localStorage, UserDefaults, SwiftData |
| Data Visualization | data-viz.md | Clean charts, accessible colors, responsive data displays |
| Typography | typography-craft.md | Font loading, vertical rhythm, whitespace, type craft |
| Performance | performance.md | Lazy loading, efficient rendering, minimal bundles |
How to Use
- Pick the skill file(s) relevant to your project
- Copy the markdown content from the skill file page
- Save it as a
.mdfile in your project root (e.g.,accessibility.md) - Reference it from your
CLAUDE.md(see “How Claude Reads Them” above)
You can use multiple skill files at once. A web app might use design-system.md + accessibility.md + responsive.md + forms.md. A macOS app might use apple-hig.md + animation.md + dark-mode.md.
How They Differ from CLAUDE.md Templates
| CLAUDE.md Templates | Skill Files | |
|---|---|---|
| Purpose | Describe your specific project | Teach general domain knowledge |
| You edit them | Yes — fill in your app name, stack, etc. | No — use as-is |
| Per project | One per project | Mix and match as needed |
| Content | Project-specific context | Reusable expertise |
When to Use Which
- Starting a new project? Start with a CLAUDE.md template, then add skill files for the areas that matter most.
- Output looks generic? Add the Design System skill file for more intentional visual decisions.
- Building for a specific platform? Add Apple HIG for macOS/iOS, or Responsive for web.
- Shipping to real users? Add Accessibility and Deploy Ready.
- Forms feel clunky? Add Forms for proper validation, error states, and mobile input handling.
- UI text is generic? Add UI Copy for clear error messages, helpful empty states, and action-oriented buttons.
- Dark mode looks wrong? Add Dark Mode for proper token architecture and dual-theme support.
Writing Your Own Skill Files
The nine skill files here are starting points. The real power is writing your own for domains specific to your work.
A good skill file follows a simple pattern:
- State the domain — What area of expertise is this? (e.g., “Data Visualization Conventions”)
- List concrete rules — Not vague principles, but specific values and patterns Claude can apply directly. “Use 8px spacing” is better than “use consistent spacing.”
- Include code examples — Show the actual CSS, HTML, or Swift that Claude should produce.
- Cover common mistakes — Tell Claude what not to do. “Never animate layout properties” is as useful as “animate opacity and transform.”
Here’s what the structure looks like:
# [Domain] Conventions
Follow these [domain] conventions for all UI work in this project.
## [Category 1]
- Specific rule with concrete values
- Another rule with examples
## [Category 2]
- More rules Claude can directly applyThe key: be specific and prescriptive. Claude follows instructions well, but it can’t guess your preferences. “Make it look good” doesn’t help. “Use an 8px spacing scale, 150ms ease-out transitions, and 4.5:1 contrast ratios” does.
Building a Personal Skill Files Repo
Once you’ve written skill files that work for you, keep them in a dedicated repo so you can reuse them across every project.
my-skill-files/
├── design-system.md
├── accessibility.md
├── animation.md
├── responsive.md
├── apple-hig.md
├── deploy-ready.md
├── dark-mode.md
├── forms.md
├── ui-copy.md
├── data-viz.md ← your custom ones
├── brand-voice.md
└── README.mdWhen you start a new project:
- Copy the relevant files from your repo into the project root
- Reference them from your
CLAUDE.md - Start building
Over time your collection grows. You might add a brand-voice.md that teaches Claude your writing style, or a data-viz.md for chart conventions, or a motion-design.md with your studio’s animation language.
This is one of the highest-leverage things you can do with Claude — you’re essentially building a library of expertise that makes every future project better from the start.
Tips
- Start with one or two — You don’t need all nine. Pick the ones most relevant to what you’re building right now.
- Skill files are reusable — Once you have them, copy them into every new project.
- They stack — Each skill file covers a different domain. Using multiple gives Claude broader expertise.
- No editing needed — Unlike CLAUDE.md templates, skill files work as-is. Just drop them in.
- Iterate on them — If Claude keeps making the same mistake, add a rule to the relevant skill file. Your skill files get better over time.