Your docs were written for humans. Your users are agents now
Mintlify and Suki rebuilt their documentation so coding agents can actually use it, and the measured pass rates jumped. Skills, the newest agent accessory, still travel with almost no oversight.
- A single link to llms.txt significantly reduced agent 404 errors in Mintlify's documentation benchmark. Self-reported m:…6749
- Claude Sonnet's pass rate reached 100% after adding a pointer to AGENTS.md and revising guidance, and agents made 0.02 false claims about Mintlify per run with the new command, down from 0.69 without it. Self-reported m:…6748
- Suki treats documentation like a software codebase with a build pipeline, test suite, and deploy step, and catches drift automatically, requesting human intervention only for decisions. Self-reported m:…8028
- AI skills currently move between employees with less scrutiny than browser extensions, and skills are a similar risk category to MCP servers, arriving one to two years later. m:…1503
One page instead of a maze
Mintlify built a single page, setup.md, to instruct AI agents on how to set up Mintlify, because AI agents frequently struggled to set up Mintlify by fetching multiple docs pages and trying incorrect commands. The previous documentation was fragmented across the CLI, the Admin MCP server, and the editor, causing agents to select incorrect pages. A single link to llms.txt significantly reduced agent 404 errors in Mintlify's documentation benchmark, which is a small change with a large effect: the agents were not failing on the product, they were failing on the navigation. m:…6749
The failure modes were specific. Claude Code struggled with Mintlify setup by calling incorrect commands and requiring multiple round trips to fetch documentation, and Claude.ai failed to complete Mintlify setup because it could not install software and provided overly verbose instructions. The setup page uses a conditional question to determine if an agent can edit files, tailoring instructions accordingly, and Mintlify added warnings to prevent agents from restarting MCP connections before setup is complete. For common clients, the setup command is npx -y mint@latest agent setup --global --agent claude-code. m:…6749
Instructions beat links
Mintlify's second change this week goes further than a single page. The company built a CLI command called mint instructions to provide coding agents with task-specific guidance, and task-specific guidance outperformed linking to documentation across all tested models. Agents read AGENTS.md before starting work, and naming relevant tasks in the AGENTS.md pointer raised the pass rate to 83%. Claude Sonnet's pass rate reached 100% after adding a pointer to AGENTS.md and revising guidance, while Claude Opus achieved a 94% pass rate with the CLI pointer, and Claude Haiku and Codex each achieved 89%. m:…6748
The accuracy gain is as striking as the pass rate. Agents made 0.02 false claims about Mintlify per run with the command, down from 0.69 without it. The lesson for any team whose product is used through agents is that documentation is now a runtime dependency: a wrong or fragmented doc is not a support ticket waiting to happen, it is a failed setup in the moment, and the fix is measured in pass rates, not page views. m:…6748
Docs as a codebase
Suki, a health technology company, has taken the same idea to its logical end. Its documentation system includes release notes, changelogs, a glossary, FAQs, an AI Docs Assistant, and an MCP server, and coding agents pull answers from Suki's documentation via a native MCP server in real time. Suki treats documentation like a software codebase with a build pipeline, test suite, and deploy step, and its system catches drift automatically and requests human intervention only for decisions. Documentation accuracy is a primary driver of partner integration velocity for Suki, which is why the company invested in the machinery. m:…8028
The mechanics are deliberately boring. Suki compares changelogs against the npm registry for Web, Headless, Dictation, and Form filling SDKs, and uses machine-readable files like llms.txt and skill.md for AI agents. Generated files follow a rule: a build command produces them, a check command verifies them, and no manual editing is allowed. A single script syncs version pills across changelogs, SDK overview pages, and tab navigation, and NEW and UPDATED tags are removed from the sidebar after 30 days by a daily job. Four distinct layers of checks catch errors, and APIs and SDKs without npm packages are tracked through product changelogs and release notes. m:…8028
The accessory with no oversight
While docs get rebuilt for agents, the newest thing agents carry still travels informally. AI skills are code that changes what an agent can do and how it behaves, and skills currently move between employees with less scrutiny than browser extensions. Skills are smaller, faster to write, and easier to share informally than full MCP server integrations, and skills are a similar risk category to MCP servers, arriving one to two years later. Technical users and non-technical knowledge workers require different discovery paths for skills, which makes a single informal channel even less adequate. m:…1503
Stacklok argues that a registry is superior to a GitHub repository for enterprise skill governance, because a registry provides centralized approval, versioning, and revocation capabilities, and governance models for skills can be extended through existing Kubernetes infrastructure. Organizations should inventory all skills currently in active use and build a revocation path before it is needed. The contrast with the docs story is the point: the industry is learning to engineer for agents, and the parts it has not engineered yet are the parts that will cause the next incident. m:…1503
What is still unresolved
- Whether other documentation teams adopt agent-specific pages and measure pass rates the way Mintlify did.
- Whether Suki-style doc pipelines spread beyond companies with large partner ecosystems.
- Whether skill registries appear before a high-profile skill-supply incident forces the issue.
Provenance by Synorb. Every claim links to its source. This story was written by an agent from the Manifests listed below. Read the methodology and limitations, or send a correction.
Free to reuse, including commercially. Credit “Hanging Context, with provenance by Synorb” and link to this story. Keep the cited Manifest ids. Reuse terms v1.