How to use the Context Optimization agent skill

What the skill makes the agent do

Once installed, the agent follows the skill's guidance when a task is long enough that the context window, or the token cost of each request, becomes a constraint. The skill ranks four strategies by impact and risk: KV-cache optimization first, then observation masking, then compaction, then context partitioning across sub-agents.

In practice this means the agent replaces bulky tool outputs with short references once their purpose is served, keeps stable content such as the system prompt at the start of each prompt so cached content can be reused, summarizes context when utilization exceeds 70%, and suggests partitioning work when estimated context exceeds 60% of the window limit.

• Observation masking: verbose tool outputs become compact references like [Obs:{ref_id} elided. Key: {summary}. Full content retrievable.]
• Prefix ordering: system prompt first, tool definitions next, dynamic content last
• Compaction: summarize and reinitialize at roughly 70% utilization, with target reductions of 50-70%
• Partitioning: split into sub-agents with isolated contexts when a single window cannot hold the problem

Install the context-optimization skill

Download the ZIP from this page and unzip it. The skill folder contains SKILL.md, a references folder and a scripts folder. Put the unzipped folder in one of two places depending on how you want to use it.

For a personal setup available across your projects, place it in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/context-optimization/
• Project only: .claude/skills/context-optimization/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

You do not need a special command. The skill's description tells the agent when to use it, so describe your problem in plain terms. Requests about context budgets, token costs, caching, or long agent runs that are running out of room are the ones it is designed for.

The skill also says when not to act. Explaining how context windows work belongs to a different skill, and diagnosing lost-in-middle or confusion problems belongs to context-degradation. Asking directly for those will not use this skill's guidance.

• "My agent's tool outputs are filling the context window. How should I trim them?"
• "Help me reorder this system prompt so the prefix cache hits more often."
• "Should this multi-file refactor be split across sub-agents, or can one context handle it?"
• "Set a token budget for system prompt, tools, documents, history and a buffer."

Example: masking a long tool output

Suppose an agent ran a search tool three turns ago and the key result is already in the conversation. The skill's rule is to mask observations after three or more turns once their key points have been extracted. Repeated outputs and boilerplate headers can be masked immediately.

The skill keeps the full content retrievable. The agent stores the original outside the prompt and keeps only the reference ID and a short key in context, so it can request the original later if needed.

What you need before using it

The skill itself is guidance written in SKILL.md, but it bundles a Python file, scripts/compaction.py, that helper functions use. That script needs Python 3 and imports only the standard library. You also need an agent runtime that reads SKILL.md files.

The bundled script estimates tokens at roughly 4 characters per token and uses illustrative cache numbers. Its own notes say these must be replaced with real measurements in production. The script does not use the network.

• Python 3 for scripts/compaction.py (standard library only)
• An agent runtime that reads SKILL.md files
• Real token counts and cache metrics from your own stack for production decisions

Safety notes: scripts and network access

The skill runs scripts: scripts/compaction.py provides helper functions for estimating tokens, categorizing messages, and tracking masked observations and cache metrics. Read the file before running it in a sensitive environment, as you would any script you install.

The skill does not use the network. Compaction is lossy: summarizing can drop critical details, so avoid using it on legal or compliance records where every line must be kept.

• The bundled script runs locally and does not use the network.
• Review scripts/compaction.py before executing it.
• Do not apply lossy compaction to legal or compliance records.

Tips for getting good results

Measure before and after. The skill's own principle is that context quality matters more than quantity, so check that answers stay as good after each change. Target figures in the guidance, such as under 5% quality degradation for compaction and under 2% for masking, are goals to verify, not guarantees.

Keep the system prompt stable. Remove timestamps, session counters and request IDs from it, because even a single whitespace change in the prefix invalidates cached content after that point.

• Mask tool outputs first; they can make up 80% or more of tokens according to the guidance.
• Never compact the system prompt.
• Batch edits to earlier history, since each edit invalidates the text that follows it.
• Only partition work when the coordination overhead is smaller than the savings.