agentrel 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 <YOUR_KEY> 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:
- Coverage — the nine types with present / thin / absent
- Inventory — page-to-type map, with orphans and duplicates
- Example health — the verdict table with a pass rate
- Machine readability — checks and score
- Recommended structure — proposed navigation tree, marking new pages
- 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.