Write your first Skill and watch Claude pick it up

You've seen what Skills are. Now you're going to build one — a personal PR description skill that gives Claude a consistent format to follow any time you ask for a PR write-up. By the end of this lesson, you'll have the skill on disk, loaded in Claude Code, and tested against a real diff. You'll also understand exactly what Claude does with it at startup and at request time.

1. Create the skill directory

Personal skills live in your home directory, so they follow you across every project on your machine. Each skill gets its own directory under ~/.claude/skills, and the directory name should match the skill name.

mkdir -p ~/.claude/skills/pr-description

2. Write the SKILL.md file

Inside that directory, create SKILL.md. The file has two parts separated by frontmatter dashes: the metadata Claude uses to match requests, and the instructions it follows after matching.

---
name: pr-description
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 following 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 together
- Mention any files deleted or renamed

The name field identifies the skill and should match the directory. The description field is the matching criteria — this is how Claude decides whether to use the skill at all. Everything after the second --- is the instruction content Claude follows when the skill activates.

3. Restart and verify

Claude Code loads skills at startup, so restart your session after creating a new one. Then check that the skill shows up in the available skills list — you should see pr-description there.

4. Test it with a real request

Make some changes on a branch, then ask Claude: "Write a PR description for my changes." Claude will tell you it's using the pr-description skill, check your diff, and produce a description following your template. Same format every time, across every project on your machine.

How skill matching actually works

When Claude Code starts, it scans four locations for skills: enterprise-managed settings, your personal ~/.claude/skills directory, the project's .claude/skills, and any installed plugins. For each skill, it loads only the name and description — not the full content. This is the detail that makes Skills context-efficient.

When you send a request, Claude compares your message against those descriptions. For example, "explain what this function does" would match a skill described as "explain code with visual diagrams" because the intent overlaps, even though the exact words differ. That's semantic matching in action.

Once Claude finds a match, it asks you to confirm before loading the full skill content into context. This confirmation step keeps you aware of what context Claude is pulling in, and gives you a way to decline if the match was wrong. After you confirm, Claude reads the complete SKILL.md file and follows its instructions.

Skill priority: who wins a name collision

If you clone a repo that has a code-review skill, and you already have a personal code-review skill, which one wins? There's a clear priority order, highest to lowest:

1. Enterprise — managed settings deployed by your organisation
2. Personal — your own ~/.claude/skills
3. Project — .claude/skills inside a cloned repository
4. Plugins — skills from installed plugins

Enterprise always wins. This lets organisations enforce standards through managed skills while still allowing individual customisation — as long as the names don't clash. If your company has an enterprise code-review skill and you create a personal one with the same name, the enterprise version takes precedence every time.

The fix is to use descriptive names rather than generic ones. Instead of just review, use frontend-review or backend-security-review. Collisions become much rarer once names describe what the skill actually does.

Updating and removing skills

To update a skill, edit its SKILL.md file. To remove one, delete its directory. Either way, restart Claude Code for the change to take effect — the startup scan is where skills enter the runtime, so nothing you change mid-session will be seen until the next start.