Skills

You are here · Paths A, B, C · Requires Pro or above in practice · 60–75 min · Assumes Projects.

Skills are listed as available on Free, but they only run with code execution enabled, which is paid-only. Free users can read this module but can’t do the exercises.

What you’ll learn: what a Skill is, how progressive disclosure makes them nearly free, and how to write one that actually triggers.

If you only read one thing

A Project holds what you know. A Skill holds how you do something.

A Skill is a set of instructions for one repeatable task — how your team writes release notes, how you want expense reports formatted, how to clean a particular export — that Claude loads only when it’s relevant. The trigger for making one is simple: you’ve pasted the same multi-step instructions into chat three times.

The clever part is that Skills are nearly free. Claude only reads a one-line description of each installed Skill until one actually applies, so you can install dozens without slowing anything down or crowding out your conversation.

Two things determine whether a Skill works. The description decides whether it ever fires — it must say both what the Skill does and when to use it, in the words you’d actually say. The body decides whether the result is good — write it like a runbook for a new hire, with numbered steps and what to do when information is missing.

And treat installing someone else’s Skill like installing software: it can tell Claude to do things. Read it first.

What a Skill is

A Skill is a folder containing a SKILL.md file — instructions Claude loads on demand when they’re relevant — plus optional bundled files and scripts.

The core insight: a Skill is what you’d write to onboard a new team member to one specific task. Not facts about your company (that’s a Project), but how we do this thing here.

release-notes/
├── SKILL.md          # main instructions
├── TEMPLATE.md       # the format we use
├── examples/
│   └── v2.4.0.md     # a good past example
└── scripts/
    └── fetch_prs.py  # utility Claude can run

Progressive disclosure — why Skills are nearly free

This is the mechanism that makes Skills work at scale.

The consequence: you can install dozens of Skills without a context penalty. Until one triggers, it costs about a hundred tokens.

And bundled content is effectively unlimited. A Skill can ship a 500-page API reference, and if the task doesn’t need it, it costs nothing.

Scripts are especially efficient: when Claude runs validate.py, the script’s code never enters context — only its output. That makes scripts far cheaper and more deterministic than asking Claude to generate equivalent code on the fly.

Anatomy of a SKILL.md

---
name: release-notes
description: Write release notes for the Ledger service in our house format. Use when the user asks for release notes, a changelog, or a version announcement.
---

# Release notes

## Process

1. Ask which version and which date range of merged PRs to cover.
2. Group changes into: Breaking, Added, Fixed, Internal. Omit empty groups.
3. Each entry is one sentence in past tense, starting with a verb.
4. Breaking changes always come first and always include a migration note.
5. Link every entry to its PR.

## Format

Follow TEMPLATE.md exactly. See examples/v2.4.0.md for a good result.

## Rules

- Never invent a PR number. If you don't have it, write `(PR: TBC)`.
- Internal-only changes get one line, not a paragraph.
- No marketing language. Engineers read these.

Field requirements

name

• Max 64 characters
• Lowercase letters, numbers, and hyphens only
• No XML tags
• Cannot contain the reserved words “anthropic” or “claude”

description

• Required, non-empty, max 1024 characters
• No XML tags

Writing a description that triggers

This is the single most important part of the whole skill, because it’s the only thing Claude sees until the skill fires. Claude matches your request against descriptions to decide what’s relevant.

A good description says both what the skill does and when to use it.

Include the words users actually say. If your team says “changelog”, “release notes”, and “what shipped”, put all three in the description.

Be specific enough not to over-trigger. A description like “handles documents” will fire on everything and crowd out better matches.

The body: write it like a runbook

The description gets it loaded. The body determines whether the result is good.

Do:

• Number the steps
• Say what to do when information is missing (ask vs write TBC vs infer)
• State the format precisely, or point at a template file
• Include a good example
• List the specific mistakes you keep having to correct

Don’t:

• Explain what the concept is (Claude knows what a changelog is)
• Write vague principles (“be thorough”)
• Exceed ~5k tokens — push detail into bundled files and reference them

Where Skills live, per surface

Skills do not sync across surfaces. Upload separately to each.

The four kinds of skill

Browse everything via Customize → Skills → + → Browse skills.

Skills follow the Agent Skills open standard, so the same format works across platforms that adopt it — you’re not locked to Claude. A reference Python SDK exists for implementers.

Runtime differences worth knowing

If you write a Skill that fetches from a URL, it will work in Claude Code and fail on the API. Plan for the surface you’re targeting.

Security

Treat installing a Skill like installing software.

A Skill gives Claude new instructions and executable code. A malicious one can direct Claude to invoke tools in ways that don’t match its stated purpose — data exfiltration, unauthorised access, destructive operations.

Rules:

• Use Skills you wrote, or that come from Anthropic
• If you must use a third-party Skill, audit every file: SKILL.md, scripts, images, resources. Look for network calls, unusual file access, anything that doesn’t match the stated purpose.
• Skills that fetch from external URLs are the highest risk — fetched content can carry instructions, and even a trustworthy skill can be compromised if its dependency changes
• Be especially careful in production systems with access to sensitive data

Skill vs. Project vs. instruction

The trigger for creating a Skill: you’ve pasted the same multi-step instructions into chat three times.

Try it

Exercise 1 — Convert a prompt into a Skill. Take the best template from your prompt library (Structured prompting with XML). Write it as a SKILL.md with proper frontmatter. Zip the folder. Upload it. Use it.

Exercise 2 — Description A/B. Write two descriptions for the same skill: one vague, one specific with trigger words. Install each in turn and try five naturally-phrased requests. Count how often it fired.

Exercise 3 — Progressive disclosure. Build a skill with a bundled reference file. Ask a question that needs the file and one that doesn’t. Confirm Claude only reads it when relevant.

Exercise 4 — Script over prose. Write a skill that includes a small Python script (e.g. validating a CSV). Compare against a version where the skill describes the validation in prose. The script version is more reliable and cheaper.

Exercise 5 — Audit. Find a third-party skill in the skills directory. Read every file before installing. Practise the habit now, while nothing is at stake.

Checkpoint

• You can state the three levels of progressive disclosure and roughly what each costs
• You can write a description that says both what and when
• You know why a skill that works in Claude Code might fail on the API

Going deeper

• Agent Skills overview
• Skill authoring best practices
• What are skills?
• How to create custom skills
• Teach Claude your way of working using Skills
• Provision and manage skills for your organization
• Skills for enterprise
• Agent Skills open standard