Skill vs Prompt vs CLAUDE.md
Three ways to instruct an agent: prompt (one-shot, in chat), skill (reusable, on-demand), CLAUDE.md (always-on, project-wide). They serve different use cases and have different token costs.
Prompts are post-it notes (one-off), skills are user manuals (look them up when needed), CLAUDE.md is the office handbook (everyone reads it on day one and re-reads every meeting).
Prompts: ad-hoc, no token cost beyond the message itself, not reusable. Use for one-off tasks. Skills: reusable across sessions, only load when invoked, slightly higher friction (need to define and discover). Use for repeated workflows. CLAUDE.md: always loaded into the system prompt for the project, costs tokens on every turn but free on cache hits, must be terse. Use for project-wide rules and invariants.
Decision tree: Will this run more than 3 times? → skill. Should this apply to every message in the project? → CLAUDE.md. Just this once? → prompt. The bad failure mode is putting workflow instructions in CLAUDE.md — every session pays for them, but most sessions don't need them. The opposite failure: putting always-on rules in skills, then forgetting to invoke them. Auth/security/style rules go in CLAUDE.md (always); 'how we ship a release' goes in a skill (on demand); 'help me name this variable' is a prompt.
I think of three layers: prompts for one-off requests, skills for reusable workflows that should be invoked on demand, and CLAUDE.md for always-on project rules. The decision is mostly about frequency × specificity. A code review checklist used on every PR is a skill. A rule like 'always use pnpm' is CLAUDE.md. 'Rename this function' is a prompt. The mistake I see is people stuffing workflow instructions into CLAUDE.md, which costs tokens on every turn even when irrelevant.
Mixing layers. A skill that duplicates CLAUDE.md content; CLAUDE.md that has a step-by-step deploy runbook; a prompt that re-explains the project's conventions. Each layer has a clear job — keep them separated.