What are Agent Skills? Understand SKILL.md before installing dozens of them
TL;DR
An Agent Skill is a folder containing SKILL.md (name + description + instructions), optionally with scripts and references. Agents load only the name and description at startup and read the full instructions when a task matches — so you can install many skills without burning context.
Anatomy of a skill
my-skill/
├── SKILL.md # frontmatter: name, description + instructions
├── scripts/ # (optional) runnable code
├── references/ # (optional) docs read on demand
└── assets/ # (optional) templates, images…How skills differ from a long prompt
| Trait | Why it matters |
|---|---|
| Progressive disclosure | At startup the agent reads only name + description (tens of tokens per skill); full instructions load when needed. |
| Open standard | Anthropic released Agent Skills as an open standard in late 2025 (agentskills.io); many tools support it. |
| Easy install | npx skills add <owner/repo>, or copy the folder into ~/.claude/skills/. |
How to put it to work
- Write a precise description: agents decide when to use a skill from its
description— vague descriptions mean the skill never fires. - One job per skill: “write release notes” or “review PRs against our checklist” beats a do-everything skill.
- Read before installing: skills can run scripts and write files. For skills with real side effects (deploys, sending data out), set
disable-model-invocation: trueso they only run when you call them. - PMs / Tech Leads: package team processes (Definition of Done, report templates) as shared skills in the repo.
Further reading: Agent Skills overview (Firecrawl)