When should I run /write-docs?

Use to keep codebase documentation updated as new features and APIs ship.

Is /write-docs a Cursor skill?

No. /write-docs is a slash command you type. Skills are playbooks the agent may load. Use both: the command runs the workflow, the skills constrain how it writes.

← Cursor Slash Commands · ENGINEERING

/write-docs

Technical Documentation & API Reference Writer

OpenAPI 3.0 specs, developer guides, code samples, and architecture docs.

/write-docs Generate OpenAPI 3.0 specification for authentication and team management routes

Where it installs

# .cursor/commands/write-docs.md
# no frontmatter, the file opens with its H1 title

# .claude/commands/write-docs.md
---
description: ...
argument-hint: [doc target and audience]
allowed-tools: Read, Grep, Glob, Skill, TodoWrite, Task, ...
---

What it does

/write-docs is a Cursor slash command. Type it in chat to run a saved workflow: Technical Documentation & API Reference Writer.

Produces clear developer documentation: OpenAPI 3.0 schemas, interactive curl examples, system architecture guides, and SDK quickstarts.

OpenAPI 3.0 specs, developer guides, code samples, and architecture docs. Unlike a skill, a command is something you invoke on purpose. The agent does not decide to run /write-docs for you.

Why it exists

Founders retype the same multi-step prompt until it rots. /write-docs exists so the pipeline, all 4 steps of it, is a file in .cursor/commands, versioned with the repo.

It ships in the Engineering Kit. It is wired to the API & Technical Documentation Writer (technical-writer) and Technical Lead & System Architect (tech-lead) agents. Required skills: Technical Documentation & OpenAPI Spec Design; Project Conventions & CURSOR.md Standards.

When to use it

Use to keep codebase documentation updated as new features and APIs ship.
Use /write-docs when you want that pipeline, not a freeform chat. If you only need one step, use a narrower command or a single agent.
Start a new chat. Do not run this command in a thread that just wrote marketing copy.

When not to use it

Do not run /write-docs as a substitute for reading the diff. The command produces files; you still gate them.
Do not chain it into a 40-turn chat. Fresh context is part of the design.
Do not run it if you have not filled CURSOR.md. The pipeline will invent a stack.

Example workflow

Scan API routes and TypeScript interfaces to extract schema definitions
Generate OpenAPI 3.0 YAML/JSON specification with example payloads
Write step-by-step developer tutorial with copy-paste code snippets
Create Mermaid architecture diagram visualizing request lifecycles

Example usage

Type this in Cursor chat: /write-docs Generate OpenAPI 3.0 specification for authentication and team management routes

The command file tells the session which agents to adopt and which skills to read. You should see phase headers, not a single dump of code.

If a phase fails its gate, stop. Do not add 'just continue'.

Example output

Expected artifact: docs/api/openapi.json
Expected artifact: docs/guides/quickstart.md

Best practices

Keep the prompt specific. /write-docs Generate OpenAPI 3.0 specification for authentication and team management routes is the shape: object, constraint, and outcome.
Let the listed agents work in order: technical-writer → tech-lead.
Save outputs in the repo. Chat-only answers evaporate.
Engineering commands should leave tests or an audit note, not only implementation files.

Common mistakes

Typing /write-docs with no object ('do the thing'). The pipeline will guess.
Re-running the command in the same chat after a failed gate instead of fixing the failing file.
Editing the command file to skip review so it 'goes faster'.
Skipping the Technical Documentation & OpenAPI Spec Design skill that the command depends on.

Frequently asked questions

What does /write-docs do in Cursor?
Produces clear developer documentation: OpenAPI 3.0 schemas, interactive curl examples, system architecture guides, and SDK quickstarts.
When should I run /write-docs?
Use to keep codebase documentation updated as new features and APIs ship.
What is an example /write-docs prompt?
/write-docs Generate OpenAPI 3.0 specification for authentication and team management routes
Which skills does /write-docs load?
Technical Documentation & OpenAPI Spec Design; Project Conventions & CURSOR.md Standards
Is /write-docs a Cursor skill?
No. /write-docs is a slash command you type. Skills are playbooks the agent may load. Use both: the command runs the workflow, the skills constrain how it writes.

Run /write-docs from your own repo

AgenticKit installs 47 slash commands, 46 agents, and 61 skills. One command installation.

Get AgenticKit →All Commands