16. Token and Context Optimization

16.1 The goal

Token optimization is not simply:

Use fewer tokens.

A better goal is:

Use the smallest amount of relevant context that allows the model to perform the task reliably.

16.2 Bad context

User request
+
Entire repository
+
Old logs
+
All documentation
+
Unrelated files
+
Duplicate instructions

16.3 Focused context

User request
+
AGENTS.md
+
Relevant skill
+
Relevant files
+
Relevant tests
+
Current error

16.4 Use project instructions

Stable rules belong in AGENTS.md.

Examples:

Run pytest after backend changes.
Use the existing database abstraction.
Do not edit generated files.

Do not repeat these rules in every prompt.

16.5 Use skills

Specialized procedures belong in skills.

API testing procedure
Security review procedure
Release procedure

Load them when relevant.

16.6 Avoid duplicated context

If the same 500-line document is repeated in multiple prompts, you are wasting context.

Instead:

Store stable guidance
       |
       v
Reference/load when needed

16.7 Tool output discipline

Tool output can become very large.

Prefer:

Relevant error
Relevant files
Relevant command output

instead of:

Entire 20-minute build log

16.8 Model routing

Use an appropriate model for the task.

A simple documentation change may not need the same model configuration as a complex architecture problem.

16.9 Measure

Track:

• Time to completion
• Number of model turns
• Token usage
• Tool calls
• Test failures
• Rework
• Final quality

Optimization without measurement is guesswork.

Exercise

Take one large prompt from your project and rewrite it using:

1. AGENTS.md
2. A skill
3. Relevant files only
4. Explicit verification