How to Create Your First Claude Skill in 20 Minutes
Claude Skills are folders containing a SKILL.md file plus any scripts or templates Claude needs. They turn a prompt you retype every week into something Claude loads automatically when relevant.
Short answer: create a folder, write a SKILL.md with YAML frontmatter (name and description), zip it, and upload it under Settings then Capabilities. Claude decides when to use it based on the description.
What is a Claude Skill, exactly?
A Skill is a directory. At minimum it holds one file named SKILL.md. Claude reads the frontmatter at startup and loads the full instructions only when a task matches. That progressive loading is why you can install dozens without burning context on each one.
The format is open — Anthropic published the spec, and Skills work across the Claude apps and the Agent SDK. A Skill can bundle Python scripts, reference documents, and templates alongside the instructions.
How do you write SKILL.md?
Frontmatter first, then the instructions as plain Markdown.
---
name: weekly-report
xdescription: Builds a weekly status report from a CSV of tickets. Use when the user asks for a weekly summary or status report.
---
# Weekly Report
1. Read the attached CSV.
2. Group rows by team.
3. Output a summary table, then three risks.
Remove the x before description — it is only here to stop the block rendering oddly. The description is the most important line in the file, because that is what Claude matches against your request.
How do you install a Skill in Claude?
- Zip the folder — the ZIP must contain the folder, not just
SKILL.mdloose. - Open Claude Settings, then Capabilities (or Skills, depending on the client).
- Upload the ZIP and enable the Skill.
- Start a new chat and make a request that matches the description.
- Check that Claude announces it is using the Skill — if it does not, the description needs work.
If Claude never triggers your Skill, the fault is almost always a vague description. “Helps with reports” will not fire; “Builds a weekly status report from a CSV of tickets” will.
What separates a good Skill from a bad one?
| Bad Skill | Good Skill |
|---|---|
| Vague description | Explicit trigger conditions |
| 500 lines of prose | Steps and checklists |
| Requires 5 files | Self-contained where possible |
Keep the main instructions under about 500 lines. If a task needs more, put detail in separate reference files that Claude loads on demand. Numbered procedures beat paragraphs — the model follows them more reliably.
What are the limits?
Skills do not add new capabilities; they add instructions and optional scripts. They cannot bypass Claude’s safety rules or run code outside the sandbox. Bundled scripts execute in a restricted environment, so no network calls to arbitrary hosts by default.
Version control is manual — there is no registry or auto-update. Teams typically keep Skills in a git repo and share the ZIPs. That is a real weakness if you expect package-manager ergonomics.
Skills suit people with a repeatable workflow they want standardized: report generation, code review checklists, brand voice rules. They are overkill for a one-off prompt you will never reuse.
Quick Summary
- A Claude Skill is a folder with a SKILL.md file and optional scripts.
- The YAML description determines when Claude triggers the Skill — make it specific.
- Zip the folder and upload it under Settings, then Capabilities.
- Keep instructions under roughly 500 lines and use numbered steps.
- Skills add instructions, not new powers — and they have no auto-update.
