Creating Your First Skill
Three Steps to a Skill
Let's build a real skill: a personal one that writes PR descriptions in a consistent format. Because it's personal, it lives in your home directory and works across all your projects. Creating a skill is three steps — make a directory, write SKILL.md, restart and test.
# 1. Create a directory in your personal skills folder.
# The directory name becomes the command you type.
mkdir -p ~/.claude/skills/pr-descriptionThe directory name IS the command
This is a subtle but important rule: the command you type (/pr-description) comes from the DIRECTORY name, not the frontmatter. The frontmatter 'name' field is just the display label in skill listings. So .claude/skills/deploy-staging/SKILL.md gives you /deploy-staging.
Writing SKILL.md
Inside the directory, create a file named exactly SKILL.md. It has two parts: YAML frontmatter (the metadata Claude uses to decide when to apply the skill) and the Markdown body (the instructions Claude follows once activated).
---
description: Writes pull request descriptions. Use when creating a PR,
writing a PR, or when the user asks to summarize changes for a pull request.
---
When writing a PR description:
1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description in this format:
## What
One sentence explaining what this PR does.
## Why
Brief context on why this change is needed.
## Changes
- Bullet points of specific changes made
- Group related changes; note any files deleted or renamedOnly description is recommended
Per the official spec, all frontmatter fields are optional — only description is recommended so Claude knows when to use the skill. If you omit description, Claude uses the first paragraph of the body. (The next lesson covers every field.)
Testing — and How Matching Works
After creating a skill by editing files, restart Claude Code so it's picked up, then verify it with 'What skills are available?'. Two ways to test it: let Claude invoke it automatically by asking something that matches the description ('write a PR description for my changes'), or invoke it directly with /pr-description.
Claude semantically matches your request to skill descriptions; on a match it loads the full body (after a confirmation), or you invoke it directly by name.
Behind the scenes: when Claude Code starts, it scans the skill locations but loads only names + descriptions. On a matching request it loads the full SKILL.md and follows it. In a regular session you'll see a confirmation that the skill is loading, keeping you aware of what context is being pulled in.
Updating, Removing, and Live Reload
Maintaining skills is simple: to update one, edit its SKILL.md; to remove one, delete its directory. Helpfully, Claude Code watches your skill directories — edits to an existing SKILL.md under ~/.claude/skills/ or the project .claude/skills/ are picked up within the current session. Only creating a brand-new top-level skills directory requires a restart.
- •Update a skill → edit its SKILL.md (live-reloaded in-session).
- •Remove a skill → delete its directory.
- •New top-level skills directory that didn't exist at startup → restart Claude Code.
- •Verify what's loaded → ask 'What skills are available?'
Next
You've shipped a working skill. Next we open up the full SKILL.md frontmatter — every field you can use to control naming, matching, tools, models, and more.
Key Takeaways
- ✓Create a skill in three steps: make a directory under ~/.claude/skills/, write SKILL.md, restart and test.
- ✓The command you type comes from the DIRECTORY name (deploy-staging/ → /deploy-staging); frontmatter 'name' is only the display label.
- ✓SKILL.md = YAML frontmatter (matching metadata) + Markdown body (instructions); only description is recommended, all fields optional.
- ✓Test two ways: ask something matching the description (automatic) or invoke directly with /skill-name.
- ✓Matching is semantic on the description; on a match Claude loads the full body (with a confirmation) — at startup only names + descriptions are loaded.
- ✓Maintenance: edit SKILL.md to update (live-reloaded in-session), delete the directory to remove; a brand-new top-level skills directory needs a restart.
Check Your Understanding
Test what you learned in this lesson.
Q1.Where does the command you type to invoke a skill come from?
Q2.Which frontmatter field is recommended (the rest being optional)?
Q3.What does Claude load at startup for each skill?
Q4.You edited an existing SKILL.md under ~/.claude/skills/. What must you do for it to take effect?
Practice This Lesson