The SKILL.md Open Standard — Full Specification

SKILL.md is an open standard for teaching AI coding agents new capabilities. This page is the reference specification.

Quick Answer: SKILL.md defines an open standard for teaching AI coding agents new capabilities, using a SKILL.md file within a skill directory, containing YAML frontmatter for metadata and markdown for instructions.

Overview

A skill is a directory containing a file named SKILL.md. The file uses YAML frontmatter for metadata and markdown for instructions. AI coding agents read the frontmatter to determine when to activate the skill, then follow the markdown instructions when it's active.

Recommended skills

production-agent-architect

by Roy Yuen

Architect, scaffold, and harden production-grade AI agents with battle-tested pa…

$6

Token Budget Officer

by PubsProToolkit

Cost-aware execution planning for AI agents — estimate cost-vs-value before expe…

$19

evaluating-ai-harness-dimensions

by https://loreto.io

Evaluates AI coding agent platforms across five structural dimensions that deter…

$10

Browse all Skillmd skills

File structure

skill-name/
├── SKILL.md           ← Required
├── templates/         ← Optional
├── references/        ← Optional
├── scripts/           ← Optional
└── examples/          ← Optional

The only required file is SKILL.md. Supporting files (templates, reference docs, scripts, examples) are optional and can be organized in any directory structure within the skill folder.

SKILL.md format

---
name: skill-name
description: A sentence describing when this skill should activate.
---

# Skill Title

Instructions for the AI agent.

Frontmatter (required)

The frontmatter block starts and ends with --- on their own lines. It must be the very first content in the file — no whitespace before the opening ---.

Required fields:

Optional fields:

Instruction body (required)

Everything after the frontmatter closing --- is the instruction body. Written in standard markdown. This is what the AI agent reads and follows when the skill is active.

The instruction body should be written as if briefing a senior developer:

• Clear, direct language
• Concrete rules, not vague guidelines
• Examples of desired output when helpful
• Structured with headings for different aspects of the task

Description field

The description is the most important field. It determines when the agent activates the skill. Write it as a sentence describing the task or context that should trigger activation.

Good descriptions:

• "Reviews code for security vulnerabilities, logic errors, and style violations."
• "Generates pytest test files matching existing project test patterns."
• "Writes conventional commit messages from staged git changes."

Bad descriptions:

• "Helps with code" (too vague — matches everything)
• "A really useful skill for developers" (describes the skill, not the trigger)
• "Use this when you want to review Python Flask API endpoints for SQL injection vulnerabilities in PostgreSQL queries" (too narrow — only triggers on exact matches)

Agent compatibility

SKILL.md is supported by:

Skills are portable across all compatible agents without modification. The SKILL.md file is identical regardless of which agent reads it.

Activation behavior

When an agent starts a session, it scans the skills directories and reads the frontmatter from every SKILL.md found. When the user sends a prompt, the agent compares the prompt against each skill's description field. If there's a semantic match, the skill is activated and its instructions are applied.

Multiple skills can activate simultaneously if more than one matches the current task.

Naming conventions

• Skill folder: lowercase with hyphens (code-reviewer, not CodeReviewer)
• File name: exactly SKILL.md (uppercase, case-sensitive)
• Name field: match the folder name

Contributing to the standard

SKILL.md is an open standard. Propose changes through community discussion in the awesome-skill-md repository.

---

Browse skills built on this standard at Agensi.