The SKILL.md Universal Standard: How AI Agents Share Reusable Expertise

On December 18, 2025, Anthropic released a spec that quietly changed how AI agents gain new capabilities: SKILL.md. Within weeks, OpenAI, Google, Cursor, JetBrains, and Mistral had adopted it. By 2026, it's a universal standard with 16+ confirmed compatible tools.

Here's why it matters and how to use it.

What SKILL.md Is

SKILL.md is an open standard for giving AI coding agents reusable, on-demand capabilities. The format is simple: a markdown file with a YAML frontmatter header that acts as a trigger, followed by a body that contains the actual instructions.

name: review-pr

description: Reviews pull requests for bugs, security issues, and code quality.

Use when reviewing PRs or code changes.

The description isn't a summary. It's a trigger. When an agent's task matches the description, the skill is loaded. When it doesn't match, the skill costs zero tokens — it doesn't exist in context.

The Progressive Disclosure Pattern

The smart design choice in SKILL.md is progressive disclosure:

Level 1: Agent reads ONLY the name and description (30–50 tokens per skill). This happens every session, for every skill.

Level 2: If the task matches, the agent loads the full SKILL.md body (under 5,000 tokens recommended). Only skills that are relevant to the current task get loaded.

Level 3: If the skill needs scripts or reference files, those are loaded from the file system on demand.

The result: hundreds of skills available to an agent without any context bloat. The agent has access to expertise in code review, data analysis, documentation generation, security auditing — all of it — without any of that expertise consuming context when it's not needed.

Tool Compatibility and Paths

The format is universal. The paths are tool-specific:

The same SKILL.md works in all of them — you just drop the folder in the tool's skills directory.

Skills vs Config Files vs MCP: The Key Distinction

These three complement each other. SKILL.md is for teaching the agent how to do specific tasks. CLAUDE.md is for telling the agent about the project. MCP is for connecting the agent to external systems.

Best Practices

• Write descriptions as TRIGGERS, not summaries. "Reviews PRs for bugs, security issues, and code quality. Use when reviewing PRs or code changes." — this tells the agent when to activate the skill.
• Keep SKILL.md under 500 lines. Above this, context bloat kicks in.
• Keep instructions under 5,000 tokens.
• Use scripts/ for heavy logic — don't put 200-line bash scripts in the SKILL.md body.
• Add a Gotchas section for common failure modes. The agent needs to know what not to do, not just what to do.
• Commit skills to Git for team sharing. Skills are code. Version-control them.

Jason Newell is an AI practitioner, builder, and writer covering agentic systems, developer tooling, and the future of AI engineering.