What are agent skills? The SKILL.md format, explained
By the maintainers of the 1153-skill PM Skills library · Updated 2026-07-26
What are agent skills?
Agent skills are plain-markdown instruction files — conventionally named SKILL.md — that teach an AI assistant to perform one task to a professional standard. A skill contains a name, a description that tells the assistant when to activate, and a body with the working method: required inputs, decision rules, an output template, quality checks, and anti-patterns. The assistant loads it on demand and applies the judgment it encodes.
The idea shipped with Anthropic's Claude (Claude Code and Claude.ai read skills natively), but the format is just markdown — any assistant that accepts system instructions can use one. Our library maintains 1153 of them under MIT, which is where the numbers and examples on this page come from.
What does a SKILL.md file contain?
A SKILL.md file has two parts: YAML frontmatter holding the skill's name and an activation description, and a markdown body holding the working framework — required inputs, the method or scoring rules, a concrete output template, quality checks, and anti-patterns. Well-formed skills are self-contained: one file, no runtime, readable by the model and by humans.
---
name: lease-decoder
description: "Decode a residential lease into plain English and rank the
clauses that can hurt you. Use when someone asks 'what am I signing'…"
---
## Framework: Severity Scale
- 🔴 Can cost you real money — auto-renewal into a full new term…
## Quality Checks
## Anti-Patterns
How are skills different from prompts?
A prompt is a one-off message; a skill is a reusable, versioned file that activates itself when the task matches its description. Skills separate the method — checked into the file, reviewable, improvable by pull request — from the request, which is whatever you type. That separation is what makes output quality repeatable instead of dependent on remembering the right magic words.
| Prompt | Skill |
|---|
| Lives | in chat history | in a versioned file |
| Activates | when you paste it | when the task matches its description |
| Improves | per person, invisibly | by PR, for everyone |
| Auditable | no | yes — read the file |
How do skills work in Claude, ChatGPT, and other tools?
Claude Code and Claude.ai load SKILL.md files natively and activate them by description. ChatGPT and Gemini use the same content pasted as custom instructions or a GPT's system prompt. Cursor, Windsurf, and similar tools consume skills as rules files. Assistants can also fetch skills on demand over MCP, so nothing needs installing at all.
This library ships pre-converted exports for 12 tools plus a hosted MCP endpoint, so the same skill runs everywhere.
Are agent skills safe to install?
A skill is inert text until an assistant reads it — but text can carry prompt injection, data-exfiltration instructions, or invisible Unicode, so treat skills like dependencies. Read before installing, prefer libraries that publish a security scan, and check any individual file with a scanner. Installing copies files; uninstalling deletes them; no code executes on its own.
Two free tools from this project: the skill-vetting skill (a human checklist) and SkillScan (the automated pattern scan, free for any public SKILL.md).
What makes a skill good?
Good skills encode judgment the model lacks, not structure it already produces: severity scales with dollar consequences, decision rules with thresholds, anti-patterns naming real failure modes. Our benchmark found frontier models score near-ceiling on generic document structure — a skill earns its place by adding the parts a senior professional knows and a model guesses.
The SkillSpec standard formalises this as conformance levels L1–L3; the finding about structure comes from the SkillBench technical report, negative results included.
▶ Try 1153 skills in the playground · browse the catalog · GitHub