context-efficiency

name	context-efficiency
description	How to write token-efficient CLAUDE.md, rules, and skills. Use when creating or editing always-loaded content (CLAUDE.md, .claude/rules/) or authoring skills. Covers the context loading hierarchy, evergreen content principles, and platform limits.
user-invocable	false

Context Efficiency

Always-loaded content (CLAUDE.md, rules without paths) is paid on every prompt, even when irrelevant. Every token spent here is a token taken from working context. Write always-loaded content as pointers, not content.

Context Loading Hierarchy

Layer	When loaded	What belongs here
CLAUDE.md	Every prompt	Orient + link. Under 200 lines (official limit).
Rules (no paths)	Every prompt	Short guardrails. One topic per file. Invoke a skill for detail.
Rules (with paths)	On demand	Scoped guidance that only matters for specific file types.
Skills (descriptions)	Every prompt	One-line descriptions. 2% of context window for ALL combined.
Skills (full content)	When invoked	Full behavioral detail. Under 500 lines per skill.
Wiki	When read	Complete project knowledge. Unlimited but we budget 20K tokens.

Platform Limits

• CLAUDE.md: under 200 lines. "Bloated files cause Claude to ignore your actual instructions."
• Skill descriptions: 2% of context window for all skills combined (16K char fallback). Override with SLASH_COMMAND_TOOL_CHAR_BUDGET.
• SKILL.md: under 500 lines. Move detail to supporting files.
• Auto memory: first 200 lines of MEMORY.md loaded. Topic files on demand.
• Overhead: a meaningful share of the context window is consumed by system prompt, tool definitions, and autocompact buffer before you type anything. The exact percentage depends on which MCP servers and tools are loaded. Run /context-audit to see the current breakdown.

Evergreen Content

Always-loaded content MUST be evergreen, true regardless of when it's read. MUST NOT contain:

• File counts or lists: "12 skills" becomes wrong the next commit. Say "check ls plugins/simpleapps/skills/" instead.
• Version numbers: "currently v2026.03.8" is stale immediately. Point to the VERSION file.
• Process data: timestamps, recent activity, who did what. That's git history.
• Hardcoded paths that change across machines or environments.
• Content that duplicates the code: the code is the source of truth. Describe the pattern, link to the file.

Instead: describe the pattern, give 1-2 examples, and link to the source for the current state.

The Pointer Pattern

Always-loaded files SHOULD be pointers that invoke on-demand content:

# Git Safety (rule, 3 lines, always loaded)
MUST NOT commit without user approval.
Load Skill("git-safety") for full guardrails.

The rule costs ~40 tokens per prompt. The skill costs nothing until invoked, then loads ~800 tokens of detailed guidance. This is 20x more efficient than putting the full content in the rule.

Wiki Links: Highest-ROI Pointer

The cheapest pointer with the biggest payoff is a wiki link in CLAUDE.md. A link like [Deployment](../../wiki/Deployment.md) costs ~15 tokens but gives the agent instant access to a full page of detailed knowledge (~500-2000 tokens) on demand. CLAUDE.md SHOULD link to every wiki content page; it becomes the agent's table of contents. Missing a link means the agent must guess where to find information or ask the user.

When to Use Each Layer

Question	Answer
Does the agent need this on EVERY prompt?	CLAUDE.md or rule
Is it a critical guardrail?	Rule (invokes skill for detail)
Is it only relevant for certain files?	Rule with paths frontmatter
Is it detailed behavioral guidance?	Skill
Is it shared knowledge across projects?	Wiki
Is it personal to one user?	Memory

Navigator Tables (SKILL.md)

A lean SKILL.md keeps the description, the always-true gate, and a navigator that routes to supporting files for conditional detail. Every navigator row MUST carry WHEN (the trigger situation) and WHY (the payoff, or the failure it prevents) — not just a topic-to-file mapping. A bare | Topic | File | table says which files exist but not whether the agent is in the situation that needs one, so it loads nothing (and misses the detail) or everything (defeating progressive disclosure).

Before — bare, don't:

Topic	File
Auth	auth.md

After — carries WHEN/WHY, do:

When you're…	Load	Why
adding a login/session flow	auth.md	token-refresh edge cases live here; skipping it ships the 401 retry loop

Rationale: better routing decisions, a lean SKILL.md, and a cheap forced load where a PreToolUse skill-gating hook forces Skill('X') on a matching file touch — the leaner the SKILL.md, the cheaper every forced load.

Checking Your Budget

Run /context-audit to see current token usage by category. Watch for:

• Skills being excluded (descriptions exceeded 2% budget)
• CLAUDE.md consuming more than ~5% of context
• Many MCP servers inflating tool definitions