Write Feature Docs

write-feature-docs

Draft a complete documentation page for a new Warp feature. You read the feature's spec, verify technical claims by researching the codebase yourself, confirm the content design plan and then the outline with the engineer, and only then produce a complete MDX draft and open a draft PR in warpdotdev/docs — tagging the docs team for review.

The engineer's job is to confirm what you couldn't verify from the spec and code — not to do a full accuracy review, not to polish prose, not to know docs conventions.

The workflow

1. Find and read the spec files
2. Research the codebase to verify technical claims — minimize what the engineer needs to check
3. Present the content design plan and wait for confirmation — who the page is for
4. Present the outline and wait for confirmation — what the page will contain
5. Generate the complete MDX draft 5.5. Attempt screenshot capture via computer use (if available)
6. Open a draft PR in warpdotdev/docs and tag the docs team

Steps 3 and 4 are two separate confirmations, in that order. The outline is derived from the plan — the plan picks the content type, and the content type determines what sections the outline has. Presenting them together would show the engineer an outline built on an audience they have not agreed to yet, and they would anchor on the concrete outline instead of reconsidering the question above it. Settle who the page is for, then decide what goes in it.

Step 1: Find and read the spec

Ask the engineer for the spec ID if they haven't provided it. The spec ID is one of:

• A Linear ticket number: APP-1234, REMOTE-1234, QUALITY-408
• A GitHub issue (prefixed with gh-): gh-4567
• A short kebab-case feature name: vertical-tabs-hover-sidecar

Look for the spec files at:

• specs/<id>/PRODUCT.md — primary source: user-facing behavior, what and why
• specs/<id>/TECH.md — secondary source: implementation, data model

Read both files if both exist. PRODUCT.md is the primary driver for the docs content.

When reading TECH.md: Before incorporating anything from it, identify content that looks like internal implementation detail — database schema, internal service names, private API endpoints, confidential server architecture. Present these flagged items to the engineer and ask them to confirm what's safe to include in public docs and what should stay internal. Do not include anything marked confidential in the draft.

This confirmation is why the skill requires a present engineer. There is no unattended path: without someone to say what is safe to publish, TECH.md content cannot be drafted at all.

If neither file exists, skip to No-spec fallback.

Step 2: Research the codebase

Before presenting the plan or the outline, use the GitHub CLI to verify as much technical content as possible yourself — reducing what the engineer needs to confirm to only what you genuinely cannot determine from the code.

Things to verify from code:

• Feature flag name: search for a safe feature token from the spec title or ticket. Before any shell use, reduce it to an allowlisted token matching ^[A-Za-z0-9][A-Za-z0-9_-]*$ and skip the shell search if you cannot produce one safely; then run FEATURE_TOKEN="<validated-token>" && gh search code "${FEATURE_TOKEN}" --repo warpdotdev/warp-internal.
• UI strings: search for user-visible button labels, menu item names, or setting names referenced in the spec
• Settings paths: confirm exact Settings menu paths (e.g., **Settings** > **AI** > **Knowledge**)
• CLI commands or keyboard shortcuts mentioned in the spec
• Related features: identify other features that cross-reference this one for "Related pages"
• Engineer to tag: identify the GitHub handle of the engineer who owns the spec.
  • Interactive mode: run gh api user --jq .login to get the handle of the person currently running the skill — use this only when the skill is being invoked directly by the spec engineer. If a docs team member or non-author is running the skill, use the discovery steps below instead.
  • Non-author runs (a docs team member or anyone who did not write the spec): before running any lookup commands, validate that the spec ID contains only alphanumeric characters and hyphens (matching ^[A-Za-z0-9][A-Za-z0-9-]*$). If the spec ID contains any other characters, skip the lookup entirely and use [TODO: tag spec author] as a placeholder. If the spec ID is valid, assign it to SPEC_ID and work through these steps in order, stopping as soon as a handle is found:
    1. Check Co-authored-by: trailers in the commit message — in repos that mirror from a private source (like warp-internal), the sync bot is the commit author but the real author appears in a Co-authored-by: trailer. Extract the first non-bot entry:

       git log --follow -1 --format="%B" -- "specs/${SPEC_ID}/PRODUCT.md" \
         | grep -i "^Co-authored-by:" \
         | grep -v "\[bot\]" \
         | head -1 \
         | grep -oP '<[^>]+>' | tr -d '<>'

       This returns an email (possibly a GitHub noreply address). If the email matches the pattern <userid>+<username>@users.noreply.github.com, extract the handle directly: echo "$EMAIL" | grep -oP '\+\K[^@]+'. If it's a real email, resolve it via gh api "search/users?q=${EMAIL}+in:email" --jq '.items[0].login'.
    2. Parse the synced-from PR URL — some sync bots embed the original PR URL in the commit body (e.g. Synced from warp: https://github.com/warpdotdev/warp/pull/11901). Extract it and fetch the PR author:

       ORIG_PR=$(git log --follow -1 --format="%B" -- "specs/${SPEC_ID}/PRODUCT.md" \
         | grep -oP 'https://github\.com/[^/]+/[^/]+/pull/\d+' | head -1)
       # Extract owner/repo and PR number, then: gh pr view <N> --repo <owner/repo> --json author --jq '.author.login'

    3. Search the origin repo PRs — try the repo that actually owns the code (checking both the public mirror and the private source if accessible):

       gh pr list --search "specs/${SPEC_ID}" --repo warpdotdev/warp-internal --state merged --json author --limit 1 --jq '.[0].author.login'
       # Also try: gh pr list --search "specs/${SPEC_ID}" --repo warpdotdev/warp --state merged --json author --limit 1 --jq '.[0].author.login'

       Skip any result where the login contains [bot].
    4. Fall back to commit author email — only if the email does NOT contain [bot]:

       EMAIL=$(git log --follow -1 --pretty=format:"%ae" -- "specs/${SPEC_ID}/PRODUCT.md")

       If ${EMAIL} is non-empty and bot-free, resolve it to a handle via gh api "search/users?q=${EMAIL}+in:email" --jq '.items[0].login'.
    5. If no handle is found after all steps, use [TODO: tag spec author] as a placeholder in the PR body.

For each claim you verify from code, mark it confirmed. For claims you can't verify (UI behavior not in code, product intent, behavior of unreleased features), flag them as [UNVERIFIED] in the outline — those are the only things the engineer needs to focus on.

Step 3: Present the content design plan and wait

This is the first of two confirmations, and it comes before the outline. Settle who the page is for before deciding what goes in it.

Fill in .agents/templates/content-design-plan.md from the docs repo, using .agents/references/content-design-plan.md for what each field is asking: audience and JTBD, problem, goals, purpose and value, content type, skill and template, and high-impact scenarios with explicit exclusions.

Print it to the terminal, then say:

"Before I outline the page, please confirm this is the right reader and the right job. Correct anything that's off, or say 'looks good' and I'll draft the outline."

Wait for the engineer's reply. Do not produce the outline in the same message. The plan decides the content type, and the content type decides what sections the outline has — an outline shown alongside an unconfirmed plan invites the engineer to anchor on the concrete sections in front of them rather than question the audience above them.

If they change the audience, the content type, or the scope, revise the plan and re-confirm before moving on. Carry the confirmed plan into the PR body in Step 6.

Step 4: Present the outline and wait

Generate a concise outline — no prose — built on the confirmed plan from Step 3. The outline shows what you've confirmed from research and exactly what still needs engineer input.

Print the outline to the terminal in this format:

📄 Docs outline for [Feature name]

PROPOSED PLACEMENT
  Section:  src/content/docs/<section>/   (e.g., agent-platform/cloud-agents/)
  File:     <feature-name>.mdx
  URL:      docs.warp.dev/<path>/<feature-name>

CONTENT SECTIONS
  title:  <Feature name>   (frontmatter; Starlight renders it as the H1)
  Opening paragraph: [1-sentence description of what you'll write]
  ## Key features — [which 2-4 capabilities to highlight as bullets]
  ## How it works — [the conceptual model: what and why, no steps]
  ## <Usage section title> — [e.g., "Creating environments", "Configuring X"]
      Prerequisites: [any prerequisites to list]
      Steps:
        1. [Step description]
        2. [Step description]
        3. [Step description]
        ...
  ## Related pages — [cross-links to suggest]

The sections above are defaults. Adapt the outline to the feature: omit ## How it works if the feature needs no conceptual explanation, add multiple usage sections if the feature has distinct workflows, and collapse ## Key features into the opening paragraph if the feature is simple enough.

VERIFIED FROM CODEBASE ✅
  - [e.g., "Feature flag: `my_feature_flag` confirmed in warp-internal"]
  - [e.g., "Settings path: confirmed as Settings > AI > Agents > Permissions"]

NEEDS YOUR CONFIRMATION ⚠️
  - [e.g., "Step 3 — does the sync trigger automatically or require a manual action?"]
  - [e.g., "Is the 'Export' button visible before the feature flag is enabled?"]

After printing the outline, say:

"I've verified what I could from the codebase. Please check the items marked ⚠️ above and reply with any corrections, or say 'looks good' to proceed."

Wait for the engineer's reply before continuing. Incorporate their feedback, then draft.

If their feedback contradicts the plan confirmed in Step 3 — a different reader, a different content type — revise the plan too rather than letting the two drift apart. The plan travels into the PR body, so a stale one misleads the reviewer.

Step 5: Generate the MDX draft

Generate a complete .mdx file based on the confirmed outline. The output is ready to drop directly into warpdotdev/docs.

Template structure

Use the canonical template for the content type the plan chose, from .agents/templates/ in the docs repo — feature-doc.md, conceptual.md, procedural.md, reference.md, troubleshooting.md, quickstart.md, or guide-page.md. Those are the source of truth and they carry their own field-by-field guidance. The sketch below shows the shape of the most common one, feature documentation, so you know what to expect; it is not a substitute for reading the real template.

Two rules the templates enforce that are easy to get wrong from memory: the page title goes in frontmatter, not a body H1 (Starlight renders the frontmatter title as the H1, so a body H1 duplicates it), and every bracketed instruction must be deleted before the page ships.

---
title: [Feature name — sentence case]
description: >-
  [1-2 sentence standalone summary. Lead with the user benefit. Include the
  feature name and a key term or two so it works as a search result snippet.]
---

[Opening paragraph: what the feature does and its primary benefit.
1-3 sentences. Lead with what the user can accomplish, not the implementation.]

:::note
[Optional: key context the reader needs upfront — a prerequisite, a limitation,
or when NOT to use this feature. Delete this callout if nothing applies.]
:::

## Key features

* **Feature A** - What it does and why it matters to the user.
* **Feature B** - What it does and why it matters to the user.

## How it works

[CONCEPTUAL section: explain system behavior, data flow, or architecture.
Answer "what" and "why" before "how." Define any new terms when they
first appear. Do NOT include step-by-step procedures in this section —
keep conceptual and procedural content clearly separated.]

## [Usage section title]

[PROCEDURAL section: motivate the task first, then give numbered steps.
Briefly explain why the user is doing this before telling them how.]

### Prerequisites

* **[Prerequisite]** - What it is and where to get it. See [full reference](link-here).

### [Task name — sentence case, e.g., "Create an environment with the CLI"]

1. First step. Expected outcome if not obvious.
2. Second step.
3. Third step.

## Related pages

* [Related feature](../path/to/page.md)
* [Deeper guide](../path/to/guide.md)

Style rules — apply exactly

These conventions come from the Warp docs style guide and must be followed:

Headings

• Sentence case for all headings: capitalize only the first word and proper feature names
• Proper feature names keep their capitalization: "Agent Mode", "Warp Drive", "Oz", "Command Palette"
• ✅ ## How it works — ❌ ## How It Works
• ✅ ## Agent Mode settings — ❌ ## Agent mode settings

Lists

• Bold term + dash + description: * **Term** - Description
• Never use a colon: ❌ * **Term**: Description

UI elements and paths

• Bold for buttons, links, menu items: Click **Save**, not Click `Save`
• Bold each segment in a Settings path, leave > plain: **Settings** > **AI** > **Knowledge**

Voice and tone

• Second person: "you can," "allows you to"
• Active voice: "Warp indexes your codebase" — not "your codebase is indexed"
• Avoid "simple," "easy," "just" — these dismiss the reader's experience
• Present tense for how things work; imperative for instructions

Frontmatter description

• Write as a standalone summary that works as a search result snippet
• Lead with user benefit, include the feature name and key terms
• ✅ Environments ensure your cloud agents run with a consistent toolchain. Learn when to use environments and how to configure them.
• ❌ This page describes environments.

Callout syntax (Astro Starlight)

• :::note — supplemental context, tips
• :::caution — caveats, limitations
• :::danger — destructive or irreversible actions
• :::tip — helpful hints and best practices

What to leave as [TODO: docs reviewer — ...] placeholders

• Screenshots where computer use fails the quality gate, is unavailable, or the feature isn't yet shipped
• Video/GIF embeds
• Exact Settings path if the feature hasn't shipped yet
• Final URL path (docs team confirms placement)
• Any behavior that remained unverified after engineer confirmation

Step 5.5: Capture screenshots via computer use (if available)

After generating the draft, attempt to capture screenshots for any [TODO: docs reviewer — screenshot needed] placeholders using computer use. This step is optional — only run it if the computer_use tool is available. If computer use is unavailable, leave all placeholders as-is.

Decide which screenshots to attempt

Only attempt screenshots where all of the following are true:

• The feature is already shipped (not behind a feature flag or unreleased)
• The UI state can be reliably navigated to programmatically
• The placeholder specifies a concrete UI surface (not vague like "show the feature working")

Skip screenshots that require account-specific state, specific data, or content that would expose sensitive information.

Pre-capture setup

Before taking any screenshot:

1. Launch Warp at a consistent window size (use the warp-internal-computer-use skill for launch guidance)
2. Navigate to the relevant UI surface or trigger the relevant feature state
3. Wait for all animations to complete and the UI to be fully settled
4. Dismiss any unrelated popups, notifications, or toasts that aren't part of the feature being documented
5. Close any sidebar panels or panes not relevant to this screenshot
6. Verify no sensitive data is visible: check for tokens, API keys, private repo names, customer workspace data, email addresses, or personal information. If any is visible, do not take the screenshot.