Claude Skills are the most powerful — and most misunderstood — extension mechanism in Claude Code. They're also the closest thing to a real superpower if you write them well.
A Skill is a markdown file that teaches Claude how to do one specific task. You write it once; Claude reads it on demand whenever the task comes up. Done right, a single 100-line Skill replaces 30 minutes of explaining yourself every session.
This guide covers what Skills actually are, when Claude fires them (this is the tricky part), how to structure one properly, and five real Skills you can write today.
What a Skill actually is
A Skill is a folder in ~/.claude/skills/ (or inside a project at.claude/skills/) containing a SKILL.md file.
Each SKILL.md has frontmatter (YAML metadata at the top) and a markdown body explaining the task. The minimum viable Skill:
---
name: weekly-status-email
description: Draft a weekly status email to my manager
---
# Weekly Status Email
When the user wants to write a weekly status email, ask for:
1. Three things you shipped this week
2. One blocker or risk
3. The single thing you're focused on next week
Then write the email in this structure:
- Opening: 1 sentence summarizing the week
- Shipped: 3 bullets
- Risks: 1-2 bullets if relevant
- Next: 1 sentence on the focus
Keep it under 200 words. No corporate jargon.That's a complete Skill. It fires when the user mentions writing a status email; Claude reads it; the email gets written in your preferred structure.
When Claude actually fires a Skill
This is the part everyone gets wrong on their first try. Skills aren't always loaded. Claude only invokes a Skill when the user's request matches the Skill'sdescription. The description is the trigger.
Two consequences:
- Vague description = the Skill rarely fires. If your description is "Help with writing" — too broad. Claude won't know when to invoke it.
- Specific description = Claude triggers it precisely. "Draft a weekly status email to my manager" is unambiguous. Claude knows exactly when this fits.
Test your descriptions by asking: "If a user said <X>, would Claude invoke this?" If the answer requires interpretation, sharpen the description.
The 6-section structure that consistently works
After writing hundreds of Skills, this is the structure that fires reliably and produces high-quality output:
1. Frontmatter (name + description)
Name in kebab-case. Description is the trigger sentence — write it like you're describing the Skill to a colleague.
2. Heading + one-line summary
Re-state the goal in plain language. This is what Claude reads first to confirm the task fits.
3. Required inputs
What Claude should ask the user for before starting. Don't skip this — even "what topic?" counts. It prevents Claude from guessing.
4. The process
Numbered steps. Each step does one thing. Atomic. If a step says "analyze the thing," break it into smaller steps explaining what "analyze" means in this context.
5. Output format
What the final answer should look like. Be specific: length, structure, formatting, what not to include. This is the single highest-leverage section.
6. Common pitfalls
Failure modes specific to this task. Tells Claude what to avoid. Examples: "Don't invent statistics that aren't in the source." "Don't use buzzwords like synergy or unlock."
5 Skills you can write today
1. PR Title Writer
Description: "Write a concise, conventional-commit-style title for a pull request."
Trigger words: "PR title for...", "commit message for..."
Why it's useful: every dev writes 10+ PR titles a week. Standardizing the format across the team is leverage.
2. Weekly Manager Update
Description: "Draft a weekly update email to my manager covering wins, blockers, and next-week focus."
Why it's useful: most people procrastinate this and write it poorly under time pressure. A Skill removes the friction.
3. Customer Email Reply
Description: "Draft a customer support email reply that acknowledges their issue, explains the resolution, and sets expectations."
Add your tone guidelines + 3 examples of good replies you've sent. Claude will match your voice.
4. SQL Query Reviewer
Description: "Review a SQL query for performance issues, security risks, and style violations."
Add your database's conventions in the body (Postgres vs MySQL flavors, index strategy, etc.).
5. Twitter Thread Composer
Description: "Turn a long-form essay or article into a 6-tweet thread with a strong hook and a clear payoff."
Include your own past good threads as examples. Claude will pattern-match.
The 4 most common Skill-writing mistakes
- Vague description. "Help with writing" fires for everything and nothing. Be specific to the point of feeling restrictive.
- Skipping "required inputs." Claude guesses what you wanted, gives you a generic answer, you have to redo it.
- No examples. "Write in our brand voice" doesn't teach the voice. Three examples teach it instantly.
- Too long. 500-line SKILL.md files don't fire — Claude reads them but the signal-to-noise ratio drops. Aim for 100-200 lines.
How to distribute Skills across your team
Skills travel as git-tracked files. Drop a .claude/skills/ folder in any project repo and every contributor with Claude Code gets those Skills automatically. This is the cleanest internal-platform pattern we've seen.
For company-wide Skills (not project-specific), keep them in~/.claude/skills/ on each contributor's machine, distributed via a shared git repo people clone to that path.
A bigger question — write them, or buy them?
Writing your own Skills makes sense when they're truly specific to your work — your tone, your code conventions, your customer voice. Anyone can write "PR title writer" in 10 minutes.
For everything generic — the 80% that's the same across most knowledge workers — buying a curated library beats writing from scratch. The Better with Claude Skills Pack covers 2,000+ tasks across 10 categories. Each one is structured exactly like this guide describes, just already done.
Use the pack for the generic 80%. Write your own for the specific 20%. That's the leverage stack.