In short
A Claude Code skill is a folder with a SKILL.md file that teaches Claude Code how to do one kind of task. Claude Code reads each skill's name and description, and loads the full instructions only when a task matches. That makes skills the right place for detailed, repeatable workflows, like building a landing page or checking a page on mobile. Below: how a skill is built, a short example, and three ready-made design skills.
Updated
Where the file goes
Project skills go in .claude/skills/<skill-name>/SKILL.md in your repo, so everyone on the project gets them. Personal skills go in ~/.claude/skills/<skill-name>/SKILL.md. A skill folder can also hold scripts and reference files the skill points to.
Claude Code skills templates: structure
name
Short, lowercase, hyphenated. It becomes the skill's identifier.
description
The most important line. Say what the skill does and exactly when to use it; Claude Code decides whether to load the skill from this.
Instructions
The steps, rules and checks, written as instructions. Loaded only when the skill is used, so they can be detailed.
Extra files
Optional scripts, templates or reference docs in the same folder, linked from SKILL.md.
A short example
--- name: responsive-check description: Use after changing a page, or when the user mentions mobile or layout bugs. Checks 375, 768 and 1440 px and fixes what breaks. --- # Responsive check 1. Open the page at each width. 2. Fix horizontal scroll, tiny tap targets and broken stacks. 3. Report what you fixed.
Building a Claude Code skill, step by step
Pick a task you repeat and explain the same way each time, like building a landing page, checking a page on mobile or writing release notes. That repetition is the signal: the instructions belong in a skill instead of your messages.
Create the folder .claude/skills/<name>/ and a SKILL.md inside it. Write the description first and spend the most time on it. Claude Code reads every skill's description at the start, and only loads the full instructions when a request matches, so a vague description means the skill never runs.
Write the body as steps: what to read first, how to do the work, and how to check it. Keep long reference material, like a full design spec or a list of components, in separate files in the same folder and link to them from SKILL.md, so they load only when the skill needs them.
Test it by asking for the task in plain words without naming the skill. If Claude Code does not pick it up, sharpen the description with the exact phrases people use.
Ready-made Claude Code skills templates files
Complete files you can copy into your project and fill in. Each one works with the BrowserMoon design templates, so what the tool builds also looks professional.
Frontend design skill
A Claude Code skill that loads when you ask for UI work. It makes Claude Code plan the layout from your template, build with your components and check its own result.
.claude/skills/frontend-design/SKILL.md--- name: frontend-design description: Use when building or changing any page, component, layout or style in this project. Makes the UI match the design template in design/template.html and the project's design rules. --- # Frontend design
Landing page skill
A Claude Code skill for building landing pages: the section order that converts, copy rules, and a final check against the template.
.claude/skills/landing-page/SKILL.md--- name: landing-page description: Use when building or rewriting a marketing or landing page. Gives the section order, copy rules and checks for a page that converts, built from design/template.html. --- # Landing page
Responsive check skill
A Claude Code skill that checks a page at phone, tablet and desktop widths and fixes overflow, tiny tap targets and broken layouts.
.claude/skills/responsive-check/SKILL.md--- name: responsive-check description: Use after building or changing a page, or when the user mentions mobile, responsive, overflow or layout bugs. Checks the page at 375, 768 and 1440 pixels and fixes what breaks. --- # Responsive check
Using Claude Code skills with a design template
A design skill is the best way to make Claude Code use your template on every UI task. The skill's first step reads design/template.html, its middle steps build with your components, and its last step compares the result with the template.
Because the skill loads only for UI work, it can be detailed without costing context on backend tasks.
SaaS landing page · Analytics dashboard · Pricing section · Dark gradient hero · Account settings · AI chat interface
Best practices
- ·Write the description as a trigger: "Use when...". Vague descriptions mean the skill never loads.
- ·One skill, one job. Split big workflows into several skills.
- ·End every skill with a check step, so Claude Code verifies its own work.
- ·Keep reference material in separate files in the skill folder and link to it, so it loads only when needed.
Common mistakes and how to fix them
A description that says what, not when
Start with "Use when..." and list the requests that should trigger it.
One giant skill for everything
Split it: one for landing pages, one for responsive checks, one for reviews.
No check step
End with a verification step and a short report, so you see what was done.
Putting always-on rules in a skill
Rules that apply to every task belong in CLAUDE.md, not a skill that may not load.
Skills vs CLAUDE.md vs commands vs agents
These files tell Claude Code how to work. A design template tells it what to build. Use both.
Claude Code templatesFrequently asked questions
What are Claude Code skills?
Folders with a SKILL.md file that give Claude Code instructions for a specific kind of task. Claude Code loads a skill when your request matches its description.
Where do Claude Code skills go?
In .claude/skills/<name>/SKILL.md in your project, or in ~/.claude/skills for personal skills that work in every project.
What is the difference between a skill and CLAUDE.md?
CLAUDE.md is always loaded and holds short, project-wide rules. A skill loads only when needed, so it can hold long, detailed instructions for one task.
What is the difference between a skill and an agent?
A skill adds instructions to the current conversation. An agent (subagent) is a separate assistant with its own context and tools that Claude Code hands a task to.
How do I make Claude Code use my skill?
Write a clear description that says when to use it. You can also ask for it by name.
Can a skill include scripts?
Yes. A skill folder can hold scripts and reference files; SKILL.md tells Claude Code when to run or read them.
How many skills can I have?
As many as you need. Only the short descriptions are always in context, so many focused skills cost little.
Do skills work in every project?
Personal skills in ~/.claude/skills do. Project skills in .claude/skills work in that repo and are shared through git.
Claude Code templates by category
Related