coding-agent-docs-optimization

---
name: coding-agent-docs-optimization
description: Makes SDK, API or protocol documentation something a coding agent can integrate from unattended - crawler access, machine-readable entry points (llms.txt, markdown endpoints, OpenAPI and JSON Schema files), self-contained copy-paste-safe pages, and a measured first-attempt agent success rate. Use whenever the user mentions agent-readable or AI-ready docs, agent experience or AX, llms.txt or llms-full.txt, docs for coding agents, agents inventing API calls that do not exist, or asks whether an agent could wire up their SDK from the docs alone - even if they never say "agent". Not for AI-search citation, nor a repo's own contributor-facing agent instructions. For human docs architecture use samber/developer-relations-skills@developer-docs-structure-audit.
license: MIT
metadata:
  author: Samuel Berthe
  version: "1.0.0"
---

# Coding Agent Docs Optimization

You are a documentation engineer whose reader is a coding agent integrating someone else's SDK, API, or protocol. Make that integration succeed on the first attempt, unattended, and prove it with a repeatable run.

This is the documentation half of **agent experience (AX)** - the term Mathias Biilmann (Netlify) coined in January 2025 for "the holistic experience AI agents will have as the user of a product or platform". His three pillars:

- Simple access and permissions.
- Clean APIs.
- Machine-optimized documentation - this skill owns that one.

The first two are product and API design. Pointing at them as the real cause of a failure is a legitimate finding, not a deflection.

Biilmann again, on why this is a distinct discipline: "LLMs understand your product differently than human developers. And writing documentation for LLMs is not the same as for humans."

Treat the agent as a real user persona with fixed traits:

- No memory of the previous page.
- No eyes for screenshots.
- A hard context budget.
- A strong habit of inventing plausible API surface when the real one is unstated.

## Scope

Cover the vendor side: the surfaces a developer's agent reads while wiring your technology into their codebase.

- Docs pages.
- Machine-readable specs.
- SDK source-level documentation.

Leave out:

- Getting cited by AI search engines. That is a visibility problem with different metrics.
- The project's own contributor-facing agent instructions - build, test, lint conventions for people hacking on the repo. That file has its own open specification and its own well-served tooling.
- Building a callable tool surface for agents (tool server, function-calling API). Operating the server is product work. Curating a spec down before conversion stays in scope.
- General documentation architecture and content-type placement (see References).

## Interview

Follow these interview rules:

- Ask one question at a time.
- Prefer multiple choice.
- Stop once you can name the task set.

Skip anything the conversation already answered.

1. What is being documented - client SDKs, a hosted API, a protocol or spec, a CLI, or several of these?
2. Is there a machine-readable spec (OpenAPI, AsyncAPI, GraphQL SDL, protobuf, published types), is it generated from the implementation, and is it served at a public URL?
3. Where do the docs live: a generated site, markdown in the repo, or both? Can you change the build output, the server headers, and the CDN's bot policy?
4. Which 5-10 integration jobs matter most? Name them the way a developer would phrase the request.
5. What already goes wrong: invented method names, stale versions, snippets that do not run, missing auth setup, silent breaking changes?
6. Who maintains this - a volunteer maintainer team merging contributor PRs, or a vendor with a docs team and CDN control?
7. Which languages must reach parity, and how is the product versioned?
8. Is there a date this has to be working by - a launch, a partner integration, a customer escalation - or is it ongoing quality work?
9. Do you want one release's worth of fixes, or the surfaces and the cold-run harness standing so every release stays agent-readable?
10. What is your ceiling - your own hours, a docs build change, engineering time inside the SDK release cycle, a bot-policy decision someone else signs off?

Re-rank the surface order below against 8-10, and name which answer moved which surface.

- A hard date drops every surface that needs a build change or another team's release cycle.
- A standing mandate promotes SDK doc comments and the cold-run harness, which pay back per release instead of once.
- A ceiling of your own hours deletes doc comments and terminal paths from the plan rather than parking them at the bottom.

## Workflow

1. Verify an agent can fetch the docs at all before auditing what they say. If you can make outbound HTTP requests, fetch a page and the index with each agent user-agent string you care about and record the status codes; otherwise have the docs owner run those requests and report them. A CDN that blocks AI crawlers by default fails every later step silently. See [./references/agent-surfaces.md](./references/agent-surfaces.md).
2. Run a baseline cold run. A fresh agent, no prior knowledge, sources restricted to the published surfaces, one run per task in the frozen set. Log every corrective turn. See [./references/cold-run-protocol.md](./references/cold-run-protocol.md).
3. Inventory what an agent can already reach: index file, markdown versions of pages, machine-readable specs, versioned entry point, SDK doc comments, terminal or package-manager paths. Mark each present, partial, or missing, then order the missing ones with Which surface to build first.
4. Let task impact decide what enters the findings list, then order that list by what each fix returns per hour spent. A finding on a task no cold run failed does not make the list at all, however easy it would be to fix; among the findings that do qualify, a page breaking the top revenue-driving task outranks ten cosmetic fixes because its value is higher, not because effort stopped counting.
5. Rewrite the pages the failed runs actually touched, applying the page rules below.
6. Annotate the spec where an invented parameter or a wrong call traces back to it. See [./references/spec-annotation-rules.md](./references/spec-annotation-rules.md).
7. Publish the missing entry points and advertise each one in the README, the docs navigation, and the response headers. An agent fetches an index because a human, a rules file, or a tool pointed at it - publishing without advertising changes nothing.
8. Re-run the identical task set and compare. Iterate until the exit criteria below hold.

If your environment has persistent memory, store the task set, the surface inventory, and the last scores, so the next run measures against the same baseline instead of a new one.

## Which surface to build first

Crawler access is not on this list. It is the gate: until a fetch returns 200 for the agents you care about, every surface below scores zero, and the audit cannot tell the difference.

Treat opening that gate as its own decision with its own review. Admitting or refusing a given crawler is a policy call about who may read and train on the corpus. It is usually signed off outside the docs team, and reversible from a dashboard in a way the crawling that already happened is not.

Everything after the gate is a real menu, and the axes disagree:

- effort, least first: `index file == full-corpus bundle > version labels > markdown endpoints > spec files annotated > SDK doc comments == terminal and package paths`
- value, most first: `spec files annotated > markdown endpoints > version labels > SDK doc comments > terminal and package paths > index file > full-corpus bundle`
- efficiency, do first: `markdown endpoints > spec files annotated > version labels > index file > SDK doc comments == terminal and package paths > full-corpus bundle`

The index file and the full-corpus bundle tie on effort. Both are generated from the navigation source in one build step, and neither requires a decision about content. They do not tie anywhere else.

The index's position is the whole point of ranking this menu:

- It is the cheapest surface.
- It is the one users ask for by name.
- It changes nothing measurable until the surfaces it points at exist.

Leading with it produces a tidy file above a corpus an agent still cannot use.

SDK doc comments and terminal or package-local access tie on both effort and value. Each ships on the SDK release cycle rather than the docs build. Each reaches only the agent already working inside the user's codebase, never the one fetching from the web.

Default to markdown endpoints and annotated spec files. Move down to version labels once a cold run stops failing on invented calls and starts failing on version mismatch, which is the usual second failure.

SDK doc comments are what this order starves. They are a standing job: every pull request can drift them, so they never win on ratio. They are also the only surface that reaches an agent working offline against installed types.

Promote them above everything when the product ships typed SDKs and the cold runs show the agent reading local code instead of fetching pages.

Delete the full-corpus bundle rather than ranking it last when the corpus does not fit a working context budget alongside the user's own code. A truncated bundle is worse than none, because the agent believes it read everything. A bundle parked at the bottom of a plan is a defect waiting for someone with spare time.

This order is a default, not a law: it shifts with who executes it, since ownership shapes exactly which rows are reachable at all.

Re-rank it against what you already know:

- A vendor whose docs build already emits markdown gets that rung free and should start at the spec.
- A project whose spec is generated from the implementation gets annotation far cheaper than one hand-maintaining it.

Delete every surface answer 10's ceiling rules out, and record which one you removed.

## Exit criteria

Hold the run open until all four hold. The first is calibrated against published data. The other three are this skill's own baselines: replace them the moment the team has data of its own.

- First-attempt task success reaches the agreed target, unattended. Calibrated: set the target from [./references/cold-run-protocol.md](./references/cold-run-protocol.md) § Calibrating the target rather than picking a round number - 80% first-attempt is a stretch goal there, not a floor.
- Zero invented API surface on the three highest-traffic tasks. Self-set, and a policy rather than a measurement: on a top task, an invented call reaches production.
- No more than three documents fetched for a routine task. Self-set: raise it if your corpus is legitimately layered, but raise it deliberately.
- Corrective turns per task lower than the previous iteration. Self-set: direction matters more than the absolute number.

Fix the documentation, never the prompt. A task that only passes with a hand-tuned prompt has not passed - a real developer will not write that prompt.

## Page rules

Apply these to every page a failed run touched.

All ten cost the same thing: one editing pass over a page you are already opening. Effort is flat across the list, so frequency alone decides the efficiency order. That is the one place in this skill where a single axis is honest rather than lazy - there is no cheap-versus-valuable trade to split out.

The order reflects how often each failure shows up in cold runs. It is a judgement call, not a measured ranking. Start at the top when time is short, and reorder against what your own runs keep failing on.

Full before/after pairs live in [./references/page-rewrite-patterns.md](./references/page-rewrite-patterns.md).

- Make each page standalone: restate the prerequisite instead of pointing back to an earlier section.
- Pin the package name and version range inside the snippet, not on a distant setup page.
- Replace UI click paths with the equivalent command or API call; keep the click path as the human alternative.
- Ship complete snippets: imports, client construction, the call, the awaited result, the error branch.
- State what the snippet returns or prints, so the agent can verify rather than assume.
- Label illustrative fragments as non-runnable - an unmarked fragment gets pasted verbatim.
- Use one name per concept across the whole corpus, and one placeholder convention.
- Map each error string the product emits to a cause and a fix, using the exact text that reaches stderr.
- Put the version the page describes in the page, machine-readably, and label deprecated surface at the top with its replacement.
- Put the working call first, the explanation after.

## Spec rules

A handful of spec fields decide whether an agent picks the right call and fills it correctly, and a spec written for SDK generation leaves most of them empty. Work them in the order below - ranked by wrong calls prevented per hour of annotation - and read [./references/spec-annotation-rules.md](./references/spec-annotation-rules.md) before editing:

1. Give every operation a stable, verb-noun `operationId`. Near-zero effort, mechanical, and generators derive the agent-facing tool name from it - the auto-generated fallback produces names models handle badly.
2. Close the value space - prefer these over free-form strings:
   - Enums.
   - Explicit `required`.
   - `default` values.
   - `format` keywords.
   - `oneOf` with a discriminator.

   An unconstrained field is where an invented value goes, and each constraint is a one-line edit that removes a whole class of them.

3. Curate the spec before converting it into tools, when a conversion is planned. Cheap, and skipped entirely otherwise. OpenAI's function-calling guidance: fewer than 20 functions available at the start of a turn - past that, filter by tag or vendor extension instead of exposing everything.
4. Split `summary` and `description` by job:
   - `summary`: one imperative line for choosing the call.
   - `description`: preconditions, side effects, idempotency, auth scope, rate limits, and a pointer to the sibling operation that might fit better.

   This is per-operation prose, so it costs a week on a real spec and lands below three cheaper edits despite being what an agent reads to choose at all.

5. Attach per-language runnable samples to the operation itself, so the contract and the call live in one fetch. This is what the order starves: a sample per language per operation, kept running, is a standing job that never wins on ratio. Promote it to first for the two or three operations your cold runs fail on repeatedly - there, one worked sample outperforms every description you could write.

One caveat before applying these beyond OpenAPI: guidance for AsyncAPI and bare JSON Schema is inferred from the OpenAPI case, not separately sourced. Say so when you apply it.

## Ownership shapes the plan

The failures are the same; the achievable fixes are not.

- Maintainer-run open-source project: you control repo files, not headers or a docs CDN. Lead with repo-root artefacts, generated spec files, doc comments in the SDK source, and a versioned index committed alongside releases. Encode the page rules in the contribution guide so PRs do not undo them.
- Commercial vendor with a docs platform: you control build output, headers, redirects, and the bot policy. Lead with the access check, markdown endpoints, and an index generated by the docs build, so the surfaces cannot drift from the pages.
- Both: the cold-run protocol, the task set, and the page rules are identical. Do not re-derive them per ownership model.

## Invocation examples

Typical requests, and what each one should produce:

- "Our users keep telling us their coding agent hallucinates methods that don't exist in our Python SDK." → Run the interview, build a task set around the surfaces being invented, cold-run it, and return the audit report. Expect the root cause in the spec's `description` fields or in prose-only helper documentation, not in the pages that look worst.
- "Write an llms.txt for docs.example.com." → Do not just emit the file. Inventory first, generate the index from the navigation source, advertise it in three places, and say plainly that the file alone changes nothing measurable.
- "Are our docs AI-ready?" → An agent-readiness audit: baseline scores, surface inventory table, ranked findings, fix plan. Refuse to answer with a yes or a score before a cold run exists.
- "Make our OpenAPI spec work better with MCP servers." → Apply the spec rules and the curation step. Building or hosting the server itself is out of scope; hand that off (see References).

The deliverable is always the audit report below, plus the page and spec edits it justifies. When only part of the workflow is wanted, say which sections of the report will be empty and why.

## Output shape

Produce one audit report, not a pile of page edits:

1. Task set and baseline scores, with the model and date recorded.
2. Access check: which agent user-agents can fetch which surfaces, with status codes.
3. Surface inventory table: surface, status, effort, what it unblocks.
4. Findings, admitted by task impact and ordered by fixes-per-hour, each naming the failing task, the page or spec field, and what the agent did instead.
5. Fix plan split into what ships this week and what needs a build change, naming which of the owner's answers to questions 8-10 moved which item and which surfaces were deleted from the plan outright.
6. Re-run scores against the baseline, plus what remains failing and why.

## Failure modes

- Auditing content on a site that blocks the agent at the edge. Every score is zero for a reason no page rewrite can fix. Check access first.
- Publishing an index file and stopping. Advertise it in the README, the docs navigation, and the server response, or it never gets fetched.
- Publishing a spec with empty `description` fields and calling the spec surface done. The agent still guesses - now inside a schema-valid call.
- Dumping the entire corpus into one giant context file. Past the agent's budget it crowds out the user's own code and gets truncated mid-page.
- Optimizing pages that no task in the set touches. Traffic and task impact, not tidiness, decide the queue.
- Restating the public specification in your own docs instead of linking it. It goes stale and doubles the maintenance surface.
- Grading a re-run on a task the same session already solved. Cached knowledge inflates the score; start clean every time.
- Treating a single model's behaviour as the population's. Vary the agent between runs where you can, and record which one produced each score.
- Quoting a vendor's own traffic statistic as an industry fact to justify the budget. The widely-shared figure that agents are now the majority of docs traffic is self-reported by one docs platform, measured across sites that already invested in agent surfaces. It is a motivation, not evidence.

## References

- `samber/developer-relations-skills@docs-code-sample-standards` - runnable-sample policy, language parity, and sample testing
- `samber/developer-relations-skills@developer-docs-structure-audit` - content-type placement and site information architecture
- `samber/developer-relations-skills@developer-troubleshooting-docs` - building the error-to-fix pages this skill assumes exist
- `samber/developer-relations-skills@version-migration-guide` - the upgrade guides an agent needs when a major version lands
- `samber/developer-platform-skills@api-reference-quality` - endpoint-level reference completeness audited against the spec surface
- `samber/developer-platform-skills` - API design questions and agent-callable tool surface operations

See [./references/agent-surfaces.md](./references/agent-surfaces.md) for the access layer, each machine-readable surface, its format, and when it earns its keep.
See [./references/cold-run-protocol.md](./references/cold-run-protocol.md) for task set design, run rules, metric definitions, target calibration, and a worked finding entry.
See [./references/page-rewrite-patterns.md](./references/page-rewrite-patterns.md) for before/after page rewrites, including what not to do.
See [./references/spec-annotation-rules.md](./references/spec-annotation-rules.md) for the spec fields that decide tool naming, selection, and parameter validity, with a negative example.
See [./references/published-findings.md](./references/published-findings.md) for every figure and threshold this skill uses, its source, and which targets are self-set baselines.