The Agent Skills standard: one config format for every editor

For the past year, every AI code editor invented its own config format. Claude Code uses CLAUDE.md. Cursor uses .cursorrules (now .cursor/rules/*.mdc). Windsurf has .windsurfrules. Codex has its own thing. If you use two or three of these tools, you maintain two or three separate rule files that say mostly the same thing in slightly different formats.

Agent Skills fixes this. It’s an open standard for a single file format, SKILL.md, that works across 20+ editors. Write your config once, drop it in the right directory, and it works in Claude Code, Cursor, VS Code, Codex, Gemini CLI, Amp, Roo Code, Goose, and a growing list of others.

This isn’t a proposal or a draft spec. These editors already support it. The standard is live and adopted.

What a skill is

A skill is a directory with a SKILL.md file inside it. That file has two parts: YAML frontmatter that tells the editor when to use the skill, and markdown content with instructions the editor follows when the skill is active.

code-review/
├── SKILL.md           # Required
├── references/        # Optional: detailed docs loaded on demand
├── scripts/           # Optional: executable code
└── assets/            # Optional: templates, schemas, data files

The SKILL.md is the only required file. Everything else is optional and loaded on demand.

Here’s a minimal example:

---
name: code-review
description: Reviews code for bugs, style violations, and project guideline compliance. Use when reviewing pull requests, checking code quality, or auditing changes.
---

Review the changed code for:

1. Bugs and logic errors
2. Project convention violations (check AGENTS.md or equivalent)
3. Missing error handling
4. Test coverage gaps

For each issue found, include the file path, line number, and a specific fix suggestion.
Only report issues you're confident about.

That’s it. The editor reads the name and description at startup, decides when the skill is relevant based on the description, and loads the full markdown body when it activates the skill.

The frontmatter

Two fields are required:

name: Lowercase letters, numbers, and hyphens. Max 64 characters. Must match the directory name. This becomes the slash command (/code-review).

description: What the skill does and when to use it. Max 1024 characters. This is the most important field because it’s how editors decide when to auto-load the skill. Be specific. “Reviews code for bugs, style violations, and project guideline compliance” is good. “Helps with code” is not.

Optional fields:

---
name: code-review
description: Reviews code for bugs, style violations, and project guideline compliance.
license: Apache-2.0
compatibility: Requires git
metadata:
  author: your-name
  version: "1.0"
allowed-tools: Bash(git:*) Read Grep
---

license is worth including if you’re sharing the skill publicly. compatibility notes any environment requirements. metadata is a free-form key-value map for whatever else you want to track. allowed-tools is experimental and support varies across editors.

Where skills live

Where you put the skill directory determines its scope:

  • Personal (~/.claude/skills/code-review/SKILL.md): Available across all your projects
  • Project (.claude/skills/code-review/SKILL.md): This project only

Replace .claude/ with .cursor/ or whatever your editor uses. The directory name varies by editor, but the SKILL.md format inside is the same.

Personal skills are useful for things you want everywhere: your code review style, your commit message format, your preferred error handling patterns. Project skills are for project-specific context: this project’s API conventions, this project’s test patterns.

If a personal skill and a project skill share the same name, the project skill wins.

How editors discover skills

Most editors that support Agent Skills do two things with them:

Auto-discovery: The editor reads the name and description of every installed skill at startup. When you ask it to do something that matches a skill’s description, it loads the full skill automatically. You don’t have to invoke it.

Direct invocation: You can also run a skill explicitly with /skill-name. This is useful when you want to force a specific workflow regardless of what the editor thinks is relevant.

The auto-discovery behavior is why the description field matters so much. A skill with a vague description won’t get loaded at the right times. A skill with a specific description that lists concrete use cases will.

Writing good skill instructions

The markdown body after the frontmatter is where the actual instructions live. There are no format restrictions. Write whatever helps the agent do the job.

A few things I’ve found work well:

Be specific about what to do, not just what the skill is for. “Review code for bugs” is a description. The instructions should say how: what to look for, what format to report in, what to skip.

Reference real files. “Follow the pattern in src/hooks/useUser.ts” gives the agent something concrete to look at. “Follow established patterns” gives it nothing.

Include negative constraints. “Do not modify code directly, only report findings” prevents the agent from doing things you don’t want. “Do not use axios, use the typed client in src/lib/api.ts” stops it from reaching for training-data defaults.

Keep the main SKILL.md under 500 lines. The spec recommends this. If your skill needs more detail, put it in references/ files and point to them from the main file. The agent loads reference files on demand, so longer content doesn’t burn context until it’s needed.

Progressive disclosure

Skills follow the same progressive disclosure pattern we talk about in writing a lean AGENTS.md. Three tiers of context:

  1. Metadata (~100 tokens): The name and description are loaded at startup for every installed skill. This is always in context.
  2. Instructions (under 5000 tokens recommended): The full SKILL.md body loads when the skill activates. This is your main content.
  3. Resources (as needed): Files in scripts/, references/, and assets/ load only when the skill references them.

This structure means you can build complex skills without bloating context. A skill with a 200-line SKILL.md and 2000 lines of reference docs only uses 200 lines of context most of the time. The reference docs load when the agent decides it needs them.

Supporting files

The optional directories let you build more than simple instruction sets.

references/ holds detailed documentation the agent reads when needed. If your skill is about API development, you might have references/error-codes.md listing all your API error codes. The SKILL.md says “See references/error-codes.md for the full list” and the agent reads it when it encounters an error handling task.

scripts/ holds executable code. A validation script, a formatting tool, a data extraction utility. The agent can run these during its work. Languages depend on the editor, but bash and python are common.

assets/ holds templates, schemas, and other static files. A PR template the agent fills in. A JSON schema for config validation. A CSV lookup table.

Reference these files from your SKILL.md so the agent knows they exist:

## Resources

- See `references/api-patterns.md` for endpoint conventions
- Run `scripts/validate.sh` to check the output
- Use the template in `assets/pr-template.md` for pull request descriptions

SKILL.md vs AGENTS.md

If you’ve read our article on writing AGENTS.md, you might wonder how skills relate to your main config file.

They’re complementary. AGENTS.md is your project’s entry point: repo structure, commands, hard rules, links to docs. It’s always loaded, always in context.

Skills are specialized tools that load on demand. Your code review skill loads when you’re reviewing code. Your feature dev skill loads when you’re building a feature. They don’t compete for context with your AGENTS.md because they’re only active when relevant.

Think of AGENTS.md as the orientation document every new team member reads on day one. Skills are the specialized runbooks they pull off the shelf when they need them.

SKILL.md vs .mdc files

If you use Cursor, you might already have .mdc files in .cursor/rules/. Those use Cursor-specific frontmatter (alwaysApply, globs, description) to control when rules load.

SKILL.md files work alongside .mdc files. If you want rules that only work in Cursor, keep using .mdc. If you want rules that work in Cursor AND Claude Code AND Codex AND everywhere else, write a SKILL.md. Both formats can coexist in the same project.

The main difference: .mdc files have Cursor-specific features like globs for file-pattern triggering. SKILL.md files rely on the description field for auto-discovery, which is less precise but works everywhere. For most use cases, a well-written description is precise enough.

Who supports it

As of February 2026, these editors support Agent Skills natively:

  • Claude Code
  • Cursor
  • VS Code (GitHub Copilot)
  • OpenAI Codex
  • Gemini CLI
  • Amp (Sourcegraph)
  • Roo Code
  • Goose (Block)
  • TRAE (ByteDance)
  • Mistral Vibe
  • GitHub
  • Databricks
  • Spring AI

Plus about a dozen smaller tools. The full list is at agentskills.io.

The adoption happened fast. Six months ago this format didn’t exist. Now it’s the closest thing to a universal standard for agent configuration.

Getting started

If you already have project rules in any format, converting to SKILL.md takes about five minutes per skill:

  1. Create a directory: mkdir -p .claude/skills/my-skill
  2. Create SKILL.md with the frontmatter (name, description)
  3. Paste your existing instructions into the markdown body
  4. Test it: ask your editor to do something that matches the description, or invoke it with /my-skill

If you’re starting from scratch, pick one workflow you repeat often (code review, feature development, commit messages) and write a skill for it. Start small. One skill with 50 lines of clear instructions beats ten skills with vague ones.

We’ve published several ready-to-use skills on this site:

Each one is a SKILL.md you can copy into your project and start using immediately.