What is SKILL.md? The open standard extending Claude Code, Cursor, and Codex

If you have spent any time with AI coding assistants, you have probably hit the same wall: you explain your project conventions once, the assistant forgets them the next session, and you explain them again. SKILL.md fixes that. It is an open, plain-text format for packaging reusable AI instructions so any compatible tool can pick them up automatically.

What is a SKILL.md file?

A SKILL.md file is a Markdown document that bundles a self-contained set of instructions for an AI coding assistant. Think of it as a CLAUDE.md or .cursorrules file, but designed to be published, versioned, and shared — more like an npm package than a sticky note.

Each file has two parts:

Frontmatter — YAML metadata at the top of the file: name, version, description, author, and tags.
Instruction body — Plain Markdown text that tells the AI how to behave when the skill is active. This is the content the tool injects into its context window.

Skills are semantic and composable. You can install a "React Server Components" skill, a "Conventional Commits" skill, and a "Postgres with Drizzle" skill at the same time; each one adds its slice of domain knowledge to your assistant without clobbering the others.

Which AI coding tools support Claude Code skills?

SKILL.md is designed as a neutral open standard, and support is growing fast:

Claude Code — Native support. Skills are loaded from ~/.skillhub/ and injected into the CLAUDE.md context hierarchy automatically.
Cursor — Skills map to .cursorrules entries. The Skillhub CLI writes the relevant block on install.
OpenAI Codex — Skills are applied as system-prompt fragments via the Codex CLI config.
Windsurf — Skills integrate with Windsurf's global rules file, giving the same persistent-context benefit.

Because the format is plain Markdown with a small YAML header, any tool that accepts a system prompt or rules file can consume a SKILL.md with minimal glue code.

How to install a skill

The Skillhub CLI makes installation a one-liner:

npx skillhub-install install <name>

For example, to install the popular react-server-components skill:

npx skillhub-install install react-server-components

The CLI fetches the SKILL.md from the Skillhub registry (backed by Cloudflare R2), writes the file to ~/.skillhub/react-server-components.skill.md, updates your local lockfile at ~/.skillhub/lock.json with the resolved semver, and patches your project's CLAUDE.md (or equivalent rules file) to reference the new skill. Every install is also counted in the registry so the community can see which skills are most useful.

You can pin a specific version the same way you would with npm:

npx skillhub-install install react-server-components@2.1.0

How to write a SKILL.md file

Writing a skill is as simple as creating a Markdown file with a YAML frontmatter block. Here is a minimal example:

---
name: conventional-commits
version: 1.0.0
description: Enforce Conventional Commits message format for all git commits.
author: yourhandle
tags: [git, commits, dx]
---

## Commit Messages

Always format commit messages using the Conventional Commits specification:

- Use one of these types: feat, fix, chore, docs, refactor, test, perf, ci.
- Keep the subject line under 72 characters.
- Add a body when the change needs explanation; separate it from the subject with a blank line.
- Reference issue numbers in the footer: `Closes #123`.

Never use generic messages like "fix stuff" or "update".

That is the entire file. The frontmatter gives the registry enough information to index and version the skill; the body is what gets injected into the AI's context. Good skills are specific, opinionated, and short — aim for under 300 words so they do not crowd out other context.

Why the format matters for the ecosystem

Right now, AI coding knowledge is siloed. A Cursor power user's carefully tuned .cursorrules file is invisible to someone using Claude Code, and vice versa. SKILL.md creates a shared layer that sits above any individual tool.

This matters for several reasons:

Portability — Switch tools without losing your team's conventions.
Versioning — Semver means you can pin, upgrade, and roll back AI behavior the same way you manage library dependencies.
Composability — Stack multiple focused skills rather than maintaining one monolithic prompt file.
Community knowledge — Experts can publish battle-tested skills; everyone else benefits without starting from scratch.

The format is intentionally simple so that the barrier to contribution is low. If you know Markdown and have opinions about how an AI should handle, say, error handling in Go or accessibility in React, you can write and publish a skill in under ten minutes.

Explore skills at skillhub.builders

The best way to understand what is possible is to browse what the community has already built. Head to skillhub.builders to search the registry, preview skill content before installing, and publish your own. Whether you are looking for Claude Code skills to tighten up your workflow or want to share the conventions your team has refined over years, Skillhub is where the ecosystem lives.