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 - Lists the phrases that trigger it - Sets guardrails so it doesn't go off-script - Includes at least one worked example We'll build a `code-reviewer` skill as the example. Step 1 — Create the repo -------------------------- mkdir code-reviewer-skill cd code-reviewer-skill git init Name your repo after the skill. Kebab-case, job-first: `seo-content-optimizer`, `sql-query-wizard`, `react-test-writer`. People search for the job, not the tool. Step 2 — Write the SKILL.md ----------------------------- Create `SKILL.md` in the root: --- name: code-reviewer version: "1.0.0" description: > Reviews pull request diffs for bugs, security issues, and style violations. Outputs a structured review with severity levels (critical / warning / suggestion). license: MIT triggers: - review this code - review my PR - check this diff - what's wrong with this 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? The description is what shows in search results — write it for a developer who has 3 seconds. triggers — the phrases a user types that activate this skill. Include variations. Think about how a junior developer would phrase the request, not how you would. rules — the single most important section. 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: # code-reviewer Reviews pull request diffs for bugs, security issues, and style violations. ## Install claude skills add code-reviewer ## 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) ---------------------------------------------- An `evals/` folder with 3–5 input/output pairs dramatically increases your approval chance and user trust. 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. Our scraper validates the SKILL.md schema and a reviewer checks it within 24 hours. What reviewers check --------------------- - Does the description accurately describe what the skill does? - Are the triggers specific enough to not fire accidentally? - 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.