Skills are just folders

How to move a long procedure out of CLAUDE.md so it loads only when it is actually needed.

8 min read

Level 0

Curious

0 XP

150 XP to ApprenticeNo streak yet0 badges0% done

A skill is a folder with a SKILL.md inside it. That is the entire technology.

.claude/skills/
└── write-non-listicle/
    └── SKILL.md

The file starts with a small header telling Claude what the skill is for and when to use it. Everything after the header is the instructions.

---
name: write-non-listicle
description: >
  Write a guide, how-to, single-tool review, or A vs B comparison.
  Use when the article covers one topic rather than a ranked list.
---

# Write a non-listicle article

## Before you start
Confirm intake is complete. If the client is unknown, stop and ask.

## Phase 1 – Research
...

The `description` is what Claude reads when deciding whether to load the skill. Write it for that job: say what it does **and when to use it**.

Why not just put it in CLAUDE.md?

Because the writing procedure is about 400 lines, and you only need it when you are writing that kind of article. Loading it every session for every task is wasted attention.

Skills load on demand. CLAUDE.md says "guides use write-non-listicle" in one line, and the 400 lines arrive only when that line matches.

claude

>Write the guide for VOS, keyword "inventory forecasting".

CLAUDE.md routes guides to write-non-listicle. Loading it.

Skillwrite-non-listicleloaded, 9 phases

Phase 1 is research. Pulling the SERP before I outline anything.

The roundup skills, the update skill and the screenshot rules never loaded. They are not relevant, so they cost nothing.

How to know something should be a skill

It is a procedure with steps, not a rule. Rules go in CLAUDE.md.
It only applies to some of your work.
It is long enough that pasting it into chat is annoying.
You have explained it more than twice.

The two-explanations rule

The second time you explain the same procedure in chat, stop and write the skill instead. You are already paying the cost of the file. You are just paying it repeatedly and getting nothing durable back.

Shared instructions go in one place

Three skills in the source system write different kinds of roundups. They share about 70% of their instructions: how to research, how to build the comparison table, how to write each entry.

That shared part lives in one reference file. Each skill reads it, then adds only what makes its own type different.

shared instructions

.claude + references

·references/listicle-shared.mdresearch, entries, tables, screenshots

·skills/write-listicle-best/SKILL.md+ section order only

·skills/write-listicle-alternatives/SKILL.md+ section order only

·skills/write-listicle-examples/SKILL.md+ its own carve-outs

Change how comparison tables work and you edit one file, not three. Three copies of a rule is three chances for them to disagree.

Challenge

Skill, or not a skill?

35 XP+9 perfect

Four things you might want Claude to know. Two of them belong in a skill. Pick both.

Which two should become skills?

Pick 2

Do this now

Create your first skill folder.

mkdir -p .claude/skills/my-procedure
touch .claude/skills/my-procedure/SKILL.md

2
Add the header. The description is the part that matters.
```
---
name: my-procedure
description: >
  What it does. When to use it.
---
```
Claude reads that description to decide whether to load the skill. A vague description means it loads at the wrong times or never.
3
Paste in the procedure you have explained more than twice, then ask Claude to run it.
```
> Use the my-procedure skill on this draft.
```

Finished reading?

Mark it done to bank the XP and keep your streak alive. Any challenges on this page score separately, so you can come back for a perfect run later.