Technical documentation written by an AI agent instead of a person. The useful version is not a chat transcript. It is a Markdown file in your repository that the agent wrote after reading the code, that a validator checked, and that a teammate reviewed in a pull request.

Can AI-generated documentation be trusted?

Only with checks around it. A model will state a wrong status code with full confidence. Trust comes from three things: the agent reads the real code before writing, a schema validator rejects malformed or dangling content, and a human reviews the diff. The validator proves structure. The reviewer proves truth.

How is this different from asking a chat tool to write docs?

A chat tool hands you text. With Chiltepin the agent works inside the repository: it writes typed YAML blocks into Markdown, runs chiltepin check, and the renderer draws the diagrams from data. The output has a schema, a diff, a build, and a reviewer. The chat output has none of those.

How do AI docs stay in sync with the code?

They sit in the same repository, so the pull request that changes a handler can change its doc. chiltepin check runs in CI and fails on broken references, so a removed block cannot leave a dangling link. A changed fact still needs an update, and the agent can draft it because it can read the diff.

Which agents does Chiltepin work with?

The authoring skill installs with npx skills add jdiejim/chiltepin into Claude Code, Cursor, Codex, Copilot and others. Chiltepin is MIT-licensed open source; the CLI validates and renders locally.

AI documentation

AI docs your team can trust

"AI docs" usually means one of two things: documentation about AI systems, or documentation written by an AI. This page is about the second. For an engineering team it means an agent reads the codebase and writes the technical documentation a person would have written: API references, architecture maps, runbooks, decision records. The question is not whether an agent can write them. It can. The question is how to make them trustworthy enough to keep.

Where AI-generated documentation fails

Three failure modes account for most bad AI docs. Each needs a different fix, and one of them has no full fix.

Hallucinated facts. The model writes a field, a flag, or a status code that the code does not have. The prose is fluent. Fluency is not evidence.
Unverifiable diagrams. A generated image of a system cannot be diffed or checked against the code. If the arrow is wrong, nobody finds out until an incident.
Drift. The document was true when written. Nothing tells you when it stops being true.

Chiltepin addresses these with three mechanisms, and each one covers less than it might seem to.

Validation. Every block has a strict schema. chiltepin check rejects unknown fields, dangling doc#id references, and duplicate ids, and exits non-zero in CI. This checks structure, not truth. A block that says the wrong thing in the right shape passes.
Render by code. The model writes data: actors, messages, fields. The renderer draws deterministic SVG and HTML from it. The model never draws, so a diagram is always text you can read and review.
Source in Git. The doc lives beside the code. The same pull request can change both, and the diff shows exactly what changed. Drift is now visible, but not prevented.

What remains is the fact check. Two things carry it: the agent reads the real code before it writes, and a reviewer reads the pull request. Validation exists so that review can spend its time on facts instead of syntax.

The workflow

Request. You ask your agent for a document. It has the authoring skill, installed once with npx skills add jdiejim/chiltepin.
The agent reads the code. Handlers, models, configuration, tests.
It writes blocks. Markdown with fenced YAML sections, one block per structured thing: an endpoint, a sequence, an ERD, a timeline.
Check. chiltepin check runs; the agent fixes every diagnostic before it hands off.
Render. The build produces a static site, a standalone HTML file, slides, or a PDF from the same source.
PR review. A teammate reads the diff and confirms the facts.

In our own generation eval (40 scenarios, September 2026) an agent with the skill chose the right block 39.5 times out of 40. 33 of 40 documents were clean on first write, 40 of 40 at handoff, with 0 render failures and about 91 seconds per document. The scenarios are in the repository.

What a block looks like

A sequence diagram is the block engineers ask for most. The agent writes the YAML below from the real request path. The build draws the figure from it. The picture is a function of the data, so reviewing the data is reviewing the picture.

```sequence
id: seq-example
actors:
  - { id: Client, name: Client }
  - { id: Server, name: Server }
messages:
  - Client -> +Server: request
  - alt: cache hit
  - Server --> -Client: 200 cached
  - else: miss
  - Server --> -Client: 200 fresh
  - end
```

SECTION 01 · Sequence

SEQUENCE

Legendcallresponsethe answer the caller getsfragment (alt / opt / loop)active

A sequence block from its starter template. Actors and messages are data; the layout belongs to the renderer.

The Orders REST API document in the gallery is a full API reference an agent wrote this way. The outage postmortem shows the other side of AI docs: a timeline, a root cause, and decisions, written from an incident record. Every document is at /gallery with its source.

Rules for an engineering team

Docs live in the repo. This is the docs-as-code rule. A doc you cannot diff is a doc you cannot trust.
Run the check in CI. A dangling reference or a malformed block fails the build, the same as a failing test.
Review facts, not formatting. The schema already did the formatting review. Ask whether the endpoint returns what the block says.
Start with what you have. chiltepin sync turns OpenAPI, SQL, DBML, Prisma, and CSV into blocks. chiltepin audit scans a codebase and recommends which documents to write first.
Let the agent update, not just create. When a handler changes, the agent can read the diff and propose the doc change in the same pull request.

For the tool category, see the AI documentation generator page. For how agent-written docs compare with reference generators like TypeDoc and Swagger, see documentation generators compared.

Frequently asked questions

What are AI docs?: Technical documentation written by an AI agent instead of a person. The useful version is not a chat transcript. It is a Markdown file in your repository that the agent wrote after reading the code, that a validator checked, and that a teammate reviewed in a pull request.
Can AI-generated documentation be trusted?: Only with checks around it. A model will state a wrong status code with full confidence. Trust comes from three things: the agent reads the real code before writing, a schema validator rejects malformed or dangling content, and a human reviews the diff. The validator proves structure. The reviewer proves truth.
How is this different from asking a chat tool to write docs?: A chat tool hands you text. With Chiltepin the agent works inside the repository: it writes typed YAML blocks into Markdown, runs chiltepin check, and the renderer draws the diagrams from data. The output has a schema, a diff, a build, and a reviewer. The chat output has none of those.
How do AI docs stay in sync with the code?: They sit in the same repository, so the pull request that changes a handler can change its doc. chiltepin check runs in CI and fails on broken references, so a removed block cannot leave a dangling link. A changed fact still needs an update, and the agent can draft it because it can read the diff.
Which agents does Chiltepin work with?: The authoring skill installs with npx skills add jdiejim/chiltepin into Claude Code, Cursor, Codex, Copilot and others. Chiltepin is MIT-licensed open source; the CLI validates and renders locally.

Set up your agent See 40 agent-written documents Try Studio