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.
The community is sharing thousands of "skills" for AI agents, and many people install dozens without understanding what's inside. An Agent Skill is really just a folder containing a SKILL.md file (name + description + instructions), optionally with scripts and reference documents. Understanding this mechanism helps you write good skills, install skills safely and avoid bloating your context.
Anatomy of a skill
my-skill/
├── SKILL.md # frontmatter: name, description + instructions
├── scripts/ # (optional) runnable code
├── references/ # (optional) docs read when needed
└── assets/ # (optional) templates, images…---
name: release-notes
description: Writes release notes from the list of merged PRs, using the team's template. Use when the user asks for release notes or a changelog.
---
# How to
1. Get the list of PRs from ...
2. Group them into Added / Changed / Fixed ...How is a skill different from a long prompt?
| Property | Meaning |
|---|---|
| Progressive disclosure | At startup the agent only reads name + description (a few dozen tokens per skill); full instructions load only when needed, and reference docs are only read when the instructions point to them. |
| Open standard | Anthropic published Agent Skills as an open standard in late 2025 (agentskills.io); many tools support it. |
| Quick install | npx skills add <owner/repo>, or copy the folder into ~/.claude/skills/. |
Thanks to layered loading, you can install many skills and still start with a small context. That's very different from cramming all instructions into one prompt or a giant CLAUDE.md.
Skill, CLAUDE.md, MCP: which to use?
| Tool | Use when |
|---|---|
| CLAUDE.md / AGENTS.md | Conventions that always apply to the project (how to build, test, code style), loaded every session |
| Skill | Specialised workflows only needed for matching tasks (writing release notes, reviewing PRs against a checklist) |
| MCP | Connecting external systems (databases, GitHub, Slack) shared across several applications |
Writing a good skill
- The description matters most: the agent decides whether to use a skill based on its
description. State clearly what it does and when to use it; with a vague description the skill is never called. - One skill, one job: "write release notes" or "review PRs against the team checklist" beats one skill that "does everything".
- Include examples: a sample output helps the agent match the format.
- Move long docs into references/ so they only load when needed.
- Test: try 3–5 real requests, including differently phrased ones, and check the skill is called correctly.
Installing someone else's skill: what to check
- Skills can run scripts and write files. Read SKILL.md and the scripts/ folder as you would a PR from a stranger.
- For skills with real effects (deploying, sending data out), set
disable-model-invocation: trueso they only run when you invoke them. - Check whether the skill calls unknown URLs or reads environment variables or key files.
- Prefer sources with a clear history; pin a version (commit) rather than always pulling the latest.
How to apply it
- Dev: start with one small skill for something you repeat every week.
- Tech Lead: put important skills in the repo so the team uses the same version and reviews them like code.
- PM: package team processes (Definition of Done, report templates, release checklists) as shared skills; process knowledge becomes something that runs.