How to write your first SKILL.md file — a complete guide with examples

Writing your first SKILL.md is easier than you think. A skill that ships, gets installed, and earns stars follows a simple pattern. Here's the complete walkthrough.

What you're building

A SKILL.md file that:

• Has a clear, searchable name
• Tells the agent exactly what job it does
• Says when to use it, in the words people actually type
• Sets guardrails so it doesn't go off-script
• Includes at least one worked example

We'll build a diff-reviewer skill as the example.

Step 1 — Create the repo

mkdir diff-reviewer
cd diff-reviewer
git init

Name your repo after the skill. Kebab-case, job-first: seo-content-optimizer, sql-query-wizard, pr-description-writer. People search for the job, not the tool.

Step 2 — Write the SKILL.md

Create SKILL.md in the root:

---
name: diff-reviewer
description: Reviews pull request diffs for bugs, security issues, and style violations, and outputs a structured review with severity levels (critical / warning / suggestion). Use when asked to review code, review a PR, check a diff, or say what's wrong with a piece of code.
license: MIT
---

# Diff reviewer

## Rules
- always assign a severity (critical / warning / suggestion)
- never suggest changes outside the diff
- flag any use of eval(), exec(), or shell injection patterns as critical
- keep each comment to two sentences maximum
- if code is clean, say so explicitly — don't invent issues

Breaking it down:

name — lowercase, kebab-case, unique in the marketplace. Run a search on ClaudeSkill before you commit to a name.

description — two to three sentences. Start with a verb. What does the skill do? What does its output look like? When should it be used?

when to use it — there is no separate triggers field. Claude reads only the name and description up front and loads the full skill when a request matches the description, so put the phrases people actually use ("review my PR", "check this diff") in the description. Think about how a junior developer would phrase the request, not how you would.

rules — the single most important part of the body (plain Markdown under the frontmatter, not a frontmatter field). Rules are the guardrails. Each one should be a concrete, testable statement. "Be helpful" is not a rule. "Never suggest changes outside the diff" is.

Step 3 — Write a README.md

Keep it short. Three headers:

# diff-reviewer

Reviews pull request diffs for bugs, security issues, and style violations.

## Install

Save SKILL.md as ~/.claude/skills/diff-reviewer/SKILL.md
(or .claude/skills/diff-reviewer/SKILL.md to use it in one project).

## How it works

Paste a diff or share a file. The skill outputs a structured review
with severity levels: critical, warning, or suggestion.

## Example

Input: a 40-line Python function with a SQL string concatenation.
Output:
  [critical] Line 12: SQL string concatenation is vulnerable to injection.
             Use parameterised queries instead.
  [warning]  Line 8: variable name `d` is not descriptive.

Step 4 — Add evals (optional but recommended)

Add an evals/ folder with 3–5 input/output pairs. Create evals/01-sql-injection.md:

input: |
  def get_user(db, username):
      return db.execute("SELECT * FROM users WHERE name = '" + username + "'")

expected_output: |
  [critical] SQL string concatenation on line 2 is vulnerable to
  injection. Use parameterised queries: db.execute("SELECT * FROM
  users WHERE name = ?", [username])

Step 5 — Push and submit

git add .
git commit -m "initial release"
git push origin main

Then go to claudeskil.com/submit, paste your GitHub repo URL, and hit Submit. Submissions are reviewed before they're published.

What reviewers check

• Does the description accurately describe what the skill does?
• Is the description specific enough that the skill isn't picked for unrelated requests?
• Are the rules concrete and testable?
• Is the license open-source?
• Is the README readable?

That's it. No minimum install count, no approval fee. Open-source and ready to ship.