Ask Knox

A skill is a directory, not a file

The first thing to internalize: a Claude Code skill is not a single file. It's a directory with a required entrypoint and optional companions. The smallest valid skill is one folder with one file:

~/.claude/skills/deploy-prod/
└── SKILL.md

That SKILL.md is the only thing the model reads up front. Everything else in the directory — runbooks, checklists, templates, reference data — is read on demand, and only when SKILL.md explicitly points the model at it. This structure is what lets a skill be both rich and cheap, and it's the through-line of this entire lesson.

Let's take a production skill apart, part by part.

The six parts

1 — Base directory. ~/.claude/skills/deploy-prod/. One folder per skill. The folder name is the skill's identity and its file namespace. Keep it lowercase-kebab and make it match the frontmatter name. When you have forty skills, predictable directory names are how you (and the model) reason about the fleet.

2 — SKILL.md. The entrypoint, and the only file loaded before the skill fires. It holds the frontmatter and the instructions. If a skill is one file, this is the file.

3 — Frontmatter name. The invocation handle. name: deploy-prod. It must match the directory and stay lowercase-kebab. This is the predictable part — it's what /deploy-prod resolves to.

4 — Frontmatter description. This is the load-bearing field, and we'll spend the most time on it both here and in the next lesson. The description is the only thing the model sees when deciding whether to fire the skill. It must carry a WHEN clause and trigger phrases. A perfect body behind a vague description is a skill that never fires. Get this one field wrong and nothing else in the directory matters.

5 — Body. Everything after the frontmatter: the steps, the failure-mode guards, the verification gate, the WHEN-NOT-TO-USE counters. The body is loaded only after the skill fires — which is the first hint of progressive disclosure.

6 — Supporting files. Optional companions in the directory: runbook.md, checklist.sh, template.json, reference data. Referenced from SKILL.md by relative path, and read on demand. They cost zero tokens until a step actually needs them.

Progressive disclosure: rich and cheap at once

Here is the mechanism that makes the six-part structure work. The model does not read your whole skill all the time. It reads exactly as much as it needs, in three layers, and the cost narrows as the detail deepens.

The funnel shape is the whole point:

Always loaded — the name and description frontmatter, roughly thirty tokens. Present in every session, before any skill fires. You pay for this constantly, so it has to be tight.
Loaded on fire — the SKILL.md body. A few hundred tokens of steps, guards, and the verification gate. Read only once the model decides to invoke the skill. You pay for this only when the skill actually runs.
Loaded on demand — supporting files. Zero tokens until a step explicitly points the model at one. A 400-line runbook in runbook.md costs nothing in the ninety-nine sessions where the skill doesn't need it.

This is why pasting a long runbook into SKILL.md is a mistake even though it "works." Body content loads every time the skill fires, and most of that runbook is reference material the model only occasionally needs. Push it into a supporting file and reference it:

## When a deploy fails
For the full rollback sequence, read ./runbook.md and follow the
"Rollback" section. Do not improvise — the order matters.

Now the runbook is there when needed and free when it isn't. The skill is rich (it has a complete rollback procedure) and cheap (you don't pay for it constantly).

Putting the parts together

Here's a compact but complete production skill that uses all six parts correctly:

~/.claude/skills/deploy-prod/
├── SKILL.md          # entrypoint: frontmatter + steps + gate
└── runbook.md        # supporting file: rollback procedure

<!-- ~/.claude/skills/deploy-prod/SKILL.md -->
---
name: deploy-prod
description: >-
  Deploy a backend or cron fix to the production runtime, end-to-end.
  Use when shipping a backend change after a PR merges to main.
  Triggers: deploy to prod, ship to production, redeploy backend.
---

## Steps
1. Host-check FIRST: confirm you are acting on the production host, not a local shadow stack.
2. On the production host: pull the merged branch, rebuild the service.
3. If anything fails mid-deploy, read ./runbook.md and follow Rollback.

## Verification gate
curl the production URL and confirm the NEW response shape, AND confirm
the service is actually running. If the gate fails, the deploy is NOT done.

## WHEN NOT TO USE
- NOT from a local-only stack. The host-check exists for exactly this.
- NOT for frontend-only changes that auto-deploy.

Every part earns its place. The name matches the directory. The description carries the WHEN clause and triggers so the skill fires proactively. The body holds the steps and a hard gate. The rollback detail lives in runbook.md, loaded only when a deploy fails. And the WHEN-NOT-TO-USE block keeps the skill from firing on cases it shouldn't touch — which is the focus of the next lesson.

Build it: assemble a real SKILL.md

Now you'll write a complete SKILL.md for a skill that runs the project's test suite and reports coverage — using every part correctly. The trap to avoid is the one this lesson warned about: don't paste a long checklist into the body when it belongs in a supporting file, and don't let the description go vague to save words. Tight description, disciplined body, supporting file referenced by relative path.

What's next