write-docs

name: write-docs description: Use when writing or editing documentation pages (concept pages, how-to guides, API reference prose, tutorials) under docs/. Provides the writing style, voice, and structural rules for Agenta docs. Apply this skill before drafting any new docs page, and include it in the brief for any subagent tasked with writing docs. allowed-tools: Read, Edit, Write, Grep, Glob, Bash user-invocable: true

Write Docs

A short, living set of rules for writing documentation in this repo. Update as we learn what works.

1. Pick the doc type first (Diátaxis)

Before writing, decide which of the four types you are writing. Don't mix them in one page.

Quick test: Is the reader learning or working? Do they need procedures, facts, or context? If you can't answer, pick the type before drafting.

Don't pollute a page with another type. Link out instead. A how-to that explains background mid-flow breaks the reader's task.

2. Style

Tone: Docker / Stripe reference tone. Declarative. Helpful, not promotional.

Voice:

• Active voice.
• Short, punchy sentences by default.
• Complete sentences unless brevity clearly wins.
• 11th-grade English for non-technical wording.
• Conditional imperatives in how-tos: "If you want X, do Y."

Words to avoid: "comprehensive", "powerful", "seamlessly", "easily", "simply", "robust", "leverage". Marketing words.

Punctuation:

• Never use em dashes (—). Use a period, parentheses, or a semicolon.
• Bold and bullets sparingly; only when they aid scanning.

Length:

• Short paragraphs.
• Cut anything that doesn't serve the reader's goal on this page.
• Reference pages are dry on purpose. Don't add narrative.

3. Customer-facing vocabulary

Docs use the words customers see in the UI and API. Internal vocabulary stays in source code.

If a page introduces a term, link to its concept page on first use.

4. Examples must be obfuscated but accurate

• Use placeholder UUIDs: 019d952f-0000-0000-0000-000000000000.
• Use fake but plausible data: "country": "France".
• Verify request/response shapes against the live API (eu.cloud.agenta.ai with the saved key) before publishing. Shapes must match what the endpoint actually returns.
• If you find a bug while verifying, file it. Do not paper over it in the docs.

5. How-to specific rules

When writing a how-to:

• Title is the user's goal, not the feature name. "How to invoke a deployed variant" beats "Using the invoke endpoint".
• Only actions on the page. No teaching, no rationale digressions. Link out for those.
• Branch where reality branches. "If your app uses chat, do X. Otherwise do Y."
• Start at a meaningful entry point. Don't repeat setup from a prerequisite page; link to it.
• Anticipate the next step. Each step should set up the next.

6. Reference specific rules

• Tables, lists, parameter descriptions. No narrative.
• Every parameter gets a description, type, and whether it's required.
• For FastAPI: docstrings go on the handler function. Field descriptions go on Field(description=...). Never put prose in openapi_extra={}.
• Don't explain "why" in reference. Link to an explanation page if needed.

7. Concept (explanation) specific rules

• Lead with the model the reader needs to hold in their head.
• One worked example is worth three abstract paragraphs.
• It's OK to be discursive here. This is the one type where narrative belongs.
• End by pointing to the how-tos and reference pages that apply the concept.

8. Auto-generated content: stay out of docs/docs/reference/api/

The *.api.mdx files under docs/docs/reference/api/ are auto-generated by docusaurus-plugin-openapi-docs from docs/docs/reference/openapi.json. Do not commit changes to those files from a domain PR. They produce 100+ files of noise per regen, and the regen is mechanical.

The auto-generated MDX is regenerated separately, downstream, after the underlying spec is updated. Two important facts about that flow:

• pnpm update-api-docs (the default) downloads openapi.json from production (raw.githubusercontent.com/.../main). That spec does not yet contain your branch's new docstrings, so regenerating from it strips your work back out.
• To get the new docstrings into the rendered docs, openapi.json has to be dumped from the branch's code (e.g. by running the API locally and hitting /openapi.json, then pnpm update-api-docs:local). That step happens once at the merge stage, not in each domain PR.

In a domain PR, your job is the source-of-truth changes:

• FastAPI handler docstrings.
• Field(description=...) on request/response models.
• The concept page under docs/docs/reference/api-guide/.

Leave the auto-MDX regen to the downstream flow. If your git status shows changes under docs/docs/reference/api/, revert them before committing: git checkout origin/<base-branch> -- docs/docs/reference/api/.

9. Before you ship

• Run the docs build (npm run build in docs/) and fix any errors.
• For API doc changes: run ruff format then ruff check --fix in api/.
• For changelog pages: see .claude/skills/create-changelog-announcement/SKILL.md for the dual-entry format and build rules.
• PR title convention: docs(docs): … for guide-only, docs(api): … for endpoint docstrings, mixed if both. If you have an issue id, prefix: [issue-id] docs(...): ….

10. Iterate

Start minimal. Ship a draft, get feedback, refine. Don't try to write the perfect page in one pass. Don't restructure whole sections in one PR.

Subagent brief template

Use this as the starting point when delegating doc-writing to a subagent. Fill in the bracketed parts. Always include the "Read first" list so the subagent picks up context.

You are writing [domain] documentation for Agenta.

Read first, in order:
1. .claude/skills/write-docs/SKILL.md (this file — the style rules you must follow)
2. tmp-docs-analysis/plan.md (project plan: scope, ordering, PR shape)
3. tmp-docs-analysis/concept-map/<domain>.md (domain research; if it exists)
4. The landed concept pages this work links to (e.g., 04-versioning.mdx)
5. The repo AGENTS.md sections on PR titles and lint commands

What to produce:
- [Concept page path, e.g., docs/docs/reference/api/06-workflows.mdx]
- Docstrings + Field(description=...) for [domain] endpoints in api/oss/src/apis/fastapi/<domain>/

Doc type:
- Concept page is an Explanation in Diátaxis terms.
- Endpoint docstrings are Reference. Keep them dry. No narrative inside docstrings.

Verification:
- Hit each endpoint at least once against eu.cloud.agenta.ai using the saved API key.
- Obfuscate IDs and payloads in examples, but request/response shapes must match the live API.
- If you find a bug, flag it with a repro. Do not paper over it.

Vocabulary:
- Customer-facing only. No "runnable" or "loadable". See §3 of write-docs.

Ship:
- Draft PR via `gh pr create --draft`.
- PR title: `docs(api): <domain> endpoint docstrings + concept page`.
- Run `ruff format` and `ruff check --fix` in api/ before commit.
- Run the docs build in docs/ before commit.

Out of scope:
- [List anything explicitly excluded, e.g., admin endpoints, preview endpoints]