Class 8 · 8.4

Skills: a simpler way to add abilities

A lighter answer to MCP's weight. Markdown instructions with optional scripts, loaded intelligently through progressive disclosure — why they feel so clean, how the folder structure works, and where they fall short.

🎯 Goal: understand skills⏱ Read: 10 min🧭 Type: concepts

MCP is powerful but heavy. Skills came later as a lighter, cleaner alternative — and many of us breathed a collective sigh of relief when they arrived. Here's what they are, why they feel so right, and where they fall short.

01What a skill is

A skill is instructions in Markdown — very much like CLAUDE.md, but with three differences that matter: you can have many of them, they're trivially simple to build, and they load into context intelligently. It started as a Claude Code idea and is spreading to other tools.

Many

Like lots of CLAUDE.md

A folder of focused instruction sets, each for a specific job.

Simple

Just files

Markdown plus optional scripts. No process to spawn, no plumbing — anyone can make one.

Efficient

Progressive disclosure

Only a tiny header loads up front; the rest arrives only if the model decides it's relevant.

02Progressive disclosure — the efficiency trick

The fancy name hides a simple idea: don't load everything at once. A skill has three levels, and Claude climbs them only as far as it needs.

Claude reads every skill's metadata (name + description) up front, loads the instructions only when your request matches, and touches resources/scripts only if it decides it needs them.

Scripts: tool-like, but lighter

A skill can include shell/Python scripts Claude may run. It's not a formal tool call with a JSON signature — it just runs the script and reads back the result. Crucially, all that processing stays out of context; only the result returns. Same outcome as a tool, at a higher, simpler level of granularity.

03The "architecture" is just folders

As with much of this world, the implementation is charmingly janky — and that jankiness is the elegance. A skill is literally a folder.

.claude/skills/ — project OR ~/.claude for global

.claude/
└─ skills/
   └─ my-great-skill/
      ├─ SKILL.md        # metadata + instructions (required)
      ├─ reference.md      # level-3 resource, loaded on demand
      └─ scripts/
         └─ do_thing.py    # runnable, result-only

Two placement choices: a project's .claude (applies to that repo) or your home directory's .claude (applies everywhere). Installing a skill is nothing more than copying that folder into place — which means checking it into your repo instantly shares it with the whole team.

SKILL.md — the required shape

---
name: juggling
description: Teaches Claude how to juggle. Use when the user asks to juggle.
---
# Instructions
Freeform guidance, workflows, code snippets… and references to
other files or scripts that form the level-3 resources.

04Why skills feel right — and their two weaknesses

Green

Simple & context-light

No process/plumbing overhead like MCP. Easy to build, trivial to share, efficient by design. For simple use-cases it just fits.

Red

Less power, hazy discovery

No rich function signatures — just scripts with simple inputs. And discovery is even more of a wild west than MCP, with brittle, keyword-matched triggering.

Triggering is a little hand-wavy

Whether a skill fires depends on your wording matching that top metadata section — you have to "hit the bullseye." You can force it with "use," but that's brittle if you don't know the skill's exact name. It's a knack you develop.

The verdict forming across the community

Many of us find skills the more compelling way to equip Claude Code — and suspect they may eventually replace MCP for tools like Claude Code. The honest rule for now: favour skills over MCP, except where MCP is the only option (e.g. Massive for market data) or where a tool ships both (Context7 has skills but still needs its MCP server).

✓ Key takeaways

A skill = Markdown instructions (+ optional scripts); you can have many, and they're trivially simple to make.
Progressive disclosure: metadata always loads, instructions load on match, resources/scripts load on demand.
Scripts run out-of-context and return only their result — tool-like, but lighter.
It's all folders under .claude/skills/ (project) or ~/.claude (global); sharing = checking the folder into your repo.
Pros: simple, context-light. Cons: less power than tools, and hazy discovery/triggering. Favour skills over MCP where you can.