From CLAUDE.md overflow to on-demand knowledge
By now you know the problem with stuffing task-specific knowledge into CLAUDE.md — it loads every session, whether relevant or not. Skills are the solution. A skill is a markdown file that Claude loads only when it detects relevance to the current task or when you explicitly invoke it with a slash command.
The mental model: a skill is a recipe. It describes how to do a specific job — the ingredients, the steps, the techniques. But the recipe does not cook. When a skill loads, its content injects into your current conversation. Claude follows the instructions using the tools and context already available in your session.
Skills live in a required directory structure:
.claude/skills/<skill-name>/
├── SKILL.md # Required — main instructions
├── reference.md # Optional — detailed reference docs
├── examples.md # Optional — usage examples
└── scripts/
└── helper.sh # Optional — executable scriptsThe SKILL.md is the entry point. Supporting files like reference docs and examples load on-demand when Claude needs them — they do not consume tokens at startup.
Skills exist at three scopes:
- Project:
.claude/skills/— available in this project, version-controlled with your code - Personal:
~/.claude/skills/— available in all your projects - Enterprise: managed settings — deployed by organisation admins
