How to Create a Claude Skill (SKILL.md): Write, Test and Review One for SEO

To create a Claude skill you write one SKILL.md file in its own folder: a frontmatter with a name and a description, then plain Markdown instructions. That part takes minutes. What takes care is the three edges where SEO skills fail: the agent loads the skill for the wrong job, never loads it at all, or keeps going past the point where a human should decide. This guide covers how to set those edges, test that the skill loads, and review it with the free skill-review. The examples come from our Claude SEO skills; the method works for any skill.

Short answer: give the skill one job. Write a two-sentence description that says when to use it and when not to, naming the sibling skill that handles the other case. Keep the body to the goal, the constraints and the steps, move long lists into references/, and end with a Done when line the agent can check. Mark every side effect (publishing, CMS writes, spend) as something a human approves.

What goes in a SKILL.md file?

A skill is a folder with a SKILL.md and, if needed, a references/ folder. Put the folder in your agent's skills folder (.claude/skills/<name>/ in a project for Claude Code; the install guide has the paths for Cursor and Codex). The file has two parts:

• Frontmatter: name (the folder name) and description (when to load it). Claude Code accepts more fields, but the Claude Code docs note that other tools only support the fields in the open Agent Skills spec. If you want the same skill to work in Cursor and Codex, start with name and description.
• Body: what the agent should achieve, what it must not do, the steps, and how it knows it is done.

Here is the shape, as a made-up example for a check that is easy to picture:

---
name: hreflang-audit
description: Use when a multi-language site needs its hreflang tags checked against the live pages. Not for translating content or choosing which markets to enter.
---

# Hreflang audit

Check that every language version links to every other version and to itself, with valid language codes.

## Constraints
- Read-only: report problems, never edit templates or the CMS.
- Read the live HTML; do not trust the sitemap alone.

## Done when
A table of URL pairs with missing or one-way links, and the fix for each.

Everything else is detail that supports those parts: official sources, dated facts, edge cases. That detail usually belongs in references/, which the agent opens only when a step points to it.

How do you write a description that triggers at the right time?

The description is the only part the agent reads before deciding. The Claude Code docs say Claude uses it to decide when to apply the skill and recommend putting the key use case first. Short wins.

A description that routes well has two sentences:

1. When to use it, in the words of a real request. "Use when rankings, AI Overviews or AI citations moved" matches what someone actually types. "A comprehensive, best-in-class SEO solution" matches nothing.
2. When not to use it, ideally naming the skill that covers that case. This is what keeps two related skills from fighting over the same request.

The pack's two answer-engine skills show the second sentence doing its job. aeo-answer-surface-playbook is for winning one named answer surface, such as a featured snippet or an AI Overview, and its description points brand-level citation work to geo-citation-playbook. The GEO skill's description points the other way. A request about a featured snippet and a request about being cited by ChatGPT Search each load one skill, not both.

Avoid "pick me" wording ("always use this skill for any SEO task"). It makes the skill load for jobs it was not written for.

How narrow should an SEO skill be?

Split skills by decision, not by topic. "SEO" is a topic; "should we build these 500 location pages?" is a decision. A skill scoped to one decision has a clear input, a clear output and a clear place to stop.

A skill is too broad when its description needs "and" three times, or its steps branch into unrelated workflows. It is too narrow when it only works for one URL or duplicates a step another skill owns. A clearer description on an existing skill often beats a new skill that overlaps it.

What should an SEO skill never do on its own?

Anything with a side effect outside the repository: publishing a page, writing to a CMS, changing robots.txt on production, spending money. Name these in the constraints and route them to a human.

Tie approval to real side effects only. A skill that says "ask before every step" trains people to click yes without reading. "Read anything, write only to a branch, a human merges" is both safer and faster. If you are building an agent rather than a single skill, seo-agent-design is the contract to write first: which tools it gets, what the approve path looks like, and what it must refuse.

How do you keep an SEO skill from going stale?

Search guidance changes often. Three habits help:

• Date your facts and link the source. "As of November 2026, per [official doc]" lets the next reader check it in one click.
• Keep volatile lists in references/. The body stays stable; the list is the part you update.
• Schedule a re-check. A weekly triage, like the one in the triage guide, tells you when a fact in a skill has moved.

Never let a skill invent numbers. If a step reports a rate (citations, clicks, coverage), make it report the sample size with it.

How do you test that a new skill loads at the right time?

Check the listing first: run /skills in Claude Code (or ask "What skills are available?") and confirm the name appears. Then send three requests:

1. A realistic request for the skill's job, worded the way a colleague would type it. The skill should load.
2. A request for the sibling skill's job. This skill should stay out.
3. A request near the edge of the scope, to see where the skill stops.

If the first request misses, the description is too vague. If the second one loads it, the "when not to use" sentence is too weak. Fix the description before you touch the body.

How do you verify that a skill did its job?

End the body with a Done when line that describes an output someone can check, not an effort. "A table of URL pairs with the fix for each" is checkable. "Hreflang is improved" is not.

A one-line Verify check after it catches a half-finished run: for example, "every row links to a live URL". If you cannot write that line, the goal is probably still too vague.

How do you review an SEO skill with skill-review?

skill-review is free and MIT-licensed in the free repository. Install it globally (see the install guide) and ask your agent to review one skill at a time:

Review .claude/skills/hreflang-audit/SKILL.md with skill-review.
Report only; don't edit yet.

It scores the skill on a five-line rubric, 0 to 2 per line, with a quote or a named gap behind each score, and ends with one verdict: ship, tighten, rewrite, or delete/merge. It also scans sibling skills for overlapping descriptions.

When you let it edit, it separates small, safe fixes (a tighter description, a Done-when line, moving a long list into references/) from changes that need the owner's OK (deleting, merging, changing the purpose). It only reports on skills you don't own, such as vendor or plugin skills. Run it on any third-party skill before you trust it, including the ones in this pack.