Most of the AI tooling I test ends up abandoned after a week. Claude skills are one of the few things that stuck, and they are also one of the most misunderstood features in the ecosystem. So I am starting a series about them: every post covers one skill I have actually tested on my own projects, with real examples, what worked, what broke, and an honest verdict.
This first post covers the foundation: what a skill actually is and why the design is smarter than it looks.
What a skill actually is
A skill is just a folder with a SKILL.md file inside. No SDK, no build step, no configuration format to learn:
my-skill/
├── SKILL.md # instructions + metadata
├── reference.md # optional: extra docs loaded on demand
└── scripts/
└── helper.py # optional: code Claude runs instead of reading
The SKILL.md starts with a small YAML header and then plain markdown instructions:
---
name: k8s-debug
description: Systematic debugging for Kubernetes workloads.
Use when pods crash, deployments fail or services are unreachable.
---
# Kubernetes debugging
1. Check pod status and recent events first
2. Read container logs before changing anything
...
That is the whole format. The instructions are for the model, not for a runtime: you are writing the procedure you would give a new team member.
The clever part: progressive disclosure
The obvious question is context. If you install 30 skills, does Claude carry 30 documents around in every conversation?
No, and this is the part that makes skills work in practice. At the start of a session Claude only sees the name and description of each installed skill, a few dozen tokens per skill. The full SKILL.md is loaded only when the task matches the description. Extra files like reference.md are loaded even later, only if the skill's own instructions point to them. Bundled scripts are executed, not read, so a 500-line helper costs almost nothing.
In other words: the description field is the API. A vague description means the skill never triggers, or triggers when it should not. When I review skills in this series, the description quality is one of the first things I look at, because it decides whether the skill fires at all.
Skills are not MCP servers
The two get mixed up constantly, and they solve different problems:
| MCP servers | Skills | |
|---|---|---|
| What they add | Connections: APIs, databases, tools | Knowledge: procedures, conventions, expertise |
| Runtime | A running process speaking the MCP protocol | A folder of markdown and scripts |
| Cost when idle | Tool definitions in context | Name plus one description line |
They compose well. An MCP server gives Claude access to your invoicing API; a skill teaches it your company's rules about when and how to issue credit notes. I build both, and in my experience the skill is usually the missing half: teams wire up the connection and then wonder why the agent still behaves like it started yesterday.
Where skills live
In Claude Code, personal skills go in ~/.claude/skills/ and follow you across projects. Project skills go in .claude/skills/ inside the repo, checked into git, so the whole team shares them. Skills also ship inside plugins, and the same format works in the Claude apps and through the API, so a skill you write for your terminal can run in an automated pipeline unchanged.
That portability is why I think skills matter beyond the hype: they are the first practical format for packaging operational knowledge for an agent that does not depend on one vendor surface.
How this series works
Each review follows the same structure, so you can compare skills across posts:
- What it claims to do, in one paragraph
- Setup, with the exact commands
- A real test on one of my projects, not a toy example
- Where it broke, because something always breaks
- Verdict: keep, adapt or skip
I run everything on my own setup: a K3s homelab cluster, real repositories, and the agents and MCP servers I use for client work. If a skill only works in a demo, that counts as a fail.
New reviews land here first and go out to the newsletter below. If there is a skill you want tested, send it my way: hello@pablodelarco.com.