Skip to content
Agent Extensibility: Skills, Config & SubagentsWhat belongs in a config file

Senior · 7 chapters

What belongs in a config file

Build and test commands, conventions, architecture notes, invariants, gotchas — versus what belongs in a skill, a tool, or nowhere

Config files accrete into expensive, stale pseudo-documentation unless their scope and loading cost are actively policed.

Read these first

What you will know

  • Move something out of a config file into a skill, and say why

    Procedures become stale and waste context when they are injected for tasks that never use them.

  • Cut a bloated config file in half

    A forced size target exposes duplicated policy, obsolete exceptions, and prose that was never operationally necessary.

  • Decide what genuinely needs to be always-loaded

    A rule that matters only during a narrow workflow belongs elsewhere, or it will compete with task-specific evidence for context.

  • Measure the token, latency, and behaviour impact of a config line across representative turns

    A 500-token instruction repeated across 20 turns can consume meaningful context budget and still fail to change model behaviour.

  • Audit a config diff and classify each entry as config, skill, tool, or nowhere

    Misplaced execution logic, volatile facts, and undocumented conventions create stale guidance or capabilities the agent cannot reliably invoke.

Chapters

  1. 1

    Always-loaded is for rules the agent could break on any task

    The test is not importance but reach: could the agent violate this on almost any task it is given? An invariant like `billing` never writing to the analytics schema qualifies; a rule that only matters during a release does not, and will spend context competing with task evidence on every session that never releases. Apply the test before arguing about wording.

    Read chapter
  2. 2

    Config, skill, tool, nowhere: sorting a diff into four destinations

    A release-freeze end date belongs nowhere: it is a fact with an expiry that nothing in the repository will update, and afterwards the agent enforces a freeze that ended. A 40-line hotfix procedure is a skill; a recovery sequence for `ECONNREFUSED` is a script the agent runs; an invariant and a hostname stay. Sprint goals and volatile facts are the hardest cases to reject out loud.

    Read chapter
  3. 3

    Moving guidance into a skill replaces a certainty with a match

    A 400-line release runbook leaves the config, prompt tokens drop, nobody complains — and two months later a release goes wrong in a way the runbook covered. Unconditional text became conditional on a description matching, and no token graph records the runs where it did not. Relocation used to avoid an argument is worse still: nobody checks which moved sections actually fire.

    Read chapter
  4. 4

    Price a proposed section before agreeing to carry it

    Someone wants 500 tokens of error-handling conventions in the file. Run a representative set of tasks with and without the section on the same commit, and compare three things: whether the outputs differ, how much window is left for task evidence on the longest sessions, and what the section does to time-to-first-token once you know whether an always-loaded prefix is re-billed each turn or served from cache. A 500-token instruction repeated across twenty turns can consume real budget and still change nothing the reviewer can point at.

    Read chapter
  5. 5

    Halving a file finds the duplicate, the obsolete and the prose

    Given 2,400 tokens of commands, architecture paragraphs, invariants, an exception for a service deleted last year, a review checklist that also lives in the PR template and a section on commit messages, the cut is not a negotiation. Duplicates and dead exceptions go, commands and invariants stay, architecture shrinks to what the agent cannot read off the repository. Handle the 700-token deploy runbook used two days a month deliberately.

    Read chapter
  6. 6

    Policy text in context is not a control that holds

    Adding 900 tokens of security policy after the agent logged customer emails preserves the mistaken premise that presence in context guarantees compliance; trimming it to 300 preserves it more cheaply. The agent still logs an address on the run where attention went elsewhere, and now a violation reads as a one-off. The same confusion produces the two-line summary plus skill hybrid, two mechanisms with one owner that quietly diverge.

    Read chapter
  7. 7

    An enforceable control does not depend on the model reading it

    The previous chapter takes the security-policy proposal apart and puts nothing in its place, which is only half an answer to an engineer who still has an incident to close. The replacement is not text: a redacting logger that strips customer fields on the way out, a lint over which fields may be logged at all, a review gate on the paths that touch customer data — controls that hold on exactly the run where the agent's attention went elsewhere. Each of them buys determinism at the price of coverage, and each leaves a residue that genuinely does belong in the file, so the credible proposal is the one that also names what its alternative fails to cover.

    Read chapter

External resources

Start reading