What you will build
By the end of this guide you will have one working custom skill: a folder with a SKILL.md file, zipped, uploaded to your Claude account, and firing on the right prompts. The same structure scales from a five-line instruction file to a multi-file package with scripts and templates.
Prerequisites (3): a Pro, Max, Team, or Enterprise Claude plan, code execution enabled in your settings, and a task you repeat often enough to be worth automating.
Pick the right task
Not every task deserves a skill. The best candidates share three traits:
- a.You repeat it at least weekly. Writing captions, formatting reports, prepping sales calls, building pages.
- b.You explain it the same way every time. If your prompt for the task barely changes, that prompt is already a skill waiting to be saved.
- c.Quality depends on rules. Voice rules, formats, checklists, banned words. Skills shine where consistency matters.
Fastest start: take a long prompt you already reuse, and turn that into your first skill. You are not writing anything new, just relocating it so Claude carries it for you.
Create the skill folder
- a.On your computer, create a folder named after the skill in kebab-case, for example weekly-report-writer.
- b.Inside it, create one file named exactly SKILL.md. This file is the skill. Everything else is optional.
weekly-report-writer/
SKILL.mdWrite the frontmatter
Open SKILL.md and start with a YAML frontmatter block. Two fields are required, and the description is the single most important line in the whole skill because Claude uses it to decide when to invoke the skill.
---
name: Weekly Report Writer
description: Write the Monday weekly report from raw metrics and notes.
Trigger when asked to write, draft, or update a weekly report, status
update, or Monday summary. Follows the fixed report format and tone.
---- a.name: human-friendly, 64 characters maximum.
- b.description: 200 characters maximum. Say what the skill does and name the exact phrases and task types that should trigger it.
- c.The match is semantic, not keyword-based, but concrete task names still beat vague ones. "Brand stuff" misses. "Write, draft, or update a weekly report" fires.
Write the instructions
Below the frontmatter, write the Markdown body: the instructions Claude follows once the skill fires. Structure it like you are onboarding a new hire who will do this task without you.
# Weekly Report Writer
## Process
1. Read the metrics and notes provided by the user
2. Open with the single most important number and what changed
3. Follow the fixed section order: Wins, Numbers, Blockers, Next week
4. Keep the full report under 300 words
## Rules
- Plain language. No corporate filler, no hype words.
- Every claim needs a number or a named source
- Never invent data. If a metric is missing, flag it.
## Example output
[paste one real, finished report you are happy with]- a.Write rules as commands: "always", "never", "if X then Y". Commands are followed more reliably than descriptions.
- b.Include at least one example of expected input and output. Examples teach what success looks like faster than rules do.
- c.Keep only always-needed content in SKILL.md. Long reference material belongs in separate files (next step) so the skill stays fast.
Add optional folders (only if needed)
Simple skills stop at Step 4. Bigger skills can add three optional folders:
| Folder | What goes in it | Example |
|---|---|---|
| references/ | Detailed docs Claude opens only when needed | Full style guide, format spec, glossary |
| assets/ | Templates and files the output builds on | HTML template, document skeleton |
| scripts/ | Executable code the skill can run | A Python script that processes data files |
Point to these files from SKILL.md with relative paths and tell Claude when to open each one, for example: "Read references/style-guide.md before writing any copy."
Never hardcode API keys, passwords, or client data into a skill, and review any skill you download from someone else before enabling it.
Zip the folder
- a.Compress the skill folder itself so the folder is the root of the archive. On Mac: right-click the folder and choose Compress. On Windows: right-click, Send to, Compressed (zipped) folder.
- b.Check the zip before uploading: opening it should show your skill folder with SKILL.md directly inside. Loose files at the root, or a folder nested inside another folder, will fail the upload.
Upload and enable the skill
- a.In Claude, open Customize and go to Skills.
- b.Click the + button, then + Create skill, and upload your zip.
- c.The skill appears in your list. Toggle it on.
- d.Uploaded skills are private to your account. On Team or Enterprise plans, admins can provision shared skills for the whole organization.
Test with real prompts, then iterate
- a.Open a fresh conversation and give a realistic prompt without naming the skill: "Write this week's report from these notes."
- b.Confirm the skill fired and check the output against your rules and example.
- c.Skill did not fire? Sharpen the description with the phrases you actually use. Skill fired but output drifted? Tighten the body instructions.
- d.Change one thing at a time, re-zip, re-upload, retest. Testing incrementally beats rebuilding a complex skill in one go.
Skills compose. Claude can use several together in one task, each handling its own layer. Build small focused skills, one job each, instead of one skill that tries to do everything.
FAQs
What exactly is a skill?
A folder containing a SKILL.md file with metadata and instructions, plus optional scripts, references, and assets. Claude loads it automatically whenever a conversation matches the description, so your process is written once and applied every time.
Do I need a paid plan?
Yes. Custom skills require a Pro, Max, Team, or Enterprise plan with code execution enabled.
How is a skill different from a saved prompt or a project?
A saved prompt only works when you paste it. Project instructions only apply inside that project. A skill fires on its own in any conversation that matches its description, and it can carry supporting files and scripts with it.
Where does the skill work once enabled?
In regular chats, in Cowork sessions including scheduled ones (they sync your enabled skills at session start), and skills can also be used with Claude Code and through the API.
Next steps
- a.Build your second skill next week, not today. One working skill you refine beats five half-tested ones.
- b.Browse Anthropic's public skills repository on GitHub for patterns worth borrowing, including the document skills that power Claude's own file creation.
- c.When a skill matters to your business, keep the local folder in version control so every change is tracked.
Version 1.0 · First published July 2026 · Steps verified against the Claude Help Center and Anthropic skill authoring docs, July 2026