What are Skills (reusable instructions for Claude): expertise you can reuse

Module: Skills, reusable expertise | Time: about 25 min reading + 30 min practice

The gist

If a workflow is a recipe for one specific dish, a skill is a recipe with a passport that you can hand to any cook in any restaurant in the world. A skill knows who it is and what it can do, and it can introduce itself to an agent (an AI that carries out tasks on its own) that has never seen it before.

Key concepts

• Skill = workflow + a YAML passport (YAML is a format for configuration files; the passport is called frontmatter, the metadata at the top of the file)
• Progressive loading: L1 frontmatter → L2 the full workflow → L3 files
• Install ready-made skills with /plugin from a marketplace; your own skills live in a folder: .claude/skills/<name>/SKILL.md
• A 6-step framework for creating a skill
• Skills get better through iteration and feedback

Theory

Workflow vs. skill: what's the difference

🎨 Picture this: a skill is a recipe in a cookbook. A workflow is the dish you cooked today from memory. The dish will be gone. The recipe stays, and any cook in any restaurant can make it again tomorrow.

A workflow is a sequence of steps for a specific task. It lives in the memory of the current session. It disappears when you close the tab.

A skill is the same workflow, but packaged into a file with metadata. The file is called SKILL.md and sits in the skill's folder (.claude/skills/<name>/SKILL.md):

---
name: weekly-youtube-roundup
description: Analyzes a YouTube channel over the last 7 days and generates a report. Use when someone asks for a weekly channel summary.
---

# YouTube Weekly Roundup

## Step 1: Collect the data...

Frontmatter has other optional fields too (for example allowed-tools, model, disable-model-invocation), but the one that matters is description: that's what Claude uses to decide when to bring in the skill.

The difference is crucial:

• A workflow is known only to the agent in the current session
• A skill is known to any agent: it can read the frontmatter and figure out "oh, this is for YouTube analytics"

How the agent picks the right skill: progressive loading

Imagine you have 50 skills. Loading all 50 into the context (the text the AI can see) on every request would waste thousands of tokens (a token is a unit of text for AI). That's why skills use progressive loading, with three levels:

🎨 Picture this: progressive loading works like a library. First you scan the spines (L1, the frontmatter, takes seconds). Found the right book? You take it off the shelf and read it (L2, the full workflow). Only if you need the atlas tucked in the back do you open it separately (L3, reference files). You don't haul the whole bookcase home.

L1: Frontmatter (roughly a hundred tokens per skill)

The agent reads only the header of every skill: the name and the description. It's like reading the spines on a shelf: you see the title and a short description. From these, it decides "this skill fits the task." The description in the list has a length limit (around 1,500 characters in the documentation as of October 2026), so put the most important part first.

name: weekly-youtube-roundup
description: Analyzes a YouTube channel over the last 7 days and generates a report

L2: The full markdown workflow (1,000–2,000 tokens)

Only once a skill is chosen does the agent read the full text with step-by-step instructions. Now it knows what to do.

L3: Supporting files (as needed)

If the skill refers to files (brand guidelines, a report template, a list of competitors), they're loaded only when the task needs them. If the task doesn't involve branding, the branding file doesn't get loaded. You can keep files and scripts like these in the skill's folder next to SKILL.md.

Bottom line: instead of loading 50 × 2,000 tokens = 100,000 tokens on every request, you load only the skills' frontmatter (50 × 100 = 5,000) plus the full text of the one you picked (2,000). The numbers are an illustration, but that's the scale of the savings: many times over.

How to install a skill from a marketplace

Step 1: In Claude Code, type:

/plugin

This opens the plugin menu with catalogs (marketplaces). Skills are distributed as part of plugins. To see which skills you already have, use the /skills command.

Step 2: Find the skill you need. Examples of plugin names in the catalogs:

• engineering:*: development, review, deployment
• marketing:*: content, email, SEO
• superpowers:*: productivity, parallel work
• anthropic-skills:*: official skills from Anthropic

Step 3: Install it (the /plugin menu shows the exact plugin and catalog names):

/plugin install <plugin>@<catalog>

The plugin's skills become available to the agent right away or after /reload-plugins. You can call them by hand as /plugin:skill, but more often the agent picks the right one on its own based on the description.

Step 4: Use it:

Do a code review of this file

The agent recognizes from the description that it needs the code review skill and applies it.

Skills get better over time

A skill isn't a static document. It evolves:

1. First version: you created it, ran it, got a result
2. You notice a problem: "the report is too long, there's no executive summary"
3. Iteration: you add an executive summary step to the frontmatter and the workflow
4. You run it again: better
5. The next problem: "the competitor benchmarking doesn't account for my region"
6. Iteration 2: you add a region parameter

By iteration 10 to 30, the skill becomes a finely tuned tool for your tasks. That's what "encoded expertise" means: expertise captured in a file.

🎨 Picture this: iterating on a skill is like sharpening a knife. After the first use, it already cuts. After the tenth, it shaves. After the thirtieth, it's a surgical instrument. Each edit removes a burr that was getting in the way.

A 6-step framework for creating a skill

Step 1: Name and trigger

How will the agent know to use this skill? There's no separate triggers field: trigger phrases go right into description (or into the optional when_to_use field).

name: competitor-price-monitor
description: >
  Monitors competitor prices and generates a comparison report.
  Use when someone asks to "check competitor prices",
  "competitor pricing" or "price monitoring".

Step 2: The goal, in one clear sentence

"Collect prices from 10 competitor websites, compare them with our prices, and highlight differences over 15%."

Not "does everything about competitors." One focus.

Step 3: The step-by-step process

Detailed instructions for each step. Not "collect the data," but "open the URL, find the .price-tag element, extract the text, convert it to a number."

Step 4: Reference files

What does the skill need besides instructions? Files like these go in the skill's folder next to SKILL.md, and the skill's text links to them:

competitor-price-monitor/
  SKILL.md
  competitors.json       # list of competitor URLs
  price-template.md      # report template
  brand-guidelines.md    # for formatting

In SKILL.md you write: "The list of competitors is in competitors.json in this same folder." Claude will open the file when it needs it.

Step 5: Rules and limits

What the skill must NOT do:

- Don't change the source data in the database
- Don't send the report without a review
- If parsing fails, skip the site and mark it as unavailable

🎨 Picture this: the 6-step framework is like a job brief for a new hire. Name (who you are), goal (why you were hired), process (how you work), tools (what you take from the supply room), limits (what's off-limits), feedback (how you report back). Skip one step and the new hire either does nothing or does the wrong thing.

Step 6: A self-improvement loop

At the end of the skill, an instruction to the agent:

After you finish, rate the quality of the result from 1 to 10.
If it's under 7, describe what went wrong in skill-feedback.md.

This creates a feedback system for future improvements.

Common mistakes when creating skills

1. The skill is too broad. "A marketing skill" is bad. "A skill for creating an email campaign with A/B testing of subject lines" is good. One skill = one focus.

2. Forgetting the YAML frontmatter. Without frontmatter that has a description, the agent has no way to tell when to bring in the skill. Always start with a --- block and a good description.

3. Stuffing all the data into the skill's body. A list of 200 competitors in the skill's body = 200 lines loaded every time. Move large data into separate files next to SKILL.md. The Claude Code documentation recommends keeping SKILL.md under 500 lines.

4. Not describing the triggers. If the description doesn't say when to use the skill, it may not activate on the right request.

5. Not iterating. The first version of a skill is almost never perfect. The plan: create → run → spot a weakness → fix it → repeat.

Skills vs. Hooks (scripts that react to an event) vs. Agents (independent workers): what's the difference

A real skill's YAML frontmatter

---
name: weekly-competitor-report
description: >
  Weekly competitor report: prices, new products,
  website changes. Format: executive summary + table.
  Use when someone asks for a "competitor report",
  "what's new with competitors", "competitor analysis"
  or "competitor monitoring".
argument-hint: "[pricing|features|content]"
---

# Competitor report

The list of sites is in competitors.json in this folder,
and the report template is in report-template.md.
What to focus on: $ARGUMENTS (pricing by default).

In this example, a parameter is passed when you call the skill (/weekly-competitor-report features) and gets substituted into the text as $ARGUMENTS. The fields tags, triggers, references, parameters and model_invocation, which showed up in older descriptions of skills, aren't used in Claude Code: triggers live in description, and reference files sit next to it in the skill's folder.

Claude Code skills documentation: https://code.claude.com/docs/en/skills

Where to keep skills

🎨 Picture this: global skills are like your personal toolkit that you carry everywhere. Project skills are like specialty tools that stay at one job site. Your power drill always comes with you; the concrete forms stay at this particular site.

Globally (~/.claude/skills/<name>/SKILL.md): The skill is available in every project. Good for general-purpose skills: code review, email writing, price monitoring.

At the project level (.claude/skills/<name>/SKILL.md): The skill is available only in this project. Good for specific skills: "our report format," "a particular client's brand voice." You can commit the project folder, and the skill will show up for the whole team.

Also good to know (as of October 2026):

• Older custom commands in .claude/commands/ still work and have been merged with skills: the file .claude/commands/deploy.md and the skill .claude/skills/deploy/SKILL.md both create a /deploy command. For anything new, it's better to choose skills
• Skills are also available in claude.ai, including on the free plan. For uploading there, the frontmatter may contain only the common fields (name, description, license, compatibility, metadata, allowed-tools); fields specific to Claude Code will cause an error on upload

Practice

Task: find and install 2-3 skills from a marketplace

1. Open Claude Code and type /plugin
2. Browse the catalog and find at least 3 skills that could be useful for your tasks
3. Install 2 skills: one for work tasks (development or marketing) and one for productivity
4. Run /skills and look at the list: find the skills you installed, open the SKILL.md file and read the frontmatter
5. Try using one skill on a real task
6. Bonus: create a simple skill by hand, a "daily report template," using the 6-step framework

Tools and resources

• /plugin: the command that opens the plugin menu and catalogs (marketplaces) in Claude Code
• /skills: the list of available skills
• Claude Code Skills documentation: the official skills documentation
• Claude Code Sub-agents: documentation on subagents (related)
• .claude/skills/<name>/SKILL.md: a project-level skill
• ~/.claude/skills/<name>/SKILL.md: a global skill

Key takeaways

A skill = a workflow with a passport. The passport lets any agent find and use the skill without you explaining it by hand.

Progressive loading saves the lion's share of tokens: first you read the book spines (frontmatter), then you open the one you need (the full markdown).

Skills get better through iteration. Version 1 is a draft. Version 15 is a precise tool built for your tasks.

Related lessons

• → Building a skill from scratch, LIVE: hands-on skill creation with Skill Creator and an eval framework
• → Skill architecture: two archetypes: Capability Uplift vs. Encoded Preference
• → Evals: self-improving skills: a testing system that lets skills improve themselves

Next lesson

→ Building a skill from scratch, LIVE: Skill Creator + Eval Framework