What is a Skill?

A Skill is a folder of instructions, scripts, and resources that Claude loads dynamically to get better at a specific, repeatable task — brand guidelines, a data workflow, a formatting convention, anything you'd otherwise have to re-explain every conversation.

The folder

Only SKILL.md is required. Everything else is added only if the skill actually needs it — a simple skill can be nothing but a Markdown file with two lines of frontmatter.

Progressive disclosure

This is Anthropic's own term for how Skills work, not a metaphor we invented. Claude doesn't load every Skill's full content into every conversation — it scans lightweight metadata (name + description) first, and only loads the full SKILL.md body when a task actually matches. This is what keeps Skills cheap to have many of, without bloating the context window.

Skills vs. everything else Claude has

The four official types

1. Anthropic skills — built-in, e.g. the document skills behind Word/Excel/PowerPoint/PDF creation. Available to everyone, Claude invokes them automatically.
2. Custom skills — the ones you or your org write for your own workflows.
3. Organization-provisioned — an admin pushes a skill to every member of a Team/Enterprise plan, optionally on by default.
4. Partner skills — professionally built by companies like Notion, Figma, and Atlassian, usually paired with that company's MCP connector.

Sourced directly from Anthropic's official "What are skills?" doc, not secondhand.

Using an existing Skill

Skills are available on Free, Pro, Max, Team, and Enterprise plans, and in beta for Claude Code and API users. The one requirement: code execution must be enabled on your account.

On claude.ai

1. Go to Customize → Skills (claude.ai/customize/skills)
2. Click "+", then "Browse skills" to open the directory
3. Enable the one you want, or upload your own ZIP

In Claude Code

Register Anthropic's example-skills repo as a plugin marketplace, then install from it:

/plugin marketplace add anthropics/skills

Then either use the interactive menu (Browse and install plugins → anthropic-agent-skills → document-skills or example-skills → Install now), or install directly:

/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

Verified directly against the anthropics/skills GitHub repo — this is real, current syntax, not a paraphrase.

Before you install someone else's Skill

Troubleshooting

"Installed successfully" but Claude won't use it: this is a known issue — restart your session. If it still doesn't trigger, your description field may be too vague; see Chapter 04 for how Claude decides when to invoke a skill.

Making your own Skill

There are two ways to create one — and most guides only tell you about the harder one.

Path A — Record it (the easy one)

In Cowork on Claude for Mac, you can record yourself doing the task on screen — clicks, typing, and optional narration — for up to ~10 minutes. Claude watches the recording and proposes a Skill for you to review and save. No SKILL.md writing required to get started.

1. Update Claude for Mac to the latest version
2. Grant Accessibility and Screen Recording permissions when asked
3. Open Cowork → click "+" → "Record a skill" (or Customize → Skills → Add → "Record your screen")
4. Do the task normally — narrate why you're doing each step, not just what
5. Click "Done." Claude proposes a new skill, or an update if it overlaps one you already have

Path B — Write it by hand

Every Skill needs a SKILL.md starting with YAML frontmatter:

• name — up to 64 characters
• description — up to 200 characters. This is the only thing Claude reads before deciding whether to load the rest — vague descriptions are the #1 reason a skill never gets used.

A real example

## Metadata
name: Brand Guidelines
description: Apply Acme Corp brand guidelines to all
  presentations and documents

## Overview
Apply these standards whenever creating presentations,
documents, or marketing materials so outputs match
Acme's visual identity.

## Brand Colors
- Primary: #FF6B35 (Coral)
- Secondary: #004E89 (Navy Blue)

## Typography
Headers: Montserrat Bold
Body text: Open Sans Regular

## When to Apply
- PowerPoint presentations
- Client-facing Word documents
- Marketing materials

This example is Anthropic's own, from the official "How to create custom skills" doc.

Best practices, straight from Anthropic

• Keep it focused — several small skills compose better than one that tries to do everything
• Write clear descriptions — be specific about when it applies
• Start simple — plain Markdown before you add scripts
• Use examples — show what success looks like
• Test incrementally — after each real change, not all at once

Optional pieces once you outgrow a single file: a dependencies frontmatter field for required packages, a references/ folder for overflow content, and executable scripts (Python, JS/Node — the same stack Anthropic's own document skills use).

Test before you trust it

Sharing a Skill

Distribution follows the same four official types from Chapter 02 — how you share depends on who needs it.

Packaging, one more time

The folder name must match the skill's name, and the folder itself — not its contents — must be the ZIP's root.

The GitHub path

1. Create the skill folder, write and test SKILL.md
2. Add a README.md and a license
3. Commit, push to a public or private repo
4. Anyone with access clones or downloads it, follows Chapter 03 to install

This is exactly how Anthropic distributes its own example skills — the anthropics/skills repo is nothing more exotic than a folder of Skills under version control.

Maintaining Skills as a team

Once more than one person depends on a Skill, it stops being a clever personal trick and starts being software your team relies on. Treat it that way.

Repo structure for a multi-skill team repo

Git workflow

• One branch per skill change, not one giant branch for everything
• PR checklist: description still accurate? Tested against the 5-case matrix from Chapter 04? Any scripts reviewed line by line?
• CODEOWNERS on skills/**/SKILL.md so changes to a skill always get eyes from someone who understands it
• Regression check after every change: does the skill still trigger on the prompts it used to?

Ownership and lifecycle

Someone should own each skill by name — not "the team." When a skill is superseded, deprecate it explicitly (a note at the top of SKILL.md, then remove it) rather than letting it quietly rot and confuse people. Version bumps matter for the same reason they matter in any shared codebase: so people know when behavior changed underneath them.