Claude Code Skills: How to Create and Use Agent Skills

Subagents give Claude Code specialized workers and slash commands give it repeatable prompts, but skills give it something different: reusable expertise it can pull in exactly when a task calls for it. A skill packages a set of instructions and any supporting files into a bundle that Claude loads on demand, so you teach the agent how to do something once and it knows it forever. This guide explains what skills are, how the SKILL.md format and progressive disclosure work, when to reach for a skill over a subagent or command, and how to install ready-made skills in one line.

What are Claude Code skills?

A skill is a folder containing a SKILL.md file — instructions written in Markdown — plus any scripts, templates, or reference documents that support them. When your request matches what a skill is for, Claude Code loads that skill and follows its guidance, gaining a capability it did not have a moment earlier. The classic examples are format-specific know-how (filling in a spreadsheet, producing a slide deck, following a house documentation style) or a multi-step workflow you want performed the same way every time.

The defining trait is that skills are model-invoked. You do not trigger a skill by typing a command; Claude decides to use it based on the task, the same way a person reaches for the right reference when a problem calls for it. That makes skills feel like latent expertise: always available, activated only when relevant. The ToolZip skills catalog is the largest of the Claude Code component types, which reflects how much reusable know-how the community has already packaged up.

Skills vs subagents vs commands

Claude Code has three main ways to extend behavior, and skills are often confused with the other two. The distinction is about what each one is:

In short: a skill is know-how the main agent gains, a subagent is a worker it hands off to, and a command is a prompt you fire yourself. They compose — a subagent can use skills, and a command can invoke a workflow that a skill defines. For a deeper comparison, see the dedicated skills vs agents vs commands breakdown; for the other two, the agents guide and commands guide go into detail.

How a skill is structured

Every skill is a directory whose name is the skill name, containing at minimum a SKILL.md file. That file has YAML frontmatter and a Markdown body:

---
name: pdf-report
description: Generate a polished PDF report from project data. Use when
  the user asks for a report, summary document, or exportable PDF.
---

# PDF Report Skill

When asked to produce a report:
1. Gather the metrics from data/metrics.json.
2. Fill in the template at templates/report.md, keeping section order.
3. Convert to PDF with scripts/build-pdf.sh and save to out/.
Always include a title, date, and a one-paragraph executive summary.

Alongside SKILL.md, the folder can hold whatever the instructions reference — a templates/ directory, a scripts/ directory, example files, or longer reference docs. The two frontmatter fields do the heavy lifting: name identifies the skill, and description tells Claude when to use it. As with subagents, the description is the routing signal, so write it in terms of the trigger — the situations and phrasings that should activate it.

Progressive disclosure: why skills scale

Skills are built around an idea called progressive disclosure, and it is what keeps them cheap. Claude does not load the full contents of every skill into context up front. Instead it sees only the lightweight name and description of each available skill. When a task matches, it loads that skill's SKILL.md body; and only if the instructions point to a supporting script or reference file does it read that file too.

The result is that you can have many skills installed, and dozens of pages of supporting material, without any of it taxing context until it is actually needed. This is the mechanism that lets skills carry real depth — a full workflow, a detailed style guide, a library of examples — while staying essentially free when they are dormant.

Creating your first skill

Rolling your own is straightforward:

1. Create .claude/skills/your-skill-name/ in your project (or under ~/.claude/skills/ for a personal skill).
2. Add a SKILL.md with a precise name and a trigger-oriented description.
3. Write the body as clear, ordered instructions — what to do, in what sequence, and what the output should look like.
4. Drop in any supporting files the instructions reference, and point to them by relative path.
5. Start a session and try a request that should trigger it; refine the description until activation is reliable.

The most common mistake is a vague description. "Helps with documents" will rarely fire at the right moment; "Use when the user asks to create or edit a .docx Word document" will. Be concrete about the triggers, and keep the instructions focused on one kind of task.

Installing skills from the catalog

You do not have to build every skill by hand. The ToolZip skills catalog curates ready-to-use skills, each installable with a single command. From your project root:

npx claude-code-templates@latest --skill="documents/pdf-report" --yes

The installer writes the skill folder into your .claude/skills/ directory, and it is available on the next session. The value after --skill is the category/name path that matches the component's page URL on ToolZip. The same installer handles every other component type by swapping the flag — --agent, --command, --mcp, --hook, and --setting — so you can assemble a full setup from one tool. Browse the whole Claude Code catalog to see how the pieces fit together.

Best practices for skills

• One skill, one job. A focused skill activates predictably. A catch-all skill fires at the wrong times and muddies its own instructions.
• Invest in the description. It is the only thing Claude sees before deciding to load the skill, so state the triggers explicitly.
• Lean on progressive disclosure. Keep SKILL.md itself lean and push long references into separate files the skill loads only when needed.
• Make instructions imperative and ordered. Numbered steps and concrete output requirements beat loose prose.
• Commit project skills. Checking .claude/skills/ into git gives your whole team the same capabilities.

Where to go next

• Skills vs Agents vs Commands
• Claude Code Agents: Install and Use Subagents
• Claude Code Best Practices: 12 Tips
• Browse the skills catalog

Skills are how you turn a one-time explanation into a permanent capability. Package a workflow you repeat, give it a sharp description, and Claude Code will reach for it exactly when it fits — no re-briefing required.