From “what is a Skill?” to a shelf your team trusts.

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.

Finding a Skill on GitHub — every click, step by step

Everything above assumes you already have a Skill's ZIP file in hand. If you've never used GitHub before, this is the missing piece — exactly how to go from "someone told me about a Skill" to a ZIP file ready to upload.

Step 1 — Open the repository

Go to the repo's page in your browser — for example github.com/anthropics/skills, Anthropic's own official collection. You'll land on the main page. The big block of formatted text below the file list is the README — think of it as the repo's cover page, explaining what's inside in plain language.

Step 2 — Find the actual Skill you want

Big repos like this one hold many Skills, each in its own folder. Click into the skills/ folder, then click a folder name (e.g. document-skills) to open it. You know you've found a real Skill — not just a folder of folders — when you see a file called SKILL.md sitting right there.

Step 3 — Download it

Navigate back to the top of the repo. Click the green "Code" button near the top right, then "Download ZIP" from the dropdown.

Step 4 — Get just the one Skill folder out

1. Find the ZIP in your Downloads folder and unzip it (double-click on Mac; right-click → "Extract All" on Windows)
2. Open the unzipped folder, then navigate the same path you clicked through on the website — e.g. into skills/, then into document-skills/
3. The folder that directly contains SKILL.md is the one you actually need. Drag just that folder out somewhere easy to find, like your Desktop

Step 5 — Re-zip just that folder

Claude needs a ZIP containing only that one Skill folder, not the whole repository.

• Mac: right-click the folder → "Compress [folder name]"
• Windows: right-click the folder → Send to → "Compressed (zipped) folder"

Quick check before you upload: the ZIP's name should match the folder name, and if you peek inside it, the folder itself should be the first thing you see — not SKILL.md sitting loose at the top level. That's the same packaging rule covered in Chapter 05.

Step 6 — Upload it

Now follow the "On claude.ai" steps further up this page: Customize → Skills → "+" → upload this ZIP.

A few GitHub words you'll run into

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.

See it in action

This is the part most examples skip: what do you actually type to trigger this Skill? You never call it by name — you just ask for the task, and Claude matches your request against the description field automatically.

Create a PowerPoint deck for our Q3 sales
pitch to Northwind Traders — 8 slides,
covering results, roadmap, and pricing.

Nothing in that prompt mentions "Brand Guidelines" or "Skill." Claude reads "Apply Acme Corp brand guidelines to all presentations and documents" in the Skill's description, recognizes this request matches, and quietly applies the coral/navy color palette and Montserrat/Open Sans typography from the example on the left — without being told to.

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.

A Skill has more than instructions. Once a team depends on it, it also has:

• an owner
• users
• versions
• tests
• reviewers
• change history
• dependencies
• release decisions
• a lifecycle

That is why a team Skill needs a development process.

Why GitHub?

The problem isn't writing a Skill. The problem starts when several people are changing the same one. Without version control, you end up with:

You quickly lose track of which version is current, who changed it, why, whether it was tested, who approved it, and how to undo it. With Git, that becomes a line you can actually follow:

A repository that scales

A Skill vs. the team scaffolding around it

These are two different things living in the same repository. Keeping them mentally separate stops a lot of confusion — especially about where documentation belongs.

Only the inner box ever gets zipped up and used by Claude, exactly as in Chapters 04 and 05. Everything in the outer box is for the humans running the repository — it never ships inside the Skill.

The team workflow, start to finish

Every change to an official Skill goes through the same sequence — no exceptions, no "just this once" direct edit to main.

Branch naming — keep it descriptive

Name the branch after what it does, not who's doing it: add-customer-email-skill, update-brand-colours, fix-invoice-skill-typo. Anyone glancing at the branch list should understand what's in flight without opening a single file.

Pull Requests — the formal proposal

A Pull Request (PR) is a structured way of saying "please look at my change and approve it," with a place for reviewers to comment on specific lines, request changes, or approve. Nothing merges into main without one — that's what branch protection enforces (see "Ownership & CODEOWNERS" below).

PR checklist — copy this into every proposal

Testing a Skill before it's reviewed

"Testing" here means three different questions, not one:

The 5-case matrix (same one from Chapter 04, worth repeating for a team)

A team-sized way to say the same thing: write a few prompts that should trigger the Skill and a few that should not, and run all of them in fresh chats. The "should not" half is the one people skip — and a Skill that fires on the wrong requests is just as broken as one that never fires.

The clean-copy test — the one teams skip

Here's the trap that catches almost everyone the first time. You test a Skill in your own folder, it works, you share it — and it breaks for everyone else, because a file it needs (a reference doc, a template, a script) was never actually committed. It worked for you only because that file was still sitting on your computer.

So the real test is: get a clean copy — a fresh download of the branch, or the packaged ZIP itself — somewhere you've never worked, and run the matrix above there. If it still works from a folder that only contains what was actually committed, it'll work for your teammates.

The collision test — for a team with several Skills

A Skill tested alone almost always passes. The real question on a team is what happens when all your Skills are active at once: two with overlapping descriptions can fight, and the wrong one answers. Before shipping, run a normal request with your other everyday Skills switched on too, and confirm the right one — and only the right one — responds.

Real tooling, if your team wants to automate this

Anthropic's own anthropics/skills repository ships real scripts for exactly this, worth knowing exist even if your team starts out testing by hand:

python skills/skill-creator/scripts/quick_validate.py skills/skill-creator
python skills/skill-creator/scripts/init_skill.py my-skill --path skills --resources scripts,references,assets
python skills/skill-creator/scripts/package_skill.py skills/skill-creator

There's also a structured format for recorded test cases, evals/evals.json, with a skill_name field and an evals list of id / prompt / expected_output / files / expectations per case — a machine-checkable version of the 5-case matrix above.

Commands and format verified directly against anthropics/skills. A further script, run_eval.py, also exists in that repo for running these cases — its exact invocation wasn't independently confirmed at time of writing, so it's mentioned here by purpose, not with invented syntax.

Reviewing a Skill — not just reading the file

Reviewing a Skill is different from reviewing ordinary text, because the real test is behavior, not prose. A good review actually runs it.

Ownership & CODEOWNERS

Someone should own each Skill by name, not "the team." A CODEOWNERS file makes this automatic instead of relying on memory: it maps a folder to specific people, and GitHub then requests their review automatically whenever a Pull Request touches that folder — the HR team gets pulled in on HR Skills, Finance on Finance Skills, without anyone having to remember to tag them.

# .github/CODEOWNERS
# These people must review changes to any skill
/skills/    @anna @ben @carla

# Different owners for specific skills
/skills/brand-guidelines/    @design-team
/skills/compliance/          @legal-team @security-team

Branch protection — the control switch

In the repository's Settings → Branches, a protection rule on main turns the whole process from "a suggestion" into "the only way in":

• Require a Pull Request before merging
• Require at least 1 approving review
• Require review from Code Owners
• Do not allow force pushes

With this on, there is no back door — not even for an admin in a hurry.

Owning the behavior, not just the file

"Owner" means more than "whose name is on the folder." The named owner of a Skill is the person responsible for:

• what it does and doesn't trigger on
• whether its output is still correct
• the files and scripts it depends on
• its security review
• and deciding when to retire it

When something about the Skill changes in the real world — a supplier, a policy, a price list — the owner is who makes sure the Skill keeps up.

Lifecycle & versioning

Give every Skill a version in its frontmatter, and bump it with a meaning a non-technical reader can follow — thinking in terms of what actually changed, not abstract numbers:

Two rules that save real headaches

• Pin the version in production; use "latest" only while experimenting. If your live setup always grabs the newest version, then anyone's merge can instantly change how the whole team's Claude behaves — with no warning. Point production at a specific, known-good version and move it up deliberately.
• Every version stands alone. As covered in the clean-copy test above, publishing a version uploads the whole Skill — files left out are gone from that version. Re-check the file list every time you bump the version, not just the wording.

Merging isn't the same as everyone having it

Merging to main makes a change official in the repository — it does not, by itself, put the new version in front of every teammate. That last step depends on which of the three distribution methods from Chapter 05 your team uses: org-provisioned updates automatically, a shared ZIP needs re-uploading, a plugin marketplace needs /plugin update or a fresh install.

Deprecating and rolling back

Made a mistake after merging? A new Pull Request that reverts the change is the normal fix; a maintainer can also roll back further using GitHub's own history. This is exactly why nothing skips the Pull Request step, even for "quick" changes — the undo mechanism only exists because the history does.

Scaling to a global, asynchronous team

None of this requires everyone online at once. A simple weekly rhythm keeps it moving across time zones without a single meeting:

Keep the shelf clean — a retirement rhythm

Skills pile up. Old ones that nobody uses don't just sit there harmlessly — they clutter Claude's decision about which Skill to load, and they confuse new team members. Add one recurring ritual: every few months, each owner re-checks their Skills. Anything that no longer works, or hasn't been used in roughly six months, gets deprecated (see the lifecycle card) rather than left to quietly rot. A ten-minute quarterly sweep saves a lot of "why did Claude do that?" later.

Who does what

Most people on the team only ever need to know two things: how to open a Pull Request, and how to review one.

Security, automation & no fake scores

A Skill isn't just a note to Claude — it's instructions, and sometimes scripts, that shape what Claude actually does. Anyone who can change a Skill can change how your team's Claude behaves. That's exactly why the review process above isn't red tape: a Skill is a trust boundary, so treat changes to one the way you'd treat changes to anything with real reach into your work.

After launch: read what your agents actually did

The checks above happen before a Skill ships. Once Skills run inside agents that work on their own, there is a second job: reading what the agents did afterwards. Network limits and permission rules block actions; reading the finished sessions shows what slipped through, and where your limits are looser than you meant.

Anthropic's cookbook has a worked recipe for this, Review your agents' sessions for security issues with Claude. It looks for five things:

The result is a ranked list of the sessions a person should read, with quoted evidence for each. It can read Managed Agents sessions, Messages API logs or Claude Agent SDK logs, and its first two parts run offline without an API key.

Both recipes were read directly at anthropics/anthropic-cookbook on 22 October 2026 and described by what they say, not run by us. They are about agents and the API, not about writing a SKILL.md, so use them as a next step, not as part of the Skills review process above.

The mistakes teams actually make

None of these are about Git. They're the traps where a Skill looks fine in the repo but misbehaves for real — the gap between "the file is correct" and "Claude does the right thing." Warn your team about these up front:

• A vague description. The single most common failure. Claude decides whether to use a Skill almost entirely from its description — too vague and it fires on the wrong things or never fires at all. Say plainly what it does and when to use it.
• Stuffing everything into SKILL.md. A giant instructions file gets loaded every single time, wasting Claude's attention. Keep SKILL.md lean (a good rule of thumb is under ~500 lines) and push detail into references/, which Claude opens only when it's needed.
• A README.md inside a skill folder. Claude reads it as part of the Skill and it clutters things. Human docs go in the repo's root README, never inside an individual skill folder.
• A forgotten-to-commit file. Works for the author, breaks for everyone else — the clean-copy test above catches it.
• Promoting a personal experiment straight to the team. Skipping the Pull Request "just this once" is how an untested Skill lands on everyone. Sandbox Skills still go through review before they're shared.
• Never retiring dead Skills. They pile up, confuse Claude's choices, and mislead new hires. Use the retirement rhythm.
• Reporting scores that weren't really run. The whole review system depends on honest reporting — a "passed" with nothing behind it is worse than an honest "not tested yet."

The complete picture, and what to do tomorrow

Starter checklist

Quick answers

Do I have to use the command line for any of this? No. Everything in this chapter — creating a branch, editing a SKILL.md, opening a Pull Request, reviewing and merging — can be done entirely through GitHub's website in your browser, or the free GitHub Desktop app. The git terms here (branch, commit, merge) are just names for buttons you click. If a teammate is comfortable at the command line that's fine too, but nobody has to be.

Do we need a developer to run this? Not day to day — a technical person is genuinely only needed for the first setup and occasional help. Proposing and reviewing Skills doesn't require it.

How many approvals should we require? Start with 1. For anything brand-, legal-, or compliance-sensitive, require 2.

Two people want to change the same Skill at once — what happens? GitHub flags the conflict. The second person waits for the first PR to finish, or the two of you combine the changes into one.