| name | draft_docs |
| description | Draft new Warp documentation pages or update existing ones using established style conventions, with optional source code context from warp-internal and warp-server. |
Draft Docs
This skill guides the process of drafting new documentation pages or updating existing ones for Warp's documentation (referred to as "docs"), which lives at https://docs.warp.dev. All style rules, content type structures, formatting standards, and terminology live in AGENTS.md at the docs repo root. That file is the single source of truth and must be read before drafting new docs.
How to use
Invoke this skill with any context that describes what you want to document:
- PRDs or feature specs
- Slack threads or meeting notes
- Existing documentation that needs updating
- A description of a feature or concept
Example: "Use the draft_docs skill to write docs for [feature name] based on this PRD: [context]"
Workflow
When this skill is invoked, follow these steps in order:
1. Gather context
Review all provided context (PRD, spec, existing doc, etc.). Identify:
- What feature or topic is being documented
- Key user benefits and capabilities
- Technical details that need explaining
2. Clarify placement
Ask the user where the doc should live. The docs are organized into sections, each with its own astro.config.mjs (sidebar config):
src/content/docs/ - Warp Terminal and IDE → docs.warp.dev/src/content/docs/agent-platform/ - Agent Platform → docs.warp.dev/agent-platform/src/content/docs/reference/ - Technical reference (CLI, API & SDK) → docs.warp.dev/reference/src/content/docs/support-and-community/ - Support → docs.warp.dev/support-and-community/src/content/docs/enterprise/ - Enterprise → docs.warp.dev/enterprise/src/content/docs/changelog/ - Changelog → docs.warp.dev/changelog/
Also clarify: Is this a new page or an update to an existing page?
3. Read the style guide
Read AGENTS.md in the docs repo root. This is required — it contains all voice/tone rules, formatting standards, content type structures, terminology, and the quality checklist. Do not draft without reading it first.
4. Identify the content type and template
Using the "Drafting by content type" section in AGENTS.md, determine which content type the page is:
| Content type | Use when | Template | Skill |
|---|
| Conceptual | Explains what/why, no procedures | .warp/templates/conceptual.md | draft_conceptual |
| Procedural | Step-by-step task instructions | .warp/templates/procedural.md | draft_procedural |
| Quickstart | Fast path to a working result | .warp/templates/quickstart.md | draft_quickstart |
| Reference | Structured information for lookup | .warp/templates/reference.md | draft_reference |
| Troubleshooting | Problem → cause → solution | .warp/templates/troubleshooting.md | draft_troubleshooting |
| FAQ | Question-and-answer format | .warp/templates/faq.md | draft_faq |
| Guide | Task-oriented walkthrough (Guides section) | .warp/templates/guide-page.md | draft_guide |
| Feature documentation | Combined conceptual + procedural (most common) | .warp/templates/feature-doc.md | draft_feature_doc |
Once the content type is identified:
- Use the corresponding template as the starting scaffold for the page.
- If a type-specific skill exists (listed above), read it for additional rules and examples specific to that content type.
- Follow the structure and rules for the identified type in
AGENTS.md.
5. Research existing patterns
Read 2-3 strong examples in the target section to match existing patterns and conventions.
6. Research source code (if needed)
For technical accuracy, optionally look in Warp's source repositories:
- warp-internal - Client-side code (Rust, Swift, etc.)
- warp-server - Server-side code (Go)
To find these repos, search for directories named warp-internal and warp-server on the user's machine. If not found, ask the user where the repos are located.
Use source code to verify technical behavior, understand feature implementation, and find accurate terminology.
6.5. Critical formatting rules
These rules are frequently violated by agents. Apply them carefully during drafting:
- Sentence case for all headings (H1–H4) — Capitalize only the first word and proper feature names. ✅
## How it works ❌ ## How It Works
- Bold + dash format for list items —
* **Term** - Description, not * Term: Description
- Bold for UI elements — Use
**Save** not `Save` after action verbs like "click"
- Bold per-segment for Settings paths — Use
**Settings** > **AI** > **Knowledge** not `Settings > AI > Knowledge`
7. Draft the doc
Create the documentation using the appropriate template from .warp/templates/. Follow the structure for the identified content type and all rules in AGENTS.md. Each template includes visible bracketed instructions explaining what to put in each section.
8. Run style lint
Run python3 .warp/skills/style_lint/style_lint.py --changed on the drafted file to catch formatting and terminology issues before presenting to the user.
9. Review against checklist
Before presenting the draft, verify against the quality checklist in AGENTS.md:
10. Update navigation and redirects
If this is a new page, remind the user to:
- Add it to the relevant section's
astro.config.mjs (sidebar config).
If this page replaces, renames, or moves an existing page, remind the user to add a redirect:
- Same-space redirect: Add an entry to the space's
vercel.json (redirects) file under redirects:.
- Cross-space redirect: Add the redirect through the Astro Starlight UI (cross-space redirects cannot be managed via
vercel.json (redirects)).
Always check the current list of redirects before adding a new one to avoid duplicates.
Output
Present the drafted documentation as a complete markdown file that can be saved directly to the appropriate location in docs/.
