The Repeated-Instructions Problem

The prompt you paste every single session

Most Claude Code users have a list. A code-review checklist. A commit message format. A deploy sequence they run every Friday. A set of conventions they paste at the start of every new session so Claude remembers how this project works.

The paste-the-same-thing loop wastes seconds every time, but the real cost is subtler: you have to remember which sessions got the context and which did not. A long Friday deploy prompt you forgot to paste means Claude starts guessing. A checklist buried in a chat three sessions ago is gone.

Skills exist specifically for this. A skill is a reusable set of instructions stored in a file. Invoke it once per session — or let Claude invoke it automatically when the topic comes up — and the instructions are in context exactly when needed. Nothing to paste, nothing to forget.

The four configuration layers

Before you build a skill, it helps to understand where it fits in Claude Code's configuration hierarchy. Four layers exist, each with a different purpose:

The critical distinction between CLAUDE.md and skills is when they load. CLAUDE.md content enters context at the start of every session and stays there — every token, every turn. A skill's body only enters context when someone invokes it. A long deploy procedure in CLAUDE.md costs tokens on every session that never touches deployment. The same procedure as a skill costs almost nothing until you type /deploy.

What a skill actually is

A skill is a directory containing a SKILL.md file. The directory name becomes the command you type to invoke it. Everything else in the directory — reference documents, example outputs, helper scripts — is optional supporting material that Claude can load on demand.

The minimal skill looks like this:

~/.claude/skills/
└── commit/
    └── SKILL.md

Typing /commit in any Claude Code session loads the SKILL.md content into the conversation. Claude reads the instructions and follows them. That is the entire mechanism.

The SKILL.md file has two parts: optional YAML frontmatter between --- markers at the top, and the markdown instructions that follow. The frontmatter configures behavior — who can invoke the skill, which tools it can use, whether it runs in a subagent — and the markdown body is what Claude actually reads and acts on.

When to extract a skill from CLAUDE.md

The signal is procedural content. CLAUDE.md should contain facts: the project uses TypeScript strict mode, the API base URL is /api/v2, migrations live in db/migrations/. When a section of CLAUDE.md starts looking like a numbered list of steps — "to deploy: first run tests, then build, then push, then verify" — that section wants to be a skill.

A useful rule of thumb: if you would skip reading a CLAUDE.md section most sessions because it only applies occasionally, that section is a skill candidate. Extract it, create a SKILL.md, remove it from CLAUDE.md, and replace it with a one-line note: "Use /deploy for the deployment procedure." Context gets lighter; the procedure stays complete.

Skills are not the only way to extend Claude

Skills handle reusable instructions. When you need Claude to reach outside its context window and talk to a live system — query a database, read a GitHub issue, search Sentry — that is what MCP servers are for. When you need Claude's behavior to change automatically in response to tool events — run a linter after every file write, log every bash command — that is what hooks are for.

The practical division: if you would write it as a prompt, make it a skill. If you would write it as an API call, make it an MCP server. If you would write it as a shell command triggered by an event, make it a hook.