The Configuration Surface

14.1 The Six Mechanisms #

Every major agent surface has converged on roughly the same set, albeit under different names.

The column that decides everything is the second. A mechanism loading on every turn amounts to a subscription, whereas one loading on demand amounts to a purchase. Putting on-demand content into an always-on mechanism is the critical configuration mistake, and nearly every repository has done it.

14.2 The Decision Rule #

One question, asked in the following order, resolves nearly every case:

The third and fourth questions catch the majority of real misuse. Most bloated instruction files are a collection of procedures that should be skills, and most of the rest are rules that should be path-scoped.

14.3 What Bloat Looks Like #

A real pattern, anonymized, illustrates it. A repository instruction file of 3,400 tokens containing:

After correction, the file carries 180 tokens always-on, 500 tokens that load when a React file is first touched, and 1,600 tokens that load on the rare turns which actually run a release or a migration.

The arithmetic, on Sonnet 5 at $2.00/MTok base input,²⁶ for a twenty-developer team averaging forty turns per developer per day:

20 devs × 40 turns × 22 working days = 17,600 turns/month

Before: 17,600 × 3,400 tokens = 59.8M tokens
After:  17,600 ×   180 tokens =  3.2M tokens
        + ~30% of turns × 500 (React)   = 2.6M   ← assumed residency
        + ~2% of turns × 1,600 (skills) = 0.6M   ← assumed residency
                                          -------
                                          6.4M tokens

Uncached delta: 53.4M × $2.00/M = $107/month

Two premises are doing work in that arithmetic and both should be stated. It is an uncached delta, so it is the worst case rather than the bill. And both conditional lines use a matching frequency where the quantity that bills is a residency fraction—the share of turns that carry the content, not the share that trigger it. Neither mechanism unloads itself once loaded: a skill body stays in the conversation (§16.1), and so does a path-scoped rule on Claude Code (§15.6), until compaction or a reset clears it. On sessions that touch a .tsx file early and then run long, the React line is closer to always-on than to 30 percent, and the same argument applies to the skill line. Both sit at cached-read rates on the turns that retain them, which is the reason this stays a small number rather than a large one. The 30 and 2 percent are therefore assumed residency fractions, and the arithmetic is correct given them—read the figure as an order of magnitude for the always-on line, which is where the 3,200-token cut actually lands, not as a model of what the conditional lines cost.

A hundred dollars a month is not, however, the point. The point is that the same edit removes 3,200 tokens of dilution from every turn, and dilution is what the evidence in §12.1 says degrades reliability. The cost saving is a rounding error; the quality effect is the reason to do it.

14.4 Precedence #

When two mechanisms say different things, which prevails? Two halves of that question behave differently. Enforcement is settled: enterprise-managed policy and platform controls sit above anything a repository can set for itself because the repository cannot edit them (§19.1, §20.4). Textual priority—which sentence the model weighs more when two of them conflict—is under-documented and varies by surface, so the hierarchy below describes a tendency rather than a rule:

Enterprise / organization policy      ← highest; usually cannot be overridden locally
  Repository instruction file
    Path-scoped instructions          ← more specific wins over less specific
      Personal / user-level config
        Skill content                 ← loaded content, competes on merit
          The current message         ← usually wins in practice, being most recent

Two vendor facts cut against the middle of that stack. GitHub documents personal instructions as highest priority, repository instructions next and organization instructions last, which inverts two of those rows. And Claude Code loads user-level rules before project rules while stating that neither set overrides the other, so a conflict between them may resolve either way. The order therefore holds only as far as your own surface’s documentation says it does, and Part VI gives each platform’s configuration surface.

Two footnotes that matter in practice. Nearest-file-wins is a property of the hosts that document it—Codex implements the AGENTS.md specification’s nesting rule, so an AGENTS.md in packages/api/ takes precedence over the root one for work inside that package (§43.1)—and it does not follow from nesting support alone. Claude Code and Copilot CLI both discover nested files and both concatenate what they find rather than overriding: Claude Code orders the content from the filesystem root down, so the nearest file is read last and gains whatever recency buys, but the documentation is explicit that files do not override each other and that contradictory instructions may be resolved arbitrarily.⁴⁸ Discovery order is not conflict resolution. Where two nested files can disagree, fix the disagreement rather than relying on depth to settle it. And the last item is why an explicit instruction in your message reliably overrides a stale instruction file—recency is a strong signal, which is a useful escape hatch and a security problem in equal measure.

14.5 Inventory Before You Optimize #

One cannot fix a configuration surface one has not measured. Every mature surface exposes a way to see what is loaded.

# Claude Code
/context                    # what is in the window right now, by category
/cost                       # spend for the session

# GitHub Copilot CLI
/context
/usage

# Codex
/status

Run the inventory command on a fresh session with no prompt entered. Whatever it reports is your fixed block—the tokens you pay on every single turn before doing any work. Most teams have never looked at this number, and most are surprised by it. Tool definitions from connected MCP servers are usually the largest line item, frequently exceeding the instruction file by an order of magnitude.