S

Skill

Pick

A skill is a folder of instructions an AI agent loads when a task matches: how to write one, and how to make it reliable.

6 chapters109 tutorials

01 · Introduction

What a skill is

A skill is a reusable set of instructions for an AI agent, saved as files instead of typed into chat every time.

The simplest skill is one folder with one file, SKILL.md. At the top it says what the skill is for ("deploy this project", "write a weekly report in our format"). Below that are the steps, rules and examples the agent should follow.

When you ask the agent for something that matches the description, it reads the skill and follows it. In Claude Code you can also call one directly by typing /<skill-name>.

Think of it as a recipe card: the agent is the cook, the skill is the card, and the same card gives the same dish every time.

02 · When to use it

When to write a skill

Write one when you notice yourself explaining the same thing more than twice:

  • A procedure with fixed steps: release, deploy, back up, onboard a client.
  • A house style: how reports, emails or commit messages must look.
  • A checklist: what to verify before shipping or sending.
  • A tool that needs special knowledge: your billing system, a vendor's API, a legacy script.

Do not write one for a one-off task, or for general knowledge the model already has. A skill earns its place by saving repeated explanation.

03 · Setup

Writing your first skill

  1. Make a folder: .claude/skills/weekly-report/ inside the project (or ~/.claude/skills/ for every project).
  2. Create SKILL.md with a short header and the instructions:
---
name: weekly-report
description: Write the Monday status report from last week's git log and the task board.
---

# Weekly report

1. Run `git log --since="7 days ago" --oneline`.
2. Group the commits by project.
3. Write three sections: Done, In progress, Blocked.
4. Keep it under 200 words. No adjectives.
  1. Put extra material in the same folder: a template file, a script to run, a reference document. Link to them from SKILL.md so the agent reads them only when needed.
  2. Try it: ask the agent for a weekly report, watch what it does, then fix the wording of any step it got wrong.

The description line matters most. The agent uses it to decide whether the skill applies, so say plainly when to use it.

04 · How to use it

Day-to-day use

  • Keep SKILL.md short. Steps, rules, examples. Move long reference text to separate files.
  • Write rules as facts ("commit messages start with a verb"), not as pleas ("please try to").
  • Add a "Done when" line so the agent knows when to stop.
  • Version the skill with the project in git. Teammates and their agents get it for free.
  • When the agent makes the same mistake twice, fix the skill, not the chat.
  • Review skills every few months. A stale step is worse than no step.

05 · Pitfalls

Pitfalls

  • Vague descriptions. "Helps with reports" will not trigger reliably. Name the task and the trigger words.
  • Too many skills. Overlapping descriptions make the agent pick the wrong one. Merge or sharpen them.
  • Secrets in the folder. A skill is plain text and often shared. Keep keys and passwords in environment variables.
  • Untested steps. Every command in a skill should have been run once by a person.
  • Skills from strangers. A downloaded skill can tell the agent to do anything. Read it before installing.

06 · Resources

Where to go next

Skills are the instruction layer. Tools (MCP) are how the agent reaches the outside world, and workflows chain several steps into one run.

My notes

Sign in to keep private notes on this handbook.Sign in