# Docs Architect > Audit the information architecture of a documentation set against what developers and AI assistants actually need, and report what is missing. Maps existing pages to a reference model, finds gaps and orphans, checks whether code examples run, and evaluates machine readability including llms.txt and clean-markdown access. Optionally drafts the missing quickstart. Works on a docs directory, a documentation site, or a repository README. Use when asked to review or restructure documentation, to find documentation gaps, to make docs AI-readable or agent-readable, or when docs exist but developers still cannot find what they need. - Skill: `agentrel/docs-architect` (Agent Skill) - Install (CLI): `npx skillmds@latest add agentrel/docs-architect` - Raw SKILL.md: https://api.skillmd.com/api/skills/agentrel/docs-architect/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: agentrel (https://skillmd.com/u/agentrel) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/agentrel/docs-architect --- # Documentation architect Most documentation problems are not writing problems. The pages are fine and the structure is wrong: no path from landing to first success, reference material where a guide belongs, and nothing that answers the question a developer actually arrived with. This skill audits structure. It does not rewrite prose. ## Applies to | | | |---|---| | **Project types** | Any product with documentation — APIs, SDKs, libraries, platforms, internal tooling | | **Stage** | Docs exist but developers still ask questions the docs should answer. Also before a docs migration, or after fast feature growth has left structural gaps | | **Needs** | A docs directory, a documentation site, or a substantial README | | **Skip if** | There is no documentation yet. Write a quickstart first, then audit — this skill assesses structure, and there is no structure to assess | The common trigger is a support channel answering the same question repeatedly. That is almost always a missing page type rather than a writing problem. ## How to use ``` /agentrel:docs-architect audit this repository's docs /agentrel:docs-architect ./docs audit a specific directory /agentrel:docs-architect https://docs.acme.com audit a published site ``` Produces `docs-architecture-report.md` and a printed coverage table across the nine page types. Read-only by default. Ask explicitly if you want the missing quickstart drafted — it writes to `docs/quickstart-draft.md` and never touches an existing page. ## The reference model Nine page types. A mature documentation set has all nine; the absent ones are the finding. | # | Type | Answers | Absent means | |---|------|---------|--------------| | 1 | Landing | What is this and is it for me? | Evaluators bounce before reading | | 2 | Quickstart | How do I see it work in minutes? | Time-to-first-value collapses | | 3 | Concepts | What is the mental model? | Users misuse the API correctly-shaped | | 4 | How-to guides | How do I do the job I came for? | Support answers the same question forever | | 5 | Reference | What are the exact parameters? | Integration becomes guesswork | | 6 | Examples | What does a real one look like? | Everyone writes the first version wrong | | 7 | Troubleshooting | Why did it fail? | Every error becomes a ticket | | 8 | Migration | How do I move versions? | Upgrades stall, old versions live forever | | 9 | Machine context | What can an assistant read? | AI-written integrations are hallucinated | Types 3 and 4 are the ones most often missing, and 7 is the one most often thin. Types 1, 2, and 5 are usually present because they are the obvious ones. ## 1. Inventory Map every page to a type. Record path, type, title, and last-modified where available. Look in `docs/`, `README.md`, `website/`, `content/`, and any docs-platform config — `mint.json`, `docusaurus.config.*`, `fern.config.json`, `mkdocs.yml`. For a hosted site, fetch the navigation tree. Flag: - **Unmapped** pages that fit no type — usually blog posts or internal notes in the docs tree - **Orphans** reachable by URL but absent from navigation - **Duplicates** two pages answering the same question, which is worse than one, because the reader cannot tell which is current - **Stale** pages contradicting the current API surface ## 2. Find the gaps For each of the nine types, score `present` / `thin` / `absent` with evidence. `thin` needs a definition, or the score means nothing: | Type | Thin when | |------|-----------| | Quickstart | Requires steps documented elsewhere, or the example does not run as written | | Concepts | Restates the reference with prose around it | | How-to | Covers the API surface rather than the jobs users have | | Reference | Fields listed without descriptions, or enums unenumerated | | Examples | Fragments rather than complete runnable programs | | Troubleshooting | Lists errors without causes or resolutions | ## 3. Test the examples Extract every fenced code block from the quickstart and how-to pages. For each, determine whether it could run as written. | Verdict | Meaning | |---------|---------| | `runs` | Complete and executable | | `needs-context` | Correct but depends on setup shown on another page | | `placeholder` | Contains `` or similar, and does not say where to get it | | `broken` | Will not run — wrong signature, missing import, outdated API | Execute the safe ones. A broken example in a quickstart is a `blocking` finding: it is the first code a developer runs, and failure there reads as the product being broken. ## 4. Machine readability Documentation is now read by assistants writing integrations on a developer's behalf. Score that path separately. | Check | Full credit | |-------|-------------| | Clean markdown access | Pages retrievable as markdown, not only rendered HTML | | `llms.txt` | Present at the domain root and current | | Structural headings | Semantic hierarchy, not visual styling | | Self-contained pages | A single page carries enough context to be useful alone | | Explicit constraints | Rate limits, auth scopes, and required fields stated in prose, not only in a table image | | Stable anchors | Deep links survive edits | On `llms.txt`: worth having, and cheap. Adoption sits near 10% of domains and the evidence for a search-ranking effect is weak — the real, demonstrated benefit is feeding coding assistants clean context. Score it as machine readability, and do not oversell it in the report as an SEO win. Self-contained pages matter more than most teams expect. An assistant frequently retrieves one page; if that page assumes three others were read first, the generated integration will be wrong in a way the developer cannot see. ## 5. Report Write `docs-architecture-report.md`: 1. **Coverage** — the nine types with present / thin / absent 2. **Inventory** — page-to-type map, with orphans and duplicates 3. **Example health** — the verdict table with a pass rate 4. **Machine readability** — checks and score 5. **Recommended structure** — proposed navigation tree, marking new pages 6. **Priority** — ranked, with effort Then print: ``` DOCUMENTATION ARCHITECTURE Landing present Quickstart thin example does not run as written Concepts absent ← highest-impact gap How-to guides thin 4 pages, all API-shaped not job-shaped Reference present Examples present Troubleshooting absent Migration absent Machine context thin no llms.txt, HTML-only retrieval Pages 47 · orphans 6 · examples 23 (14 run, 6 need context, 3 broken) First fix Repair the quickstart example ~1h Biggest Write the concepts page ~2d Report → ./docs-architecture-report.md ``` ## 6. Optionally draft the quickstart If the user asks, and only then, draft the missing quickstart. Write it to `docs/quickstart-draft.md` — never overwrite an existing page. Rules for the draft: - Every prerequisite stated inline, including the ones the team considers obvious - One complete runnable example, no placeholders without a link to where the value comes from - Ends at a verifiable result the reader can check - No marketing sentences ## Notes - **Structure, not prose.** Do not rewrite pages, and do not flag tone or style. - **Read-only** unless explicitly asked for the quickstart draft. - A documentation set covering all nine types well should score highly and get a short report. Do not manufacture gaps.