improve-agent-token-efficiency

name

improve-agent-token-efficiency

description

Improve custom built AI agent token effiency. The skill reviews existing agent codebase, look for opportunities for improvement based on best practice principals, and implement approved changes. Use this skill whenever a user wants to reduce AI agent token costs, improve token efficiency, or asks for feedbacks on system prompts, tool definitions, or agent graphs, even if they don't explicitly mention cost. This skill applies to any open-source agent development framework (LangGraph, Claude ADK, Strands, CrewAI, OpenAI Agents SDK, Google ADK).

Improve Agent Token Efficiency

Reviews an existing agent, recommends token-efficiency improvements, and — after you approve each change — implements them without altering the agent's behavior.

Pipeline Overview

[User input: code folders/URL]
        │
        ▼
┌─────────────────────────────────────────────┐
│ Phase 1: Understand existing agent          │
| Output: agent_doc.md.                       |
└─────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────┐
│ Phase 1b: Capture baseline run              │
│ (build metrics runner; run original agent   │
│  BEFORE any edits)                          │
│ Output: run_agent_metrics.py,               │
│  baseline_run.json, test_inputs.json        │
└─────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────┐
│ Phase 2: Discover Improvement Opportunities │
│ Output: agent_issues.md                     │
│ Gate: human triages each issue (interactive)│
└─────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────┐
│ Phase 3: Improvement Plan                   │
│ Output: improvement_plan.md                 │
│ Gate: human approves each plan (interactive)│
└─────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────┐
│ Phase 4: Implementation Plan                │
│ Output: implementation_worklist.md          │
└─────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────┐
│ Phase 5: Code implementation                │
│ @[reference/05_code_implementation.md]      │
│ Output: code_change_summary.md              │
└─────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────┐
│ Phase 6: Validation                         │
│ @[reference/06_validation.md]               │
│ (re-run edited agent; compare vs baseline)  │
│ Output: validation_report.md                │
└─────────────────────────────────────────────┘

---

Phase Details

Phase 1: Understand existing agent

Use @01_understand_existing_agent.md:

• Gather key information about the agent
• Output: information about the agent in agent_doc.md file

Phase 1b: Capture baseline

Use the @01b_capture_baseline.md prompt:

• Build a reusable metrics runner (run_agent_metrics.py) and run the original agent on a fixed test input set, recording responses + token usage per model and per test case + turn counts — before any code is edited (must precede Phase 5)
• Output: run_agent_metrics.py, baseline_run.json, test_inputs.json

Phase 2: Discover improvement opportunities

Use @02_discover_improvement_opportunities.md:

• Examine against agent development best practices
• Output: issues about the agent in agent_issues.md file
• Issue triage gate (mandatory, interactive): the skill presents each issue one at a time and the human decides Pursue/Skip before the next — not a single approval at the end; only pursued issues proceed to Phase 3

Phase 3: Improvement planning

Use the @03_improvement_planning.md prompt:

• Generate one improvement plan per pursued issue.
• Plan approval gate (mandatory, interactive, before code): the skill presents each plan one at a time and the human approves/rejects before the next — not a single approval at the end; only approved plans proceed to Phase 4/5. Plans marked Needs functional validation are highlighted for extra scrutiny.
• Output: improvement_plan.md

Phase 4: Implementation planning

Use the @04_implementation_planning.md prompt:

• Based on improvement_plan.md, generate an ordered implementation worklist (planning only — no code generation)
• Output: implementation_worklist.md

Phase 5: Code implementation

Use the @05_code_implementation.md prompt:

• Work implementation_worklist.md top to bottom, one change at a time; revert and flag any change that alters behavior
• Output: modified agent code + code_change_summary.md

Phase 6: Validation

Use the @06_validation.md prompt:

• Reuse the Phase 1b run_agent_metrics.py to re-run the edited agent on the same test_inputs.json, then compare against baseline_run.json on both functionality (still meets the goal/expected output in agent_doc.md) and token/turn counts per model and per test case (did they drop); flag any functional or efficiency regression to the human
• Output: validation_report.md

How to structure your output

1. Quick wins — low-effort, high-impact changes (prompt caching, concise tool definitions, user input caps). Lead with these.
2. Architectural changes — things that require design decisions (restructuring the agent graph, converting sub-agents to tools). Be specific about which nodes to change and why.
3. Model right-sizing — specific suggestions for which nodes could use a different model, with reasoning.

For each recommendation, explain the expected impact and what specifically needs to change. Point to the actual text, node, or configuration that needs work. Be concrete — generic advice is easy to ignore.

If you don't have enough information to assess a particular technique, say so and ask a targeted question rather than skipping it silently.