Open standard

SKILL.md format

SKILL.md is the open file format for AI agent skills. It's a short Markdown file with YAML frontmatter that tells an AI coding tool — Claude Code, Cursor, Codex CLI, Windsurf, Copilot, Gemini CLI, or any MCP-compatible client — how to do one specific job well.

By

Why a single Markdown file?

The Agent Skills standard was introduced by Anthropic in late 2025 and has since been adopted by 26+ AI coding tools and platforms. The design is deliberately minimal: a SKILL.md is just text that an AI model can read. No runtime, no compilation, no SDK lock-in.

Because the format is plain Markdown, skills are portable. The same file works in Claude Code today, in Cursor tomorrow, and in whatever tool replaces them next year — as long as that tool supports the standard.

Anatomy of a SKILL.md file

A SKILL.md has two required parts: YAML frontmatter (metadata) and a Markdown body (instructions). Here's a minimal example:

---
name: code-review
description: Thorough code review — checks correctness, security, performance, and tests.
---

# Code review

When the user asks you to review code, follow these steps:

1. Identify the files changed in the current diff.
2. Check for correctness, security, and performance issues.
3. Verify there are tests for new behavior.
4. Rank findings by severity (critical, high, medium, low).
5. Suggest specific code fixes for each finding.

Required frontmatter fields

  • name — short kebab-case identifier (e.g. code-review).
  • description — one or two sentences. The AI uses this to decide whether to load the skill, so write triggers, not features.

Common optional fields

  • version — semver for the skill itself.
  • author — name or username of the skill creator.
  • tags — array of free-form tags for discovery.
  • platforms — list of supported tools (CLAUDE_CODE, CURSOR, CODEX_CLI, etc.).
  • permissions — declared capabilities the skill needs (filesystem, network, shell).

Where SKILL.md files live

  • Claude Code: .claude/skills/<name>/SKILL.md in your project root, or globally at ~/.claude/skills/.
  • Cursor: .cursor/rules/<name>.mdc (Cursor's equivalent format) or shared SKILL.md when using cross-tool skills.
  • Codex CLI: the directory configured in your codex.toml.
  • Custom paths: any tool that reads SKILL.md will pick the file up wherever you place it, as long as it's reachable from the agent's working directory.

Writing a good SKILL.md

  • Trigger-driven descriptions. The first line the model sees is the description. Lead with when to use this skill, not what it does.
  • One job per skill. A code-review skill should not also deploy. Composition handles chaining.
  • Numbered steps. AI models follow checklists more reliably than prose paragraphs.
  • Explicit failure modes. Tell the model what to do when something can't be verified ("if no tests exist, flag it instead of writing one").
  • Keep it short. Sub-1,000 words is the sweet spot. Longer skills crowd context. Split into multiple skills if needed.

Publishing your SKILL.md

Once you've written a SKILL.md, you can publish it on skills-hub.ai to make it installable in one command and discoverable via search, MCP, and the leaderboard. Publishing is free, requires only a GitHub login, and includes automatic security scanning and quality scoring.

Publish a SKILL.md →