typefox/agent-skills/agent-experience

Agent Experience (AX)

AX is the experience AI agents have when working in a repository — how easily they can access, understand, verify, and safely change it. Two reframings drive everything in this skill. First, onboarding happens at the start of every task: a human onboards once, an agent re-onboards every session, so everything a new hire needs in week one, the agent needs in minute one, on every run. Second, hallucination is what inference looks like when context is missing: when an agent invents a build command or misuses an internal API, that is not a model defect to tolerate — it is an AX defect to fix.

The honest test — the single success criterion behind every artifact this skill produces: an agent given a real ticket, with no human help, reliably reaches a green verification suite and produces a diff a reviewer accepts. Optimize for that. Readiness checklists and scores are diagnostics for spotting neglect, never targets to maximize.

Vocabulary: write "AX" and "agent-ready" in everything you produce. When reading sources or searching the web, also recognize the synonyms: context engineering (the superset term — this skill is its repo-side slice), harness engineering (in its repo-side sense), agent readiness, agent legibility, ambient affordances. Generated artifacts never say "harness" — that word collides with the agent-runtime meaning.

The control system in brief

Treat the repo-side AX setup as a control system that regulates the codebase toward its desired state. Two control directions × two execution modes give a 2×2 that classifies everything you find or create:

Both directions are mandatory. Feedback-only, the agent repeats the same mistakes every session — nothing steers it up front. Feedforward-only, rules accumulate but nothing ever verifies they held. Guides raise first-attempt quality; sensors give the agent a self-correction loop that fixes issues before they reach human eyes. Sensors also set the ceiling — the sensor ceiling: the system regulates only what some sensor observes, so a defect class nothing senses (a page that renders wrong under green tests, errors swallowed by a catch block) ships and recurs without ever triggering the loop below. Before letting more agent work land with less human review, widen sensor coverage first — every blind spot a reviewer used to cover becomes a shipped defect class.

The steering loop is the practice that builds and maintains the system: whenever an agent makes a mistake, engineer the repository so that mistake cannot recur — never settle for "prompt harder". Escalate any recurring failure up this ladder until it stops recurring:

1. a line in AGENTS.md →
2. a dedicated doc or skill →
3. a lint rule or structural test →
4. an architectural constraint.

Operate the loop as a coupling with a restraint. The coupling: the rule or sensor that prevents a mistake ships in the same change as the fix for that mistake, with the triggering incident cited inline (issue number, error, failing run) — fix and lesson never travel separately. The restraint: rules are added one per observed mistake, never speculatively — a mistake that hasn't happened yet can't pass the litmus test. The citation is also what keeps rules prunable: a rule that names its incident can later be re-judged against whether that failure class still occurs; a rule that names nothing is the first pruning candidate.

Keep quality left: fast computational sensors run alongside the coding session; expensive and inferential ones run post-integration or on a schedule.

Affordances are the structural properties that make a repo governable — what the codebase makes cheap to sense and to constrain: a strongly typed language (type checking is a free sensor), a constraining framework (its conventions abstract away whole error classes), fast build/test tooling (feedback-loop speed), clearly definable module boundaries (expressible as import rules). Start with what the codebase affords; acquiring a missing affordance (adding types, cleaning boundaries) is an investment that precedes the sensor work it enables. Variety reduction is the affordance you choose: committing to a topology narrows what an agent can produce, which is what makes a comprehensive control set achievable.

Non-negotiables — the AX standards

Hold every artifact you audit or generate to these. In improve mode they are the audit checklist; in every mode they are the generation rules. Cite them by tagline when explaining findings (e.g. "this violates map, not manual"), as this document does itself.

1. Repo-local or nonexistent. Anything the agent can't reach from inside the repo effectively doesn't exist — wikis, chat threads, and people's heads are invisible. Push knowledge into versioned repo artifacts. An external system counts as reachable only where a fetch path exists (e.g. gh for GitHub issues); otherwise mirror a one-line summary with the link as provenance.
2. Single source of truth. Each fact lives in exactly one place; everything else points at it. Never vendor copies of external docs — audited vendored files have drifted 183 lines from upstream, still instructing agents to run tools removed months earlier.
3. Map, not manual. The root instruction file is a ≲150-line map that teaches the agent where to look next, with progressive disclosure into docs/. A giant file crowds out the task, makes everything "important" (so nothing is), rots into stale rules, and can't be mechanically verified.
4. Every line passes the litmus test: would removing it cause a mistake the agent wouldn't otherwise make? Instructions are not free: unnecessary rules cost reasoning tokens on every task, listed commands get used vastly more than unlisted ones, and unedited LLM-generated overview files reduce task success while raising cost (the numbers — single-study, but the best we have — are in references/agents-md.md). Deviations from ecosystem defaults earn lines; defaults never do.
5. Never trust prose — verify by execution. Every command cited in agent docs is verified by actually running it, with the exact invocation and timing recorded. A doc–reality discrepancy is a first-class finding, not noise.
6. Run it, don't read it. Agents demonstrably read check scripts and predict their results instead of executing them. Require evidence-backed verification: execute the check, capture the output to a file rather than through a pipe, and read the exit code unpiped — cmd | tail reports the pipe's exit status, not the command's, so a failing check piped through a pager or filter records a misleading 0.
7. Verify the relevant output. A change is proven at the application's observable output — the rendered page, the emitted data or file, the API response — never only at the code that produces it: code-level sensors routinely stay green over wrong output (a layout that renders broken under passing unit tests; a stream with the right schema and wrong numbers). Where the agent can't natively perceive that output — pixels, large result sets, binary formats — supplying the perception tooling that makes it legible (browser automation to see a UI, a query script over emitted data) is part of the AX setup, not an optional extra.
8. Enforce invariants mechanically where it pays; prose where judgment is required. State the boundary ("parse data shapes at the boundary"), enforce it with a lint or structural test, and leave the how open. A check is code the repo maintains from then on: a rule configured in a tool the repo already runs is nearly free, a bespoke script is a component with its own bugs and drift. Weigh that upkeep against the mistake it fences — a prose line is the right rung wherever the check would cost more than the mistakes it prevents.
9. Error channels are guidance channels. Every custom check emits messages written for agent self-correction: what's wrong, why the rule exists, what to do instead, how to record a justified exception where judgment is legitimate — and, when the rule lives in a doc, where it lives (message patterns in references/techniques.md).
10. Docs are verified like code. Freshness is mechanically checked (scripts/check_docs.py — its module docstring lists every check), and every artifact has an explicit lifecycle: active/completed for plans, accepted/superseded for decision records.
11. Write-as-you-go. Agent statelessness erases anything not captured: every interview answer and decision lands in its durable artifact immediately — never in a summary to be filed later.
12. Every fact traces to a source. Any statement in a generated doc traces to the repo, to output captured this session, or to the user's own words — anything else is marked (to be confirmed) or omitted. Product color counts: an invented name, count, or backstory is as much a fabrication as an invented database choice, and the user is never quoted or paraphrased saying something they did not say.
13. Convention over configuration. This skill carries opinionated defaults for the AX layer itself — which artifacts to create, doc layout, sensor wiring, message patterns — and applies them whenever the user hasn't stated otherwise. Interviews and template placeholders gather project facts (intent, scope, technical architecture); they never poll the user on how to design the AX layer ("would you like ADRs?" is a forbidden question). An unprompted user preference or a hard project constraint overrides a default and gets recorded as an ADR. When in doubt, convention wins.

Pick your mode

Find the user's situation and jump in — state your chosen mode and scope before starting (that statement is Phase 0; consult alone skips it):

The workflow

One shared phase spine; the mode selects which phases run and at what depth.

Phase 0 — Scope and mode