context-optimization

name	context-optimization
version	1.0.0
owner	swarmery-core
description	Use this skill when a task spans 3+ files or crosses repo boundaries and context usage must be managed. Don't use it for single-file edits or read-only queries.
disable-model-invocation	true
allowed-tools	Read, Grep, Glob
color	teal
docs	{"status":"reviewed","source_sha":"9d0a19d62c88","updated":"2026-08-06T00:00:00.000Z"}

Purpose

Minimize context window consumption during multi-file and cross-repo tasks by using targeted reads, codebase-retrieval-first discovery, and incremental loading. This skill does not perform code changes itself; it governs how the agent loads information before skills like code-quality, api-integration, or deployment do their work.

When to use this skill

• Trigger A -- Task touches 3 or more files across any of the project's repos (see .claude/project.json → repos)
• Trigger B -- Task crosses repo boundaries (e.g., the device/edge repo + the main app)
• Trigger C -- Context window usage exceeds 40% of the model's limit and more reads are planned (this is also the threshold at which step 7 delegates isolatable reads to a leaf)

When NOT to use this skill

• Anti-trigger A -- Single-file edit (renaming a variable, fixing a typo)
• Anti-trigger B -- Read-only query about one function or type definition
• Anti-trigger C -- Task estimated under 5 minutes with fewer than 3 files involved
• Anti-trigger D -- Agent is already in a subagent with scoped context (context is already isolated)

Required environment (Runtime: .claude/skills/context-optimization/SKILL.md)

• Tools/libraries: codebase-retrieval, Grep, Read (with offset/limit parameters)

Inputs

• task_description: string -- The user's request or the delegated task summary
• repos_involved: string[] -- List of repos the task may touch (e.g., ["apps/<mainApp>", "<device>"])

Outputs

Format: A structured context plan listing which files to load, in what order, and which sections (line ranges) to target.

Length budget: Max 30 lines for the context plan. The plan is a lightweight index, not a narrative.

Output template:

## Context Plan

**Task:** {one-line summary}
**Repos:** {repo list}
**Estimated files to edit:** {N}

### Phase 1 -- {description}
| # | Repo | File | Offset | Limit | Reason |
|---|------|------|--------|-------|--------|
| 1 | apps/<mainApp> | src/lib/telemetry/ws-client.ts | 12 | 35 | WebSocket reconnect logic |
| 2 | apps/<mainApp> | src/app/api/telemetry/stream/route.ts | 1 | 35 | SSE endpoint handler |

/clear before Phase 2: {yes|no} -- {reason}

### Phase 2 -- {description}
| # | Repo | File | Offset | Limit | Reason |
|---|------|------|--------|-------|--------|
| 3 | <device> | src/telemetry/sender.py | 20 | 40 | Telemetry sender |

### Budget
Files loaded: {N} / Files to edit: {M} (ratio: {N}:{M})
Confidence: {HIGH|MEDIUM|LOW} -- {rationale}

Procedure

1. Identify repos -- From the task description, determine which of the project's repos are involved (list them from .claude/project.json → repos and device). Map each repo to its language and search glob, e.g.:

   Repo (example)	Language	Search glob
   apps/<mainApp>	TypeScript	*.ts, *.tsx
   <device> (device/edge repo)	Python	*.py
   infrastructure repo	YAML/service config	*.yaml, *.yml, *.tpl
   CI/CD config	YAML/Shell	*.yaml, *.sh
   versions/config repo	YAML/JSON	*.yaml, *.json

   Checkpoint: Repos identified; proceed only if task touches files in at least one repo.

2. Discovery via codebase-retrieval -- Run codebase-retrieval with a focused query describing the symbols, patterns, or data flow relevant to the task. Do NOT read full files first.

   Confidence gate: If the returned results do not reference any of the repos or symbols mentioned in task_description, rate confidence as LOW and stop: "codebase-retrieval returned results that do not appear relevant to [task]. Narrow the task scope or specify which repo to search."

   Checkpoint: codebase-retrieval returned at least one relevant result with HIGH or MEDIUM confidence.

3. Targeted reads -- For each file identified, read only the relevant section using offset/limit (read at most 200 lines per file unless targeting a known function that spans more). Prefer reading imports + the specific function over loading the entire module.

   Checkpoint: Each read used offset/limit, not full-file reads.

4. Incremental loading -- If the task spans multiple phases (e.g., understand structure, then implement, then test), load only the files needed for the current phase. After completing a phase that loaded files no longer needed, suggest /clear before the next phase.

Self-check before returning

• codebase-retrieval was called before any full-file reads
• No file was loaded in its entirety when only a specific function was needed (used offset/limit)
• Files loaded count is no more than 3x files actually edited
• /clear was suggested if switching between repos
• Context window usage stayed below 50% of model limit throughout the task
• Context plan follows the structured output template (not free-form reasoning)
• Confidence gate was applied after codebase-retrieval
• At >=40% window usage, every isolatable read (digest output) was delegated to a leaf subagent per the step-7 decision rule -- not loaded into main -- and kept at depth-1

Common mistakes to avoid

• DO NOT read 4+ full files upfront before understanding the task structure -- use codebase-retrieval first
• DO NOT keep files from a previous repo loaded when switching to a different repo
• DO NOT /clear mid-task without ensuring the agent has saved its plan or partial progress
• DO NOT assume context window is 200K tokens -- it varies by model; check the model's actual limit from the system prompt
• DO NOT load test files alongside implementation files unless the task specifically involves writing tests

What to surface to the user

• The structured context plan listing files to load and why each is needed
• A /clear suggestion with rationale when switching repos or when context exceeds 40%
• Subagent recommendation when task spans 3+ repos with independent workstreams
• A leaf-subagent-isolation recommendation when main is at >=40% window and a phase needs a large read whose output is only a summary (step-7 decision rule; keep at depth-1: orchestrator -> leaf)
• The confidence level from codebase-retrieval results

Escalation

• Stop and ask when: Task scope is ambiguous and it is unclear which repos are involved
• Stop and ask when: codebase-retrieval returns no relevant results for the described task (the task may be mis-scoped)
• Stop and ask when: Context window exceeds 60% and more files still need to be loaded
• Stop and ask when: Confidence is LOW after codebase-retrieval -- do not proceed with an unreliable context plan

Examples

Context plan produced:

## Context Plan

**Task:** Fix telemetry latency between the device/edge repo and the main app
**Repos:** apps/<mainApp>, <device>
**Estimated files to edit:** 1

### Phase 1 -- Understand the data flow (main-app side)
| # | Repo | File | Offset | Limit | Reason |
|---|------|------|--------|-------|--------|
| 1 | apps/<mainApp> | src/lib/telemetry/ws-client.ts | 12 | 35 | WebSocket reconnect logic |
| 2 | apps/<mainApp> | src/app/api/telemetry/stream/route.ts | 1 | 35 | SSE endpoint handler |

/clear before Phase 2: yes -- switching from the main app to the device/edge repo

### Phase 2 -- Check the device firmware side
| # | Repo | File | Offset | Limit | Reason |
|---|------|------|--------|-------|--------|
| 3 | <device> | src/telemetry/sender.py | 20 | 40 | Telemetry sender |

### Budget
Files loaded: 3 / Files to edit: 1 (ratio: 3:1)
Confidence: HIGH -- codebase-retrieval returned exact telemetry files

Result: 3 files loaded, 1 file edited. Ratio 3:1 (within budget).

Failure modes

• Mode: codebase-retrieval returns irrelevant results -- symptom: loaded files do not relate to the task -- detect: agent realizes after reading that the content is unrelated -- fix: refine the query with more specific symbols or file paths; rate confidence as LOW
• Mode: /clear suggested at wrong time -- symptom: agent loses context it still needs -- detect: agent cannot recall previously loaded information -- fix: before /clear, write a brief summary of findings to preserve across the context reset
• Mode: context budget exceeded -- symptom: model starts truncating or losing earlier context -- detect: agent gets confused about previously loaded content -- fix: /clear and reload only the files needed for the remaining work

Related skills

• code-search -- defer to code-search for finding all references to a known identifier; context-optimization governs when and how much to load
• api-integration -- compose with api-integration when the task involves understanding the project's API flows across repos
• code-quality -- compose with code-quality after context-optimization has identified the minimal set of files to review

How to use

What it does

This skill plans what to read before you read it. On a task that spans several files or more than one repo, it turns "open everything and hope" into a short, ordered context plan: which files, which line ranges, in what phase, and where to /clear between phases. It does not change code — it governs how information gets loaded so the skills that do the work still have room to think.

When to use it

• The task touches 3 or more files, in one repo or across several.
• The task crosses a repo boundary — for example apps/<mainApp> plus <device>.
• Your context window is already past 40% and more reads are coming.
• You are about to load a large module tree just to extract a verdict or a short list.

When not to use it

• Single-file edits — a rename or a typo fix. Just make the edit.
• A read-only question about one function or type — use code-search instead.
• You are already running as a subagent with scoped context; the isolation you would gain is already there.

How to invoke

Skill(skill: "core:context-optimization")

Invoke it at the start of the task, before any full-file reads. It runs codebase-retrieval first, then hands you a plan of targeted reads to execute.

Inputs

• task_description — the request or delegated task summary — required.
• repos_involved — the repos the task may touch, e.g. ["apps/<mainApp>", "<device>"] — optional; it is inferred from the task and from .claude/project.json when you leave it out.

What you get back

A context plan of at most 30 lines: one table per phase with repo, file, offset, limit and a reason per row; a /clear decision with its rationale at each phase boundary; and a budget line giving files-loaded versus files-to-edit plus a HIGH/MEDIUM/LOW confidence rating. The target ratio is no more than 3 files loaded per file edited. If confidence comes back LOW, the skill stops and asks you to narrow the scope rather than handing you an unreliable plan.

Worked example

Skill(skill: "core:context-optimization")
Task: fix telemetry latency between the device/edge repo and the main app
Repos: apps/<mainApp>, <device>

The plan comes back in two phases. Phase 1 reads two main-app files by line range — the WebSocket reconnect logic and the SSE endpoint handler. It then marks /clear before Phase 2: yes, because the work switches repos. Phase 2 reads one range in the device sender. Budget: 3 files loaded, 1 edited, ratio 3:1, confidence HIGH.

Related

• code-search — prefer it when you already know the identifier and just need every reference.
• code-quality — run it after this skill has narrowed the review to a minimal file set.
• api-integration — compose with it when the task turns on API flows that span repos.