Stop Agent Context Bloat: The Context Cartographer Skill
September 18, 2026
Terminal coding agents often load too many irrelevant files, waste tokens, rely on stale documentation, and start editing before criteria are clear. Context Cartographer is a Claude Code skill that uses XML structure to force a task contract and minimum sufficient context before any edit.
What is agent context bloat?
An agent with access to your entire repository will often load too many irrelevant files, waste tokens, rely on stale documentation, and start editing code before establishing clear criteria. The result is a bigger context window and a worse answer.
Context Cartographer doesn't rewrite your query. It acts as a strict context-selection protocol that runs before Claude Code begins modifying files, and it uses Anthropic's recommended XML structure to gather the minimum sufficient context with the highest possible signal.
What are the core mechanics?
| Mechanic | What it does | Failure it prevents |
|---|---|---|
| Task contracting | Defines constraints and acceptance criteria in a structured contract before any edit | Editing before the goal is clear |
| Progressive discovery | Queries configuration files (CLAUDE.md, manifests) before scanning deep folders |
Loading irrelevant files and stale documentation |
| Separation of concerns | Uses a scratchpad step to divide user facts, repository evidence, and inferences | Assumption-based hallucinations |
| Tool-use minimization | States when to run search and view tools and when to stop and ask a blocking question | Wasted tool calls and token spend |
How does the skill use XML tags?
The skill is written with sections such as objective, constraints, non-goals, workflow instructions, examples, and anti-patterns. Two design choices are worth explaining.
Why XML tags? Modern models follow nested XML tags with high logical adherence compared with standard Markdown headings. Tags also keep the model from conflating instruction boundaries with your local code or repository files.
Why a scratchpad step? Having the agent process its reasoning inside a structured scratchpad before it acts mimics chain-of-thought. It reduces hallucinated file paths by separating what the user said, what the repository shows, and what the agent is only inferring.
What does it do on a real request?
The skill ships with worked examples. For an implementation request such as "implement feature X based on user feedback," the agent:
- Retrieves
CLAUDE.mdto check code conventions. - Locates existing schema files and target directory paths.
- Drafts the task contract with precise acceptance criteria.
- Proposes minimal, targeted edits instead of a broad sweep.
For a debugging request that includes a stack trace, it preserves the stack trace verbatim, identifies the files and line numbers the trace names, inspects local initialization routines, and runs the local build tool to reproduce and verify the fix.
When does it activate?
It applies to non-trivial development, debugging, and code review requests. Its goal is a rigorous task boundary and optimal codebase context before Claude Code modifies files.
How do I install it?
- Download
context-cartographer.md. - Save it as
.claude/skills/context-cartographer/SKILL.mdin your project or in~/.claude/skills/. - Ask Claude Code for a non-trivial change and watch it write the contract first.
More skills are in the GitHub repository.
FAQ
Does this skill rewrite my prompts?
No. It is a context-selection protocol. It governs what the agent reads and when it stops to ask, not how your request is worded.
Why read CLAUDE.md and manifests first?
They are cheap, high-signal files that describe conventions and structure. Reading them before scanning deep folders keeps the agent from loading irrelevant code.
How does the scratchpad reduce hallucination?
It forces a separation between user facts, repository evidence, and inferences, so a guess is never treated as a verified fact.
Is a verification loop worth its token cost?
That is an open trade-off: a detailed loop costs tokens, while agent trial-and-error costs them too. I would like to hear how others weigh it.
Related: Agent Prompt Architecture covers the context budget for the agent's own prompt. This skill was first shared on r/PromptEngineering by u/Parking-Kangaroo-63.