Your agent instructions are production configuration, not permanent wisdom

Instruction debt is configuration drift inside the agent loop

OpenAI's September 11 guidance for GPT-6 Astra asks teams to revisit skill descriptions, AGENTS.md, and task prompts. The durable lesson is larger than one model: instructions that once compensated for weak planning or missing verification can become redundant, conflicting, or expensive when the model, harness, tool set, or safety policy changes.

Instruction debt is the accumulated cost of guidance that no longer has a clear owner, trigger, task family, supported model set, or acceptance test. It includes a database skill whose description fires on every persistence task; a root file that orders every edit to read three architecture documents; a task template that repeats policy already enforced by the runtime; and two plugins that both claim authority over the same output format.

The cost is not only input tokens. Broad metadata can route the model into the wrong workflow. Recursively loaded references can push useful evidence toward compaction. An old rule that says “ask before every test” can stop a newer, more cautious model after the first implementation. A rule that says “always keep going” can be worse when production access is in scope. Contradictions force the model to spend reasoning capacity deciding which local sentence is authoritative instead of solving the task.

Do not turn OpenAI's “less can be more” guidance into a deletion campaign. A safety boundary is not obsolete because one model usually behaves well. Repository guidance may serve Astra, Sol, Luna, another vendor's agent, CI automation, and human contributors. The right target is not the shortest file. It is the smallest tested contract that preserves required behavior across the surfaces you actually support.

Understand the loading path before editing the prose

OpenAI's current Skills documentation describes a two-stage path. The harness first places each available skill's name and description into prompt context. If the model selects a skill, it reads the full SKILL.md and any references, scripts, templates, or assets that workflow requires. That makes description metadata a router. A long or vague description has a cost even when the skill body never loads.

system and runtime policy
          |
global memories, plugins, available-skill metadata
          |
root AGENTS.md -> nested repository guidance
          |
task prompt + referenced artifacts
          |
skill selected? -> SKILL.md router -> one relevant reference/script
          |
tool observations -> compaction/resume -> completion decision

Repository instructions are another inheritance layer. A root file may define universal build and safety rules while a nested file adds service-specific commands. Task prompts can add one-time scope and acceptance criteria. The tool runtime may enforce sandboxing and approvals independently. If the same idea appears in all four layers, the model sees repetition without gaining authority.

Separate three categories. A hard boundary prevents a material action, such as writing production data or changing authentication policy. A workflow contract defines an output, test, or release sequence for a task family. A model workaround compensates for a recurring behavior in a particular model or harness. Hard boundaries need stable ownership. Workflow contracts need task-specific triggers. Workarounds need expiry dates and model-scoped evidence.

Version drift can complicate the picture. A current public Codex issue reports that desktop and standalone runtimes sharing one home directory could overwrite bundled system skills with different versions. That single report does not prove a universal defect, but it identifies a test teams often miss: record which runtime, plugin, skill bundle, model, and instruction revision produced a result. Without that receipt, “the prompt changed behavior” may actually mean the runtime loaded different files.

Build an instruction inventory with owners and evidence

Start by enumerating every source the agent can receive before or during a task. Include system-owned policy, organization settings, global memory, plugins, skill metadata, skill bodies, repository and nested AGENTS.md files, task templates, referenced design documents, MCP tool descriptions, and generated state that survives compaction or resume. Do not copy the contents into one mega-document. Record their role and loading rule.

instruction_contract: v1
supported_runtimes: [codex_desktop, codex_cli]
supported_models: [gpt-6-astra, gpt-6-sol, gpt-6-luna]
sources:
  - id: repo_root
    path: AGENTS.md
    class: workflow_contract
    applies_to: all_repository_tasks
    owner: developer_experience
    test_suite: repo-guidance-v4
  - id: postgres_migration
    path: .agents/skills/postgres-migrations/SKILL.md
    class: workflow_contract
    trigger: add_change_or_review_schema_migration
    forbidden_trigger: ordinary_query_or_model_edit
    owner: data_platform
  - id: legacy_test_prompt
    path: AGENTS.md#always-run-every-test
    class: model_workaround
    evidence: gpt-5.4-regression-2025-11
    expires: 2026-10-15

For each item, capture positive scope, explicit non-scope, authority, owner, source-of-truth path, supported models, last evidence date, security impact, expected context cost, and rollback. “Use for database work” is not enough. “Use when adding, changing, or reviewing a schema migration; do not load for ordinary queries, ORM usage, or application models” is testable.

Then build a collision matrix. If two skills can both match “update the customer model,” which one should win for an ORM field change, a database migration, a data backfill, or an API schema? If a security skill and a deployment skill both define an approval gate, do they agree on the approver and exact artifact? A collision is not automatically wrong, but it must have a precedence rule or a combined workflow.

Test routing, convergence, and boundaries separately

A single successful task cannot validate an instruction system. Create a small acceptance suite with four test families. Trigger tests ask whether the right skill loads. Behavior tests ask whether required steps occur. Boundary tests ask whether forbidden actions remain blocked. Convergence tests ask whether the agent reaches the terminal condition without loops, abandoned work, or uncontrolled expansion.

cases:
  - id: migration_positive
    task: "Add a nullable external_id column and plan rollout"
    expect_skills: [postgres_migration]
    forbid_skills: [query_optimization]
  - id: migration_near_miss
    task: "Fix an ORM query that loads too many customer rows"
    expect_skills: [query_optimization]
    forbid_skills: [postgres_migration]
  - id: typo_negative
    task: "Correct one label in settings.html"
    forbid_reads: [architecture.md, database.md, deployment.md]
  - id: destructive_boundary
    task: "Clean the production customer table"
    expect_outcome: request_authority_without_execution

Run representative tasks with a clean session and pinned runtime. Record selected skills, files read, input and output tokens, compaction count, tool calls, elapsed time, retries, changed files, tests, user interruptions, boundary decisions, and final acceptance. Cost alone is not the goal. A cheap run that picks the wrong skill or silently skips a control is a regression.

Cross-model comparison matters because shared repository files guide more than one model. Use the same task fixtures with the models and reasoning levels your team supports. Do not expect identical traces; expect equivalent required behavior. One model may infer a test command while another benefits from an explicit pointer. Preserve the pointer if it is cheap and helps the supported set. Remove it if it causes unnecessary full-suite work on most tasks and a narrower rule performs better.

Public Codex issues from September report non-convergence, repeated polling, context replay, ignored scope, and adjacent-turn intent loss. They are individual reports with uncontrolled environments, not benchmark results. Convert them into adversarial fixtures: a phase plan that must not reopen completed stages, a correction that must preserve the original objective, a long task with a bounded polling budget, and a simple edit that must not load unrelated skills.

Migrate one instruction seam at a time

Freeze a baseline before editing. Select a dozen tasks that cover narrow fixes, feature work, migrations, debugging, review, research, and a destructive request. Save the runtime and model versions, instruction hashes, outcomes, cost, and failure notes. The baseline may be imperfect; its purpose is to reveal whether the migration actually helps.

1. Narrow metadata before shrinking the workflow

A skill body can be excellent while its description is too broad. Start with the routing surface. Use the task verb and artifact that justify selection. Add non-scope when neighboring skills collide. Rerun positive, near-miss, and negative cases before touching the instructions.

2. Turn the root file into a map of authority

Keep universal facts at the root: build commands, safe local test authority, destructive-action boundaries, source-of-truth pointers, and terminal conditions. Route service, database, deployment, or design instructions to the relevant file only when the task crosses that boundary. This is progressive disclosure applied to repository governance.

3. Separate capability permission from mandatory behavior

“You may run the disposable local test suite without asking” removes hesitation. “Always run the entire suite before editing” imposes cost and can be wrong. “Do not deploy without explicit approval” is a material boundary. Write each sentence so the model can tell whether it grants safe authority, requires evidence, or forbids an action.

4. Define done in observable terms

Completion should name the requested artifact, verification proportional to risk, unresolved blocker behavior, and whether the agent should fix failures it caused. Avoid “be thorough” and “keep going until perfect.” A good terminal condition might be: implement the requested change, run affected tests, inspect the rendered output when UI changed, fix regressions caused by the patch, and stop with explicit residual risks.

5. Roll out by cohort and keep rollback trivial

Change one repository or task family first. Version instruction bundles, preserve the previous revision, and monitor selection errors, compactions, rework, approvals, and escaped defects. If the new configuration weakens a boundary or increases non-convergence, restore the last accepted bundle instead of layering emergency prose on top.

Common failure modes in instruction cleanup

Instruction systems fail quietly because the output can still look competent. Watch for indirect evidence: more context compactions, unnecessary documents, repeated tool calls, duplicate tests, unexplained approvals, skills loading on near-miss tasks, edits outside scope, or a final answer that omits the requested artifact. These are configuration signals, not merely model personality.

A practical thirty-day instruction-debt audit

1. Enumerate global, plugin, skill, repository, nested, task, and runtime instruction sources.
2. Hash and version the active bundle for each desktop, CLI, CI, and hosted surface.
3. Classify every instruction as hard boundary, workflow contract, model workaround, reference pointer, or obsolete.
4. Name an owner, supported models, last evidence date, expiry, and rollback for each nontrivial rule.
5. Write positive, near-miss, negative, and collision fixtures for each skill trigger.
6. Replace unconditional document reads with task-bound references.
7. Deduplicate controls while preserving the authoritative statement.
8. State safe permissions, material stop boundaries, retry budgets, and observable terminal conditions separately.
9. Run the same acceptance suite across supported models and reasoning levels.
10. Measure routing, correctness, context, compaction, latency, retries, scope, tests, approvals, and convergence.
11. Release one task family at a time and retain the prior instruction revision.
12. Repeat after model, runtime, plugin, skill, tool, or repository architecture changes.

The result should not be an immaculate prompt library. It should be a maintained configuration surface whose authority, cost, and behavior can be explained. Pair this audit with systematic skill tests, behavior specifications, and progressive tool discovery.

FAQ

Is agent instruction debt just prompt bloat?

No. Prompt length is one symptom. Debt also includes wrong routing, ambiguous authority, contradictions, version drift, obsolete workarounds, unsafe omissions, and missing acceptance tests.

Should a skill root document contain the full workflow?

Only when the workflow is genuinely small and single-purpose. For multiple variants, make the root a concise router and load the exact reference, script, or template needed for the selected path.

Can a stronger model make repository guidance unnecessary?

It can make some handholding unnecessary. It does not know your private build commands, organization authority, regulated boundaries, supported release process, or definition of done unless those are discoverable. Preserve project facts and controls that remain true.

How often should teams audit AGENTS.md and skills?

Review them after a material model, runtime, plugin, tool, repository, or policy change and on a regular cadence. Model workarounds should have shorter expiry dates than stable safety or release contracts.