coding-agent-docs-optimization

SKILL.md

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: