SKILL.md Explained: A Standard Format for Building AI Agent Skills

What Is SKILL.md? A Practical Guide to AI Agent Skills

If you work with AI coding agents, you have probably seen SKILL.md mentioned and wondered what it actually is. In a matter of months it went from one company's feature to a standard adopted across Claude Code, Cursor, Codex CLI, Gemini CLI and more. Here is the plain explanation, with no hype. What a skill actually is A skill is a folder containing a SKILL.md file that teaches an AI agent to do a specific task well. Instead of re-explaining your conventions, your workflow, or your standards every single session, you write them down once. The agent reads them automatically whenever they are relevant. Think of it as the onboarding note you would give a capable colleague taking over a task — except you write it once, and every agent that supports the standard reads it. Why it caught on Before skills, every agent started from zero each session. You re-explained your code review standards, your documentation style, the quirks of your project — over and over. A skill captures that knowledge permanently. And because SKILL.md is a shared format, the same skill works across every agent that supports it. Write once, use everywhere. That combination — solving a real shared problem, simply — is why it spread so fast. The anatomy of a SKILL.md Every SKILL.md has two parts. The frontmatter is YAML metadata between two lines of three dashes. It has two required fields: a name (short, lowercase, hyphenated) and a description (what the skill does and, crucially, when to use it). The body is plain markdown — the actual instructions. The steps, the order, the conventions, the things to check. The frontmatter tells the agent when to use the skill. The body tells it how. The three types of skill Skills range from simple to powerful: Markdown-only skills are pure instructions — conventions and checklists, no code. This is where most people start, and it already covers a huge range of useful tasks. Skills with scripts add shell or Python the agent can run, for tasks that need real execution rather than guidance. API-calling skills reach external services — fetching data, posting updates, integrating tools into the workflow. You do not need to start complex. A markdown-only skill that encodes how you like code reviewed, or commits written, or docs formatted, is genuinely useful on day one. The field that decides everything Of the two required fields, the description matters far more than people expect. The agent decides whether to load a skill by reading its description and matching it against what you asked. Write the description too narrowly and the skill never fires — no matter how good the instructions inside are. The fix is to write the description around the words you would actually type, including the synonyms. Not "Reviews pull requests" but "Reviews code for bugs, style and security. Use when the user asks to review, check, audit or look over code, a pull request, a diff or a file." That one habit prevents most "my skill does not work" problems. The bottom line A skill is a small, durable investment: a markdown file that teaches your agent something, once, and applies it consistently across every agent you use. Start with whatever you explain most often, get the description right, and you will wonder how you worked without it. Free starter: The format, a working template, and the description technique are all on a free cheat sheet: AI Agent Skills Quick-Start Cheat Sheet Go deeper: The full guide covers the complete specification, five build walkthroughs, ten production-ready templates, security, and a 30-day plan: AI Agent Skills: The Complete SKILL.md Standard Guide What is the first skill you would write — the thing you explain to your AI most often? Curious to hear in the comments.

23 hours ago

Building Your First AI Agent Skill: From Markdown to APIs

AI agent skills are easier to build than they look, and they scale from a simple markdown file to something that runs scripts and calls APIs. Here is a practical walkthrough of the whole spectrum, starting from the simplest useful skill. Start simple: a markdown-only skill The simplest skill is a folder with a single SKILL.md inside. No code. Just frontmatter and instructions. code-reviewer/ SKILL.md The SKILL.md has frontmatter (a name and a description) and a markdown body with the instructions. For a code reviewer, the body might be an ordered checklist: check correctness first, then security, then style, then tests, and report findings grouped by severity with the file and line cited. That is a complete, useful skill. Most of the value in skills lives at exactly this level — encoding the conventions you would otherwise repeat every session. Level up: a skill with scripts When a task needs real execution rather than guidance, add scripts to the folder: code-reviewer/ SKILL.md scripts/ check.py The SKILL.md instructs the agent to run the script as part of the task. Now the skill does not just advise — it acts. This is the step from a skill that tells the agent how to think to one that performs a concrete operation. Go further: an API-calling skill The most capable skills reach external services — fetching data, posting updates, integrating a tool into the agent's workflow. Structurally it is still a SKILL.md plus the code to make the calls, but now the skill connects your agent to the outside world. A useful safety note: skills that run commands or call APIs are exactly where you want to be deliberate about scope. Restrict what the skill can touch, review what it does, and treat third-party skills with the same caution you would any code you run. The three steps that never change Regardless of complexity, building a skill is always the same three steps: Create the folder with a SKILL.md inside. Write the frontmatter — name and description. Invest in the description; it decides whether the skill ever fires. Write the body — the instructions, and references to any scripts. Then test it by phrasing real requests and confirming it triggers. Widen the description wherever a natural request misses. Where the value compounds Your first skill is one capability. A library of them — markdown skills for conventions, script skills for operations, API skills for integrations — quietly upgrades every agent you use. Start with a markdown-only skill today, and add complexity only when a task actually needs it. Free starter: The format, a working template, and the description technique are all on a free cheat sheet: AI Agent Skills Quick-Start Cheat Sheet Go deeper: The full guide covers the complete specification, five build walkthroughs, ten production-ready templates, security, and a 30-day plan: AI Agent Skills: The Complete SKILL.md Standard Guide What would your first script-backed skill do? Drop the idea in the comments and I will suggest how to structure it.

23 hours ago