<aside> 🦥

Sources

Equipping agents for the real world with Agent Skills – Anthropic

Agent Skills – Claude Docs

Agent Skills open spec

</aside>

🦥 Sloth's Simple Definition

<aside> 🦥

A Skill is a folder that teaches an agent how to do a specific task. At minimum it's a single SKILL.md file with instructions, plus optional scripts, templates, and reference docs. Think of it as a little playbook the agent picks up only when it's actually needed.

Fun fact: the format was created by Anthropic and released as an open standard, so it's not just a Claude thing.

</aside>

The Magic Trick: Progressive Disclosure

<aside> 🦥

Skills load in 3 layers, so they don't clog the context window:

  1. Name + description (~100 tokens), always visible so the agent knows the skill exists.
  2. Full SKILL.md, loaded only when the agent decides the skill is relevant.
  3. Extra files (scripts, references), loaded only if the task needs them.

This means you can have dozens of skills installed without bloating context. Compare that to MCP, where the whole tool list gets dumped in on every single turn.

</aside>

What a Skill Folder Looks Like

my-skill/
├── SKILL.md        # required: metadata + instructions
├── scripts/        # optional: code the agent can run
├── references/     # optional: deeper docs
└── assets/         # optional: templates, files

The SKILL.md starts with YAML frontmatter (name + description), then plain markdown instructions.

🦥 Skills vs Tools vs MCP

<aside> 🦥

They're not rivals. The best setups use skills + MCP together: skills for know-how, MCP for connecting to apps.

</aside>

How To Make a Good Skill

<aside> 🦥

  1. Walk through the workflow with the agent until you get one successful run.
  2. Ask the agent to write the SKILL.md based on that real run.
  3. When it messes up later, feed the failure back and have it update the skill so the mistake never happens again.

Write descriptions that clearly say when to use the skill, that's what triggers it. 🦥

</aside>