Notes
Claude
Introduction to Agent Skills
Creating Your First Skill

Creating Your First Skill

Note

TL;DR

  • A skill is a directory containing a SKILL.md file with metadata (name, description) in frontmatter and instructions below
  • Claude loads only skill names and descriptions at startup, then matches incoming requests against those descriptions using semantic matching
  • You get a confirmation prompt before Claude loads the full skill content into context
  • Priority for name conflicts: Enterprise → Personal → Project → Plugins
  • To update a skill, edit its SKILL.md. To remove one, delete its directory. Always restart Claude Code for changes to take effect

Creating a Skill

  • The name identifies your skill.
  • The description tells Claude when to use it — this is the matching criteria.
  • Everything after the second set of dashes is the instructions Claude follows when the skill is activated.

Example:

---
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

Testing Your Skill

Claude Code loads skills at startup, so restart your session after creating one. You can verify it’s available by checking the available skills list.

How Skill Matching Works

When Claude Code starts, it scans four locations for skills but only loads the name and description — not the full content.

  • Enterprise: managed-settings.json
  • Personal: ˜/.claude/skills
  • Project: project/.claude/skills
  • Plugins: project/.claude-plugin/plugin.json

When you send a request, Claude compares your message against the descriptions of all available skills.

  • Example: “Explain what this function does” would match a skill described as “explain code with visual diagrams” because the intent overlaps.

Once a match is found, Claude asks you to confirm loading the skill. This confirmation step keeps you aware of what context Claude is pulling in. After you confirm, Claude reads the complete SKILL.md file and follows its instructions.

Skill Priority

The priority order (from high to low):

  1. Enterprise — managed settings, highest priority
  2. Personal — your home directory (~/.claude/skills)
  3. Project — the .claude/skills directory inside a repository
  4. Plugins — installed plugins, lowest priority

If your company has an enterprise “code-review” skill and you create a personal “code-review” skill with the same name, the enterprise version takes precedence.

To avoid conflicts, use descriptive names.

  • Example: Instead of just “review,” use something like “frontend-review” or “backend-review.”

Updating and Removing Skills

Update: Edit its SKILL.md file

Remove: Delete its directory

Restart Claude Code after any changes for them to take effect.

docs