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.

See SKILL.md in action

code-reviewer

Free

Run a structured code review on your recent changes without waiting for a teammate. This skill checks for security vulnerabilities (SQL injection, XSS, authentication bypasses), logic errors, edge cases, performance issues, and style violations.Findings are organized by severity: Critical, Warning, and Suggestion. Each finding includes the file, line number, a description of the issue, and a concrete fix. Use it as a first pass before peer review, or as your only reviewer on solo projects.

Get this skill

git-commit-writer

Free

Stop writing vague commit messages. This skill reads your actual staged diff and generates precise, informative commit messages following the Conventional Commits specification. It detects the commit type (feat, fix, refactor, docs, chore, etc.), identifies the scope from the changed files, flags breaking changes, and suggests splitting commits when multiple logical changes are staged. Works with any git repository.`

Get this skill

designing-hybrid-context-layers

$10

What This Skill DoesMost RAG systems fail silently — not because the model is weak, but because the retrieval architecture assumes every query is a lookup. This skill teaches you to design hybrid context layers that match the retrieval strategy to the query type, so your agent gets the right kind of context every time.Problems It SolvesThe RAG-for-everything trap — routing relational and temporal queries through vector search causes silent structural failure, expensive reranking, and answers that get worse as you add more context.Multi-hop blindness — "Which teams own services that depend on the deprecated API?" is an entity-traversal query, not a lookup. Vector RAG cannot answer it accurately.Missing organizational causation — questions like "What decisions led to this incident?" require a temporal event graph, not a document chunk.Context-reasoning mismatch — good context routed to a weak reasoning tier, or long context with no causal structure, produces hallucinations at scale.What You GetThe skill defines a three-layer context model:Layer 1 — Factual Store (Vector RAG): Single-fact, single-document point queries — the only case where RAG is structurally correct.Layer 2 — Relational Store (Knowledge Graph): Entity relationships, dependency chains, and multi-hop queries that require traversal across linked nodes.Layer 3 — Temporal/Episodic Store (Timeline Index): Event sequences, causal decision chains, and "how did we get here" queries that require timestamped structure.You also get a query router decision tree — a concrete classification step that routes every incoming query to the correct layer before any retrieval begins, plus a phased implementation roadmap for teams migrating from RAG-only systems.Who Should Use ThisTeams building AI agents over enterprise knowledge bases, architecture decision records, incident histories, or any organizational system where the agent must answer relational or causal questions — not just fact lookups.

Get this skill

Browse all 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.