Your AI agent doesn't need another prompt. It needs a skill.
A prompt is a one-time instruction. You type it, the agent follows it, and by the next session, the entire conversation is gone. You start from zero every time.
A skill is a reusable workflow file that sits in your project. You write it once. The agent loads it every time the task comes up and follows the same defined process, on repeat.
The numbers back this up. SkillsBench, the first peer-reviewed benchmark for agent skills (published February 2026, 84 tasks across 11 domains), found that curated skills raised average agent pass rates by 16.2 percentage points. Self-generated skills, where the agent tried to write its own, showed no reliable improvement at all.
The quality of the skill is the variable. As agents get more capable, the people who know how to write good skills pull further ahead of the people who type instructions into a chat window and hope for the best.
The skill format itself is no longer a single-vendor feature. Anthropic released the Agent Skills specification as an open standard in December 2025 at agentskills.io. Within three months, OpenAI's Codex, Google's Gemini CLI, GitHub Copilot, Cursor, VS Code, and dozens of other tools adopted the same format.
As of mid-2026, over 40 products support the SKILL.md standard. Write a skill once, and it works across every major coding agent without modification.
This guide covers everything: what a skill is, how to write one from scratch, how to avoid the security traps in community-shared skills, and what changes about your daily work once you start building them.
Save this. You'll reference it all week.
## What a Skill Actually Is
A skill is a folder. Inside it is a file called SKILL.md. That file has two parts: a short header with the skill's name and description (written in YAML), and a body with the actual instructions the agent should follow (written in plain Markdown).
my-skill/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
└── assets/ # Optional: templates, resourcesThe SKILL.md file is the only required component. Everything else is optional and loads only when the agent needs it.
## How Skills Load (Progressive Disclosure)
Your agent doesn't read every installed skill at the start of every session. That would flood its context window and make it dumber. Instead, skills load in three tiers:
Tier 1: Name and description only. When a session starts, the agent reads just the name and one-line description of each installed skill. This costs 30 to 50 tokens per skill. Enough to know what's available without burning through context.
Tier 2: Full instructions. When the agent decides a skill is relevant to the current task, it pulls the full SKILL.md body into context. Now it has the complete workflow.
Tier 3: Reference files. If the instructions reference external files (scripts, templates, documentation), the agent loads those only when it reaches the step that needs them.
This three-tier system is why you can install dozens of skills without slowing down your agent. It loads the minimum it needs when it needs it.
Generated by Thread Navigator
Press ⌘ + S to quick-export