What are Claude Skills? How they work, how to install one, and when to use a Skill instead of MCP or a Project

How a Skill works

Anthropic describes Skills as "folders containing instructions, scripts, and resources that Claude discovers and loads dynamically when relevant to a task" (Anthropic, Skills explained). The key idea is progressive disclosure. Claude loads a Skill in three stages (Agent Skills overview):

1. Metadata, always loaded. The name and description from the top of SKILL.md, roughly 100 tokens per skill. That's how you can install many skills without filling up the context window.
2. Instructions, loaded when triggered. The body of SKILL.md. Anthropic recommends keeping it under 5,000 tokens and under 500 lines.
3. Resources, loaded as needed. Reference files are read only when a step needs them. Scripts are run, and only their output enters the context.

That third point is the one people underrate. A skill can carry a Python script that does the maths properly, so the model isn't eyeballing a spreadsheet and guessing a total.

What a Skill looks like inside

Here's the top of a real one, the free csv-quick-clean skill from our Oarsman Skills Sampler:

---
name: csv-quick-clean
description: Quickly cleans a messy CSV export from a bank, accounting tool,
  CRM or store - skips title lines above the real header, detects the
  delimiter, removes blank and duplicate rows, converts amount text like
  "(1,234.50)", "Rs. 500", "$1,200" or "250 Dr" into numbers and rewrites
  dates as YYYY-MM-DD. Use when the user uploads a CSV that won't sort or
  sum properly, asks to tidy or clean an export, or needs a clean CSV
  before analysis.
license: MIT
compatibility: Python 3.8+ standard library only. No network needed.
---

# CSV Quick Clean
## Workflow
1. Save the user's file and run:
   python3 ${CLAUDE_SKILL_DIR}/scripts/quick_clean.py "input.csv"
2. Read the JSON summary and tell the user what changed...
## Rules
- Never edit values by hand to "fix" them...

The folder looks like this:

csv-quick-clean/
├── SKILL.md
└── scripts/
    └── quick_clean.py

Three things make it work:

• The description says what and when. Claude matches your request against the description, so "Use when the user uploads a CSV that won't sort or sum properly" matters as much as the feature list. Anthropic's docs make the same point: the description "must say both what the Skill does and when to use it."
• The script does the deterministic part. Parsing (1,200.00) as −1200 is a job for code, not for a language model's judgement.
• The rules stop bad habits. "Never edit values by hand" prevents the most common failure: the model quietly "fixing" a number.

The format rules come from the open Agent Skills specification: name is required, lowercase letters, numbers and hyphens, up to 64 characters, and must match the folder name; description is required, up to 1,024 characters. license, compatibility, metadata and allowed-tools are optional.

How to install a Skill (three places)

Claude Code. Personal skills live in ~/.claude/skills/<skill-name>/SKILL.md and load in all your projects; project skills live in .claude/skills/ inside a repository, so everyone who clones it gets them (Claude Code docs). You can also install skills bundled as a plugin. For our sampler, either:

# as a plugin
claude plugin marketplace add vishalrwt1995/oarsman-skills-sampler
claude plugin install oarsman-skills-sampler@oarsman-skills-sampler

# or by copying the folders
git clone https://github.com/vishalrwt1995/oarsman-skills-sampler.git
cp -r oarsman-skills-sampler/skills/* ~/.claude/skills/

Claude Code picks up changes to skill folders during a session. You can trigger a skill by asking for the task in plain words, or directly with /skill-name.

Claude.ai. Zip the skill folder (not just its contents) and upload it in your Skills settings. Anthropic's guide to creating skills is specific about this: the ZIP must contain my-skill/SKILL.md, and a SKILL.md at the root of the ZIP isn't recognised. Custom skills need code execution turned on and, per the overview, a Pro, Max, Ultra, Team or Enterprise plan. Custom skills are per user, not shared across an organisation.

The Claude API. Upload the folder to the Skills endpoint (POST /v1/skills) and use it with the code-execution tool (API reference).

One gotcha worth knowing: Claude Code's Cowork and cloud sessions don't read ~/.claude/skills/ on your machine. They load the skills enabled on your claude.ai account. If a skill works in your terminal but not in Cowork, that's usually why (Claude Code docs).

A 2-minute test that the install worked

1. Ask: "What skills are available?" The skill's name should appear.
2. Give it a task that matches the description. For csv-quick-clean, upload a bank export with a title line and a few (1,200.00) amounts and ask "clean this up so it sums".
3. Check that Claude says it ran the script and shows a summary (header row found, rows removed, columns converted). If it just rewrote the data itself, the skill didn't trigger: make your request closer to the description or invoke it with /csv-quick-clean in Claude Code.

Skill vs MCP vs Project vs subagent

Anthropic's own comparison is the clearest one (Skills explained). Condensed:

Anthropic sums up the Skill/MCP split in one line: "MCP connects Claude to data; Skills teach Claude what to do with that data." And Skills vs Projects: "Projects say 'here's what you need to know.' Skills say 'here's how to do things.'"

A simple rule of thumb from our own building: if you've pasted the same instructions into Claude three times, make it a Skill. If you've copy-pasted the same data into Claude three times, connect it with MCP.

What makes a good Skill (lessons from building and testing ours)

We have built and tested three paid skill packs and a free sampler (the tests ship inside each one). The patterns that mattered most:

1. One job per skill. "Clean a CSV export" triggers reliably. "Do finance" doesn't.
2. Put the trigger phrases in the description. Write the words a user will actually type ("won't sum", "bank export", "tidy this").
3. Move maths and parsing into scripts. Then test the scripts like normal code. Our free sampler has 13 automated checks, including that cleaned amounts add up to the statement's closing balance.
4. Write rules for the failure you fear. For finance: never hand-edit numbers; say which columns didn't convert.
5. Keep SKILL.md short; link to references. Long tables and policies go in separate files that Claude opens only when needed.
6. Review before you install. A skill is code plus instructions. In Claude Code, the allowed-tools field can pre-approve tools for the turn that invokes the skill, so read it before you trust a skill from the internet.

Where to start

• Free: the Oarsman Skills Sampler (MIT licence) has two small skills, csv-quick-clean and ai-crawler-check, standard library only, no API keys. We used the ai-crawler-check matcher for our study of AI crawler rules on 2,000 websites.
• Skill packs (we built these; $29 each): Finance Analyst (clean exports, reconcile ledgers, explain budget variance, month-end pack; 29 included tests), SEO + AI Visibility (41 tests) and E-commerce Weekly Report (33 tests). The tests check the scripts and the skill format. They are not a promise about your results, and the Finance pack is not accounting or tax advice.