SKILL.md, that contains everything an AI coding agent needs to perform a specific task reliably.
The problem skills solve
AI coding agents like Claude Code, Cursor, and Copilot are powerful but generic. Without specific instructions, they:- Guess at your project’s conventions
- Miss domain-specific requirements
- Produce inconsistent results across sessions
- Cannot learn from corrections
What a skill contains
A skill typically includes:| Section | Purpose |
|---|---|
| Metadata | Name, version, description, tags, target agents |
| Instructions | Step-by-step directions for the task |
| Constraints | Rules and guardrails the agent must follow |
| Verification | How to check that the output is correct |
| Context | Background information, conventions, examples |
| Examples | Sample inputs and expected outputs |
Skills vs. prompts
| Prompt | Skill | |
|---|---|---|
| Format | Free text | Structured Markdown with metadata |
| Persistence | One-off, lives in chat history | Versioned file on disk |
| Reusability | Copy-paste | Install once, use across sessions |
| Quality | Varies | Scored on 6 dimensions |
| Sharing | Screenshots, gists | Export, import, or publish |
Skills across agents
Skills are designed to be agent-agnostic. The same skill can be installed into:- Claude Code via
.claude/skills/files or CLAUDE.md sections - Cursor via
.cursor/skills/files - GitHub Copilot via
.github/copilot-instructions.md - Codex CLI via
AGENTS.md - Gemini CLI via
GEMINI.md - Amp via
.amp/skills/files - Goose via
.goose/skills/files
Skill lifecycle
- Create. Write from scratch, generate with AI, or convert existing docs.
- Edit. Refine instructions, add constraints, include examples.
- Evaluate. Score quality and fix gaps.
- Install. Deploy to one or more agent runtimes.
- Use. Agents follow the skill during coding sessions.
- Patch. Update based on real-world performance.