Site directory
Everything on Agent Experience, in one place
Every guide, example, resource, rule and evidence record, grouped by what you want to do.
Each circle is a topic. The map puts its guides, rules and evidence records around it.
What do you want to do?
Learn the basics
What AX is, the map of the field, and the word list.
Fix a tool or API
Tool descriptions, large catalogues and APIs, instructions that stay true.
Design approvals and handoffs
Approval steps, handoffs to a person, and recovery after a failure.
Measure and review
The readiness rubric, metrics, and how to run a review.
Talk to the author
About, services, contact and support.
Understand the field
Start with the overview, then choose a topic below.
Go deeper by topic
Put it into practice
Follow a worked example or take a template into your own project.
Follow the evidence
Dated changes, the findings behind the guides, and the rules of a checker for agent-facing surfaces.
Every ax-check rule
D: descriptions and schemas
- Missing description
- Placeholder description
- Description only restates the name
- Does not say when to use it
- Does not say when not to use it
- No neighbouring tool named
- Closed vocabulary hinted in prose, not declared as an enum
- Parameter has no description
- Side-effect annotation contradicts the description
- No side-effect annotations
- openWorldHint false for a tool that reaches outside
- Object schema does not set additionalProperties to false
- Near-duplicate descriptions
- Duplicate name
- Description too short
- Description length outlier
- Context footprint estimate
- Required property not defined
- Example does not match the schema
- Promotional language in a description
- Many visible parameters
- SKILL.md frontmatter missing or invalid
- Skill name breaks the naming rules
- Skill description over 1,024 characters
- Bundled reference missing
- SKILL.md over 500 lines
C: CLI behaviour
- Command hangs without a terminal
- Error exits with status 0
- Error text not on stderr
- Error does not name a next step
- Unknown command gives no suggestion
- No machine-readable output flag
- Documented JSON output does not parse
- No dry-run flag documented
- Help is not reachable
- ANSI colour codes without a terminal
- NO_COLOR not honoured
- Version output is not plain
- Advertised JSON output not verified
F: drift and facts
- Claimed URL is broken
- Claimed URL could not be verified
- Claimed npm package does not exist
- Claimed PyPI package does not exist
- Claimed package version does not exist
- Claimed MCP tool is not served
- Served MCP tool is not mentioned
- Claimed CLI command does not exist
- Claimed CLI flag does not exist
- Linked local file is missing
- Claims extracted but not verified
Every evidence record
- An enum in the schema ends silent failures from example-only vocabularies
- Constraints stated only in prose produce silent failures on live APIs
- Error text that names the next tool lifts recovery
- Naming recovery tools is the active ingredient in failure receipts
- Idempotency keys cut duplicate writes from 28% to 4%
- An evidence contract cuts false-success reports after tool failures
- Browser agents declare success on most of their failures
- Declared completion and logged completion differ by up to 41 points
- Tools as code match or beat JSON tool calls for most models
- Agent scaffolding, not MCP versus CLI, drove cost
- Coding agents mostly read instruction files, not docs sites
- Compact documentation did not help when the source was present
- FAQ blocks and structured data showed no citation effect within a domain
- Allow/ask/never policies blocked less overreach than per-action approval
- Approvals that outlive their task raise attack success
- Approval records omit the effects a command goes on to trigger
- Injected skills lowered pass rates and raised token cost on average
- Skill rules that name a command or path change what agents do
- Skill selection precision collapses as the skill pool grows
- Praise and list order move tool selection
- Agents leave available tools unused: the adoption gap
- Search-and-execute meta-tools cut catalogue tokens by 99% in production
- Hiding tools is not enforcing permissions
- Harnesses alter shell calls and the wrong action runs silently
- Run-to-run variance dominates, and a verification tool beats a verification prompt
- Prompt injection split across tool channels evades defences
- A capable agent skipped the index and guessed the page
- A JSON input mode for a CLI raised agent cost 4x to 11x
- A warning that names the failing plan redirected agents; a tip did not
- Adding the context7 MCP server gave no lift; its tools went unused
- A model with cheaper tokens cost 3.7x more per run
- Vendor claim: agents never invoked a docs skill in 56% of eval cases
- Vendor claim: agents were 48% of Wrangler CLI use
- Vendor claim: users approved about 93% of permission prompts
- Vendor claim: 70% of new Supabase databases are created by agents or AI tools
- A CLI exits 0 when a destructive command is refused
- Destructive and bulk commands that report success but do nothing
- Dry-run output printed secrets until a fix redacted them
- Launch post and documentation disagree on agent output format
- Agent skills recommended a package that does not exist
Explore the work and get in touch
See the public work, read about its author, or talk about a workflow.
Use the site with an assistant
Connect an MCP client, or fetch the machine-readable files directly.