Claude Skills Examples: 6 Real SKILL.md Files and What Makes Each One Work

The fastest way to understand Claude skills is to read a few real ones. A skill is not a framework or a plugin API — it is a folder with a markdown file in it. Claude reads the file's description, decides whether the current task matches, and if it does, follows the instructions inside. That is the whole mechanism. Below are worked examples across the categories people actually use, each showing what makes it fire and what makes it useful.

The anatomy every example shares

A skill lives at .claude/skills/<name>/SKILL.md in a project, or ~/.claude/skills/ if you want it everywhere. The file starts with YAML frontmatter and continues with plain markdown:

---
name: code-review
description: Review a diff for correctness, security, and clarity.
  Use when the user asks for a review, before opening a PR, or
  after finishing a feature.
---

## How to review

1. Read the full diff before commenting on any single line.
2. Rank findings: correctness > security > performance > style.
3. For each finding, give the file, the line, and the fix.
4. Do not invent problems. If the diff is clean, say so.

Two rules explain most of the difference between a skill that works and one that never loads. First, the description is the trigger — it is the only part Claude sees before deciding to use the skill, so it must name the situations, not just the topic. Second, the body is a procedure, not a personality. "You are a world-class reviewer" changes nothing. A numbered checklist changes everything.

Example 1: a commit message skill

The smallest useful skill category. The description says "Use whenever writing a git commit message or a PR title", and the body encodes your convention: a Conventional Commits prefix, imperative mood, a subject under seventy characters, and a body that explains why rather than what. Nobody has to remember the rules again, and every commit in the repo starts looking like it was written by the same person.

Example 2: a test-writing skill

This is where skills beat prompting. The body states the framework, the file naming convention, and the non-negotiables: test behavior rather than implementation, cover the failure path, never assert on internal state, run the suite before claiming it passes. The description triggers on "write tests", "add coverage", and "after implementing a new function". Now Claude writes tests in your idiom instead of a generic tutorial style.

Example 3: a PDF or document skill

Document skills are the clearest demonstration of why skills bundle code. Extracting text from a PDF, filling a form, or merging files is mechanical work that a script does perfectly and a language model does approximately. So the skill ships a Python script alongside the markdown and the instructions say "run this script" instead of "figure it out each time". Anthropic's own open-source document skills work exactly this way — see our guide to Claude skills for PDF for the full breakdown.

Example 4: a brand voice skill

Not everything is code. A brand voice skill contains your tone rules, your banned phrases, your preferred spellings, and a short before/after table showing an off-brand sentence next to its corrected version. The description triggers on any drafting or editing of public copy. Examples matter more than adjectives here: showing two rewritten sentences teaches more than a paragraph describing the voice.

Example 5: a debugging methodology skill

The body is a loop: reproduce the bug, form a hypothesis, add instrumentation, confirm or discard the hypothesis, fix the root cause, remove the instrumentation. The value is not the knowledge — Claude knows how to debug — it is the discipline. Without the skill, the default behavior under time pressure is to patch the symptom. With it, the process runs the same way every time.

Example 6: a project-specific skill

The highest-value skill on most teams is the one nobody else could write: how your deployment works, which environment variables matter, what the staging URL is, why the migration script must run before the build. It is boring, unglamorous institutional knowledge, and encoding it once saves every future session — and every future teammate — from rediscovering it.

Turning an example into your own

Copying a skill is a starting point, not a destination. The pattern that works: take an example, use it for a week, and every time Claude does something you have to correct, add one line to the skill preventing it. After a few rounds you have a document that encodes your actual standards rather than someone else's.

Before you rely on a skill, verify it loads. Ask Claude which skills it has available, then phrase a request naturally and see whether the right one fires. If it does not, the description is almost always the problem — our free SKILL.md validator catches the frontmatter mistakes that make a skill invisible, and this guide explains the triggering rules in detail.

FAQ

Keep reading