agent-ecosystem

Agent Docs Spec — Testing skill for Claude Code

Testing community

A specification for making documentation sites accessible to AI coding agents: discovery, truncation limits, content negotiation.

How to install Agent Docs Spec

This entry records only its repository, not the path inside it, so there is no exact command to give. Open agent-ecosystem/agent-docs-spec and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What Agent Docs Spec does

A specification for making documentation sites accessible to AI coding agents: discovery, truncation limits, content negotiation.

Alternatives in Testing

  • Flow Spec — NLSpec authoring — use when you need a structured specification from multi-AI research and consensus 2.8k ★
  • Agent Plugins Spec — Agent Plugins Specification v1.0.0 — A minimal standard for packaging agent extensions into distributable plug 1.2k ★
  • Spec Draft PR — Turn a feature idea or GitHub issue into a one-page spec saved to Documentation/specs/ and opened as a draft P 324 ★

README

Agent-Friendly Documentation Spec

A proposed specification for the documentation community to codify what makes docs agent-friendly. The spec focuses on meeting the technical constraints of agent platforms (truncation limits, content negotiation, discovery); it does not consider qualitative evaluation of content.

**Status**: Draft (v0.6.0)

**Full spec**: [SPEC.md](SPEC.md) | **Website**: [agentdocsspec.com](https://agentdocsspec.com)

The Problem

Coding agents (Claude Code, Cursor, GitHub Copilot, and others) increasingly fetch documentation during development workflows. But most documentation sites were built for human readers, and agent access patterns are fundamentally different:

  • Agents retrieve URLs from training data instead of navigating your site
  • Web fetch pipelines truncate content without warning (Claude Code at ~100K chars; the MCP Fetch reference server at just 5K chars by default)
  • HTML-to-markdown conversion is lossy, and inline CSS can consume the entire truncation budget before content even starts
  • Most agents don't know about llms.txt or .md URL variants unless told
  • Cross-host redirects and JavaScript redirects break agent access entirely

The result: agents frequently fail to get the documentation content they need, fall back on training data, or work with partial information without knowing it.

What the Spec Covers

The spec defines **28 checks across 7 categories**:

Category Checks What it evaluates
Content Discoverability 7 Discovery index exists, is valid, fits in a single fetch, links resolve, links point to markdown, embedded directives in HTML and markdown pointing agents to llms.txt
Markdown Availability 2 .md URL support, content negotiation via Accept headers
Page Size 6 Rendering strategy (SPA/CSR detection), markdown size, HTML size (pre/post conversion), served transfer size, content start position, single-fetch completeness
Co