draft-docs

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
• AEO, SEO, Peec, or answer-engine source data that should inform a draft

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

If no spec was provided, go looking for one. "Provided" assumes a requester, and a scheduled run has none — which is how automated drafts end up with an audience invented from a one-line changelog bullet. Check warp-server for a specs/<id>/PRODUCT.md matching the feature. Only some specs have one, and TECH.md is the implementation plan, not the product reasoning.

Use it for framing only: audience, problem, goals, and explicit non-goals. Per step 6 it is never verification for labels, flags, or defaults, and it is never evidence that a feature shipped. Never quote it into a page — warp-server is private and specs describe unshipped plans. If none exists, proceed without one and note the absence in the content design plan rather than inventing an audience.

1.5. Create an AEO brief when source data drives the request

If the request mentions AEO, SEO, Peec, answer-engine visibility, search-query vocabulary, content gaps, or whether to create a new page versus update an existing page, read .agents/skills/aeo_brief/SKILL.md and create the brief before drafting. Use the brief to decide:

• Which page or section should change
• Which user/search vocabulary belongs in the draft
• Which product terms or UI surfaces need precise naming
• Which topics to avoid because they duplicate existing docs or create a junk-drawer page
• Which questions require human review before publishing

2. Clarify placement

Ask the user where the doc should live. The docs are organized into sections, with navigation configured in src/sidebar.ts:

• 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.

3.5. Confirm the doc should exist, then design it

Two gates, in order. Both come before you open a template.

First, should this doc exist at all? Apply .agents/references/docs-worthiness-criteria.md.

How much of the gate applies depends on who is asking:

• Automated runs (missing_docs drift-watch, or any scheduled agent) apply the full gate. The default is no docs and the burden is on the change to earn a page. Record the verdict with the gate it passed and the concrete evidence — a setting key, CLI flag, quoted error string, changed default, API field, or (for Gate 4) the newly possible job plus the in-product surfaces you checked and found silent. If nothing passes, say so and stop; "this is new and users should know about it" is not a reason to write a page.

• A person asking directly is subject to Gate 0 only. Gate 0 is a factual check — has this shipped, is the surface public — and a requester can simply be wrong about it, so verify it and stop if it fails. Drafting for an unshipped feature is the most common failure regardless of who asked.

  Gates 1 through 4 are judgment, and a person requesting the page usually has context you do not: the roadmap, the support queue, a conversation you were not in. Do not decline their request on Gates 1-4. If something looks off — an existing page already covers the surface, or the change looks like a pure UI affordance — say so once, then defer to their answer and proceed.

When the change passes, choose the outcome explicitly: update an existing page (preferred), new page, or no docs. Prefer updating whenever a page already covers the surface. When Gate 4 is the only gate it passed, the outcome is capped at an update.

Second, what should the doc be? Pick the form with the routing rule in .agents/references/content-design-plan.md: a new page gets the full form in .agents/templates/content-design-plan.md, an update that adds a concept gets the three-line short form, and a correction gets no plan. Use the reference for what each field is asking.

The plan decides the content type — step 4 records that decision rather than making it. Starting at the template produces pages shaped by the template instead of by the reader's need.

When a person invoked this skill, present the plan and wait before drafting. This is the checkpoint: redirecting the audience or content type now costs a conversation, and after the prose exists it costs a rewrite. Do not skip it just because the requester seems confident about what they want.

Carry the completed plan into the PR body as a ## Content design plan section either way. In an unattended run there is no one to present it to, so the PR body is the only place a human will see the reasoning.

Small corrections listed under "When a plan can be skipped" in that reference are exempt from both gates.

4. Identify the content type and template

Record the content type chosen in the design plan, and pick its template and type-specific skill from this table. If drafting has diverged from the plan's chosen type, revisit the plan rather than silently switching templates.

Content type	Use when	Template	Skill
Conceptual	Explains what/why, no procedures	.agents/templates/conceptual.md	draft_conceptual
Procedural	Step-by-step task instructions	.agents/templates/procedural.md	draft_procedural
Quickstart	Fast path to a working result	.agents/templates/quickstart.md	draft_quickstart
Reference	Structured information for lookup	.agents/templates/reference.md	draft_reference
Troubleshooting	Problem → cause → solution	.agents/templates/troubleshooting.md	draft_troubleshooting
FAQ	Rarely — cross-cutting questions with no canonical home	.agents/templates/faq.md	draft_faq
Tutorial	Full workflow walkthrough (Guides section)	.agents/templates/guide-page.md	draft_guide
Feature documentation	Combined conceptual + procedural (most common)	.agents/templates/feature-doc.md	draft_feature_doc

Two of these carry admission rules rather than just structure, and both are checked in review:

• FAQ defaults to "not an FAQ." All three admission rules in AGENTS.md must hold before you create or extend one. Most FAQ-shaped content belongs on the page that owns the topic.
• Quickstart vs. tutorial is a scope decision, not a location one. A quickstart is ~5 minutes and ~600 words for someone who already knows the product; a tutorial walks a full workflow and requires that a quickstart already exists. "Guides" is the section name and holds both.

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.

When the draft names UI labels, Settings paths, CLI flags, default permissions, plan eligibility, or platform support, treat source (or a live build) as required verification, not optional color. A PRD or spec is not verification: labels and flag names routinely change between spec and ship.

If you cannot verify a claim (for example, the source repos are not available in this environment), do not guess and do not silently drop it. Choose one of these, and record the claim either way:

1. Omit the claim - Write around it when the page still works without it. Describe the action without naming the exact flag, or link to the reference page that will carry the detail.
2. Include it with an inline marker - Keep the spec's wording and flag it in an MDX comment next to the claim: {/* VERIFY: flag name from PRD, unconfirmed against warp-internal */}.

Keep a running list of every unverified claim as you draft. Reporting that list is required — see step 9.5.

6.5. Critical formatting rules

These rules are frequently violated by agents. Apply them carefully during drafting:

• Product name variables — For any product name in src/data/vars.ts, use the variable instead of the hardcoded string. Add import { VARS } from '@data/vars'; immediately after the frontmatter closing ---. Use {VARS.KEY} in MDX prose (e.g. {VARS.WARP_AGENT_CLI} not "Oz CLI"). Use {{TOKEN}} directly in frontmatter YAML values (e.g. title: "{{WARP_AGENT_CLI}} reference"). Key vars: WARP_AGENT_CLI, WARP_AUTOMATION_PLATFORM, WEB_APP, WEB_APP_URL, DASHBOARD, AGENT_MODE, WARP_DRIVE. See src/data/vars.ts for the full list.

• Sentence case for all headings (H1–H4) — Capitalize only the first word and proper feature names. ✅ ## How it works ❌ ## How It Works

• Descriptive, specific headings — Beyond correct case, a heading should name the specific topic so readers and agents can scan the page and extract a self-contained answer. Prefer the concrete object or outcome over a vague section label. ✅ ## How key type affects billing and GitHub access / ## Configuring Workload Identity Federation ❌ ## More details / ## Overview / ## Additional information / ## Other

• Frontmatter description is a standalone search summary — One to two sentences, roughly 50–160 characters, stating the user benefit and primary keywords. It must make sense out of context, in a search result or an AI citation. ✅ description: Environments keep cloud agents on a consistent toolchain across every trigger. ❌ description: This page describes environments. ❌ a description that only restates the title

• Bold + dash format for list items — * **Term** - Description, not * Term: Description and not * **Term** — Description. Use a hyphen with spaces around it as the separator after the bold term.

• Unordered list marker is * — Match the templates and existing docs. Reserve - for nested lists whose parent already uses ; use for numbered procedures. ✅ ❌ as the top-level marker on a new page

7. Draft the doc

Create the documentation using the appropriate template from .agents/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 .agents/skills/style_lint/style_lint.py --changed on the drafted file to catch formatting and terminology issues before presenting to the user.

If this skill is running as a cloud agent producing an agent-authored PR, capture a violation summary for the self-improvement loop after the PR is created:

1. Re-run with --output /tmp/style_lint_out.json to get machine-readable output.
2. Aggregate the issues array by check field to get violation counts per check name.
3. Include the following structured marker in your text response (write it as part of your agent message, not via a shell echo command). This ensures it appears as a TextContentBlock in the conversation, where oz run get --conversation can reliably retrieve it:

   [SIGNAL:style-lint] {"date":"YYYY-MM-DD","pr":"NNN","branch":"BRANCH_NAME","authored_by":"agent","skill_used":"SKILL_NAME","files_scanned":N,"violations":{"check_name":count}}
   

The improve-drafting-skills outer loop reads this signal from the conversation via oz run get --conversation, scanning assistant TextContentBlock messages for the marker. No git operations are required.

Skip steps 1–3 in local/interactive sessions.

9. Review against checklist

Before presenting the draft, verify against the quality checklist in AGENTS.md:

• The change passed .agents/references/docs-worthiness-criteria.md, and the verdict names a gate plus concrete evidence
• A content design plan exists with every field filled in, and the draft matches the content type it chose
• The outcome is the lightest correct one — an existing page was updated unless a new page is genuinely justified
• Frontmatter description is a standalone search summary (benefit + keywords; not "This page describes..." and not a restatement of the title)
• Content follows the structure for its content type
• Section order follows reader chronology (requirements → setup → usage → advanced → troubleshooting)
• Error messages and failure modes live in Troubleshooting, not woven through the main flow
• Callouts are sparse (usually 0–2 per page), never consecutive, and not used as a substitute for body prose
• Prose passes the tone rules: no marketing buzzwords, no meta-openers ("This page covers..."), no restated cause-and-effect or recap lines, and it reads naturally aloud (AGENTS.md → Voice & tone)
• Internal architecture (orchestrators, control planes, lifecycle states) appears only where the reader can act on it, and relocated detail landed on a maintainer-facing surface instead of being deleted
• A deletion-only second pass removed framing lines, self-commentary, rule justifications, and boilerplate a parent page already covers (AGENTS.md → Voice & tone → Cut again)
• Terminology matches the glossary (.agents/references/terminology.md)
• Headers use sentence case (with proper feature name capitalization)
• Headers name a specific topic (not bare Overview / More details / Other)
• Lists use * markers with bold term + hyphen + explanation format
• Cross-references are included, and the page ends with (quickstart or tutorial) or (every other type)

9.5. Report unverified claims

Inline {/* VERIFY: ... */} markers alone are skippable: a reviewer who skims the rendered page or the diff will miss them. Surface the full list where the human cannot miss it.

• Agent-authored PRs - Add an ## Unverified claims section to the PR description. Include one bullet per claim with the claim itself, the file and section where it appears, and what would confirm it (for example, "check TuiArgs in warp-internal"). Include the section even when the list is empty, with the single line None — all UI labels, flags, defaults, and eligibility claims were verified against source. Never drop the section.
• Local or interactive sessions - List the same claims in your response to the user, before they review the draft.

A reviewer must be able to see every unconfirmed claim without opening the diff.

10. Update navigation and redirects

If this is a new page, remind the user to:

• Add it to the relevant section in src/sidebar.ts.

If this page replaces, renames, or moves an existing page, remind the user to add a redirect to the redirects array in vercel.json at the repo root:

{
  "source": "/old/path",
  "destination": "/new/path/",
  "statusCode": 308
}

All redirects live in that one file, including redirects between top-level sections — there is no separate per-section redirect file and no UI for managing them. Include the trailing slash on destination to match the existing entries.

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/.