Build your first skill
Plan, write, and organize a SKILL.md file
⏱ Est. ~7 min
01 · Read
Before you write a single line, you need to identify a repeatable workflow.
Think about what you keep telling Claude Code: "Use functional components." "Write tests first." "Use conventional commits." "Don't add comments for obvious code."
Every one is a skill candidate. The best skills capture a workflow you follow every single time — not a one-off request.
Ask yourself: "What instruction do I type to Claude Code at least once a week?" That's your first skill.
Key points
- Good skills capture repeatable workflows, not one-off tasks
- Think about instructions you type every Claude Code session
- Start with one concrete workflow, not everything at once
- Skills should have opinions — clear rules, not vague suggestions
02 · Code example
Every SKILL.md starts with YAML frontmatter between --- lines. Here are the three main fields.
YAML Frontmatter
---
name: Code Reviewer
description: Reviews code for bugs, style, and best practices
instructions: Use this skill when reviewing pull requests or code changes
---
name is the skill's display name in the /skill list. description tells Claude (and you) what this skill does. instructions give Claude a hint about when to activate this skill. All three are optional, but strongly recommended.
03 · Quiz
You just saw three standard YAML frontmatter fields. Which of these is not one of them?
- name
- description
- language
- instructions
04 · Step-through
Let's build a real skill step by step. We'll make a "Code Reviewer" skill that enforces your team's review standards.
1. Create the skill folder
Create the directory structure inside your project. Run: mkdir -p .claude/skills/code-reviewer. The -p flag creates parent directories if they don't exist. This puts the skill inside your project, where it can be committed to git.
2. Write the YAML frontmatter
Open .claude/skills/code-reviewer/SKILL.md and add a metadata block. Start with a line of ---, add name, description, and instructions fields, and close with another line of ---.
3. Add the instruction body
Below the closing ---, write your review rules in natural language. Use markdown headings to organize sections and bullet lists for concrete rules. Be specific — "check for SQL injection in user input" is way better than "review the code."
4. Test with /skill
In a Claude Code conversation, type /skill and see your new skill in the list. Select it to activate. Now ask Claude to review some code — it should follow your rules. If not, refine and try again.
05 · Code example
Here's the completed "Code Reviewer" skill — a complete, production-ready SKILL.md.
code-reviewer/SKILL.md
---
name: Code Reviewer
description: Reviews code changes for bugs, security, and style
instructions: Use when asked to review code, PRs, or diffs
---
## Review Checklist
When reviewing code, check for:
- **Security**: SQL injection, XSS, command injection, hardcoded secrets
- **Error handling**: Are errors caught? Are they logged? Do they fail gracefully?
- **Edge cases**: What happens with empty input? Null values? Very large data?
- **Naming**: Are variables and functions named clearly?
- **Tests**: Are there tests for the new code? Do existing tests still pass?
## Output Format
Structure your review as:
1. **Summary** — one sentence overview
2. **Issues** — bullet list, severity (high/medium/low)
3. **Suggestions** — optional improvements (not blockers)
The body uses standard markdown — headings, bold, bullet lists. Claude treats it as instructions and follows them. The review checklist tells Claude what to look for, and the output format ensures every review is consistent and structured.
06 · Fill in the blank
The YAML frontmatter in a SKILL.md file is wrapped by two lines of _____
07 · Drag to sort
A SKILL.md file has a specific structure. Think about what Claude reads first when loading a skill, and sort these parts top to bottom.
(This section is interactive — please enable JavaScript.)
Other lessons in this chapter
⚠ The full interactive experience needs JavaScript. Please enable it and reload.
※ This is an independent Traditional Chinese teaching project — not an official Anthropic product. Claude™ is a trademark of Anthropic, PBC.