Claude Code Skills: Stop Repeating Yourself, Stop Bloating CLAUDE.md

You keep typing the same instructions into Claude. The same planning steps, the same review checklist, the same "here's how we structure a PR" — every session, from scratch. Or worse, you paste it into CLAUDE.md to stop retyping it, and now CLAUDE.md is growing with things that only apply some of the time.

Skills solve both problems. A Skill is a folder on your machine with a SKILL.md file inside — your workflow instructions, written once. Claude discovers it on its own, based on the task you're describing, and loads it only when it's actually relevant.

The mental model#

CLAUDE.md holds your stable project rules — the stuff that's always true. A Skill is a reusable method — a playbook for one specific kind of job, loaded only when that job comes up. Keep the constitution short. Put the how-to guides in Skills.

How discovery works#

The agent first sees only the name and description of every skill you have — that's it, a few tokens each. Based on your actual request ("help me plan this feature"), it scans those descriptions, finds the match, and only then loads the full SKILL.md. If the skill keeps growing, split it into supporting files — example scripts, references — and only pull those in when the workflow actually needs them. Same principle as Rules: don't load what you don't need yet.

You can also skip discovery and call a skill explicitly from the CLI with /skill-name.

Where skills live#

There's a hierarchy: enterprise-wide (every user in the org gets access), personal (~/.claude/skills, usable across all your projects), project-scoped (.claude/skills inside one repo, this project only), and plugin-level. Most of what you'll build day to day is either personal or project-scoped.

In the video#

00:00 — What a Skill actually is, and why: don't repeat yourself, don't bloat CLAUDE.md
02:59 — The hierarchy: enterprise, personal, project, plugin
04:27 — /skills — listing everything currently available
05:07 — The frontmatter format: name, description, and why the description has to be genuinely specific
07:45 — Watching a skill get auto-discovered and loaded for a real task
08:53 — Building a new skill from scratch (a "cooking" skill, with variable substitution)
10:38 — Refining an existing, oversized skill with Claude Opus and the official docs
13:49 — find skills: installing a skill someone else built (150k installs, one command)

Writing the frontmatter that actually gets discovered#

The metadata at the top of SKILL.md is not decoration — it's the only thing Claude reads before deciding whether to load the rest. Beyond name and description, you can add:

when to use — extra context for exactly which situations should trigger it
model — pin a specific model to this skill (a planning skill benefits from more reasoning power than a boilerplate one)
effort — low, medium, high, or max reasoning effort for whatever runs inside the skill

Get the description vague, and the skill just won't get picked up when it should. This part is worth rewriting a few times.

Splitting an oversized skill#

In the video, an existing "build" skill has grown too large — everything crammed into one SKILL.md. The fix: paste the official Claude Skills documentation into context, point Opus at the oversized skill, and ask it to split things correctly — code templates and workflow details move into separate reference files, the main SKILL.md shrinks down to what actually needs to be there every time.

Because a skill is nothing but a folder of markdown files, you can commit it to git and hand it to your team directly — and if everyone's CLAUDE.md references the same skills, your whole team follows the same workflow automatically, without anyone having to remember the steps by heart.

The other direction works too: find skills is a searchable marketplace built into the CLI. Search for what you need — "a skill to test my frontend," or by name — and install directly into your personal folder. One in the video has 150k installs, built by someone else entirely, doing real work the moment it's installed.

The actual point#

Put your repeated workflow instructions into a Skill, not into CLAUDE.md. If the skill grows, split it into supporting files. Write a description that's actually descriptive, because that's the only thing standing between "the agent finds this automatically" and "you're back to typing it out by hand."