Coding Agent Optimization

---
name: coding-agent-optimization
description: Use when auditing or tuning a development machine's Claude Code or Codex setup for context, model, subagent, permission, or token efficiency. Analyse local capabilities first and apply only supported reversible changes; route runner-specific details to the linked adapters.
metadata:
  portable: true
  compatible_with:
  - claude-code
  - codex
---

# Coding Agent Optimisation

Analyse one development device, then tune its coding-agent configuration to
reduce context waste, unnecessary model spend, unsafe delegation, and repeated
work. Keep the canonical procedure vendor-neutral; use the Codex and Claude
Code adapters only after the local runner and schema have been identified.

## Prerequisites

Load `anti-ai-slop`, `skill-composition-standards`, and
`world-class-engineering` first. Load `skill-safety-audit` before accepting or
applying a new optimisation workflow. After inventory, load only the relevant
adapter: [Codex](references/codex.md) or [Claude Code](references/claude-code.md).

## When this skill applies

- Audit a new Windows, macOS, Linux, WSL, or container-based development device.
- Tune Codex or Claude Code for smaller bounded workers and cleaner contexts.
- Port an agent configuration to another PC without copying unsupported keys or
  model identifiers.
- Review a configuration that appears to consume too many tokens or spawn too
  many workers.
- Prepare a safe, reversible patch for global or project-level agent settings.

Do not use this skill to design an application agent runtime, an in-product
multi-agent protocol, or a provider gateway. Route those tasks to
`ai-agent-runtime-architecture`, `ai-agent-multi-agent-coordination`, or
`ai-model-gateway`.

<!-- dual-compat-start -->
## Use When

- The task is to inspect or optimise a particular device's Claude Code or Codex
  installation, context policy, model selection, delegation, or permissions.
- The user needs a portable, device-specific patch rather than a copied config.

## Do Not Use When

- The task is application-agent architecture, provider gateway design, or a
  generic multi-agent protocol; route to the neighbouring skills named above.

<!-- dual-compat-end -->

## Inputs

| Artifact | Produced by | Required? | Why |
|---|---|---:|---|
| Device capability profile | `scripts/inventory_device.py` or the runner | required | Set safe concurrency and context limits |
| Existing runner configuration | Local inspection | required | Preserve user settings and find supported surfaces |
| User priorities and authority | Request or project rules | required | Decide whether edits, backups, and restarts are allowed |
| Current runner documentation | Official source or local help | conditional | Verify volatile keys, models, and delegation behaviour |

## Outputs

| Artifact | Consumed by | Acceptance condition |
|---|---|---|
| Device assessment | User and future portability work | OS, resources, runners, capabilities, and gaps are evidenced |
| Optimisation plan | Runner adapter | Every proposed edit names its file, reason, and rollback |
| Applied configuration delta | The relevant runner | Only supported, authorised, reviewable changes are made |
| Verification and rollback record | User or operator | Parse/help checks, remaining risks, and restart needs are explicit |

## Capability contract

Require read and search access. Execute the inventory script and runner help or
model-discovery commands when available. Edit only when the user authorises
application; make a timestamped backup before changing a user configuration.
Use network access only for current official documentation when local help is
insufficient. Never read, print, upload, or change authentication files,
tokens, API keys, session databases, or command history.

Without execution, return a bounded assessment and patch plan with checks
marked `not assessed`. Without editing authority, do not claim that changes
were applied. Without a runner interface that can guarantee the selected role,
model, permissions, and fresh context, do not delegate.

## Non-negotiables

- Inspect the actual device and installed runner before choosing settings.
- Preserve unrelated configuration, comments, MCP servers, plugins, skills,
  project trust, and user preferences.
- Never invent a model, context limit, feature flag, agent role, or config key.
- Keep analysis and review workers read-only; grant writes only to a bounded
  implementation role with an exclusive write set.
- Use one worker by default. Parallelise only independent work with disjoint
  scopes, an aggregate cap, and one reconciliation owner.
- Require fresh context for delegated work. If the runner cannot guarantee it,
  keep the work in the primary thread and report the limitation.
- Verify the resulting configuration through the runner, not by checking only
  that a file exists.

## Device policy

Use these as local policy defaults, not as vendor limits. Reduce them when the
device is shared, thermally constrained, rate-limited, or running heavy IDEs,
containers, emulators, or databases.

| Device profile | Signal | Default worker cap | Policy |
|---|---|---:|---|
| Constrained | Fewer than 8 logical CPUs or less than 16 GiB RAM | 1-2 | Prefer one fresh read-only worker; avoid deep parallel work |
| Standard | 8-15 logical CPUs and 16-31 GiB RAM | 2-4 | Permit bounded exploration or one implementation worker |
| High-capacity | At least 16 logical CPUs and 32 GiB RAM | 4-10 | Permit independent parallel work only when the task justifies it |

## Decision rules

| Evidence | Action | Stop or fallback |
|---|---|---|
| Runner and role/model are discoverable and explicitly selectable | Configure the bounded role and verify it | Keep the role unconfigured if selection is indirect |
| Advertised context maximum is known | Set the requested context no higher than that maximum | Preserve the existing value and report the gap |
| Device is constrained or busy | Lower worker concurrency and avoid costly reasoning tiers | Use a single primary run |
| Configuration key is accepted by local help or documented schema | Patch it with a backup | Do not write an unknown key |
| Fresh-context control is exposed by the spawn interface | Set the runner-specific no-history option | Do not spawn if context inheritance cannot be excluded |
| Existing settings contain unrelated user state | Make a narrow patch around the target keys | Stop and ask if the target cannot be isolated |
| Validation fails after the patch | Restore the backup or apply the smallest reversal | Report the failed check and leave evidence |

## Core workflow

1. **Bound the change.** Identify the device, runner(s), scope (global or
   project), user priorities, and whether edits, backups, and restart guidance
   are authorised.
2. **Inventory without secrets.** Run `scripts/inventory_device.py` when
   possible. Record OS, CPU, memory, disk headroom, runner locations, command
   versions, and available configuration surfaces. Do not dump file contents.
3. **Inspect current state.** Read the applicable `AGENTS.md`, `CLAUDE.md`,
   runner config, role files, and model catalogue. Redact or skip credential
   material. Detect dirty or concurrent edits before touching a file.
4. **Choose the smallest safe policy.** Apply the device table and decision
   rules. Prefer context hygiene, bounded workers, least privilege, and
   explicit verification over more parallelism. Load the runner adapter now.
5. **Prepare a reversible delta.** List each file, key, old behaviour, new
   behaviour, reason, evidence, and rollback path. Do not copy a configuration
   from another machine until every model, key, path, and limit is rechecked.
6. **Apply narrowly.** Create a timestamped backup, patch only the approved
   write set, and preserve unrelated settings. Never install packages, change
   firewall or execution policy, alter credentials, or disable safety prompts
   as part of this optimisation.
7. **Verify the live surface.** Parse TOML/JSON/Markdown as applicable, run
   runner help or model discovery, confirm role paths and model availability,
   and inspect the diff. Mark restart or new-thread requirements explicitly.
8. **Hand off evidence.** Report the device tier, changed paths, applied and
   skipped optimisations, verification results, rollback path, and residual
   risks. Distinguish observed facts from inference.

## Optimisation priorities

1. Remove context pollution by keeping durable policy short and routing deep
   procedures to skills or references.
2. Make delegation explicit, bounded, fresh-context, and cheaper than the
   primary model; do not delegate merely because the feature exists.
3. Pin a model only when its availability and quality/cost reason are evidenced
   on this device. Otherwise inherit the runner's supported default.
4. Cap concurrency according to the device and aggregate token budget.
5. Keep read-only review roles read-only and separate implementation write sets.
6. Close completed workers and avoid redoing work while a delegated task runs.

## Anti-patterns

- Copying one PC's config to another without checking the installed version.
  Fix: inventory, compare supported keys, then generate a device-specific delta.
- Raising context or concurrency because a blog post names a larger limit.
  Fix: use the local catalogue or help output and cap at the advertised value.
- Giving every worker the parent's model, permissions, and full context.
  Fix: select a verified smaller role and require fresh context.
- Letting two workers edit the same file without ownership or reconciliation.
  Fix: use disjoint write sets or one worker.
- Treating a successful file write as successful configuration.
  Fix: run parser, help, model, and role-resolution checks.
- Reading auth files to discover a provider installation.
  Fix: use paths, metadata, version commands, and documented diagnostics only.
- Disabling permission prompts or sandboxing to make agents faster.
  Fix: reduce scope, use read-only roles, or request explicit authority.

## Read next

- `ai-agent-multi-agent-coordination` for runtime-level handoffs and conflict
  resolution.
- `ai-agent-governance-and-limits` for aggregate budgets and kill switches.
- `ai-agent-tooling-and-hitl` for action approval and permission boundaries.
- `skill-writing` for canonical skills and thin runner adapters.
- `skill-safety-audit` before accepting high-impact instructions.

## References

- [Codex adapter](references/codex.md) for `config.toml`, `AGENTS.md`, roles,
  model catalogues, and fresh-context checks.
- [Claude Code adapter](references/claude-code.md) for `CLAUDE.md`, settings,
  agents, permissions, and session limits.

## Evidence Produced

| Category | Artifact | Format |
|---|---|---|
| Correctness | Device and runner assessment | JSON plus concise Markdown summary |
| Security | Permission and secret-handling review | Findings with inspected paths |
| Operability | Applied delta and rollback record | File/key diff and backup path |
| Verification | Live runner checks | Commands, results, and unassessed gaps |

## Portable runner rule

The procedure is portable across Claude Code, Codex, and future runners. Keep
provider-specific commands, model identifiers, path conventions, and config
schemas in adapters. Do not turn this skill into a global instruction dump or
claim that a runner supports a control merely because another runner does.