seoskills.sh
Catalog/Docs/What are agent skills? How SKILL.md files work

What are agent skills?

Updated

Agent skills are how you teach an AI agent a job once instead of explaining it in every chat. Each skill is a folder with a SKILL.md file inside: a name and a description of what the skill does and when to use it, followed by the instructions themselves. Under the open Agent Skills standard, an agent reads each skill's name and description at startup and loads the full instructions only when your task matches.

What's inside a skill folder

A skill is a directory, and only one file in it is required. The Agent Skills specification lays it out like this:

skill-name/
├── SKILL.md       # required: metadata and instructions
├── scripts/       # optional: code the agent can run
├── references/    # optional: docs the agent reads when needed
└── assets/        # optional: templates, images, data files

Scripts let a skill do work a prompt can't, like calling an API or processing a CSV export. Reference files hold long material, such as detailed API docs, that the agent opens only when a task needs it. When you install one of the catalog's own skills from seoskills.sh, you get the whole folder, scripts and reference files included.

In Claude Code, a skill you keep for yourself lives at ~/.claude/skills/<skill-name>/SKILL.md and works in all your projects. A project skill lives at .claude/skills/<skill-name>/SKILL.md, and once you commit it, everyone working in that repository gets it.

What a SKILL.md file contains

A SKILL.md has two parts: YAML frontmatter between --- lines, then Markdown instructions. The spec requires two frontmatter fields:

  • name: up to 64 characters of lowercase letters, numbers and hyphens, matching the folder name
  • description: up to 1,024 characters on what the skill does and when to use it

Optional fields cover a license, environment requirements (compatibility), extra metadata, and an experimental allowed-tools list of pre-approved tools. The body has no required format, though the spec recommends step-by-step instructions, examples of inputs and outputs, and common edge cases. Here is a minimal example for a hypothetical title tag check:

---
name: title-tag-review
description: Reviews page title tags for missing, duplicate or overlong titles and suggests rewrites. Use when the user asks to check, audit or rewrite title tags.
---

1. Get the list of URLs to review, or ask for a crawl export.
2. Record each page's title tag.
3. Flag pages with no title, a title shared with another page, or a title likely to be cut off in search results.
4. Suggest a rewrite for each flagged page and explain the change.

The description carries more weight than any other line, because the name and description are all the agent sees before it decides to load the skill. A vague one such as "Helps with SEO" can leave the skill unused, or loaded for the wrong task. Name the job, and use the words people actually type when they ask for it. For a full walkthrough, see how to write a SKILL.md.

How an agent decides to load a skill

Agents load skills in three stages, which the spec calls progressive disclosure:

  1. At startup, the agent reads the name and description of every installed skill, about 100 tokens each.
  2. When your task matches a description, it loads that skill's full SKILL.md. The spec recommends keeping the body under 5,000 tokens and 500 lines.
  3. Scripts, references and assets load only when they're needed.

So a long skill costs little until it runs. The descriptions are the part you always pay for. Claude Code keeps the description of every skill Claude can invoke in context on each turn, and when many skills are installed it drops some descriptions to fit, starting with the skills you use least.

You don't have to wait for the agent to choose. In Claude Code, type / and the skill's name to run it directly. A skill with disable-model-invocation: true in its frontmatter runs only when you invoke it that way, which suits anything with side effects.

What skills are used for

Anything you'd otherwise explain to your agent again and again. Claude Code's docs suggest writing a skill when you keep pasting the same instructions, checklist or multi-step procedure into chat, or when part of your CLAUDE.md has grown into a procedure rather than a fact. SEO work is full of these, and the catalog sorts its skills into 14 categories, from Technical SEO to Local SEO. Three examples:

  • Schema adds, fixes or optimizes schema markup and structured data on your site.
  • Brief produces an editor-ready content brief for a target keyword or topic.
  • Striking Distance Opportunity Finder finds keywords in Search Console positions 11 to 20 that have real demand, ranks them by projected click gain, and maps each one to its page.

A skill gives the agent a method. When the agent also needs a live connection to a tool such as Search Console, that's the job of an MCP server, and skills vs MCP explains how the two fit together.

One format, many agents

Agent Skills is an open standard, so the same folder works across tools. Claude Code, Cursor, Codex, ChatGPT and Gemini CLI all document support for it, and the open-source skills CLI can install skills into many more agents, GitHub Copilot, OpenCode and Cline among them. Cursor even loads skills from Claude Code's and Codex's skill folders for compatibility.

The core format travels well, but some extras stay agent-specific. Claude Code adds fields of its own, such as context: fork, which runs a skill in a subagent, and the skills CLI's compatibility table lists Claude Code as the only agent that supports it. Each agent also reads skills from its own folders, listed in where agents keep skills.

Install a skill, and read it first

Every skill page on seoskills.sh shows its install command. The catalog's own skills install from our index by slug, and a skill by another author installs from that author's GitHub repository:

npx skills add https://seoskills.sh --skill striking-distance-finder
npx skills add https://github.com/coreyhaines31/marketingskills --skill schema

Add -a claude-code or -a cursor to install for one agent. The step-by-step versions are install skills in Claude Code and use skills in Cursor.

Because a skill can bundle scripts and pre-approve tools, read it before you install it. seoskills.sh runs a static security scan on every listed skill, shows the result on the skill page, and labels skills that pre-approve shell commands or web fetching. Skill safety covers what to look for.

Next