draft-guide

name	draft_guide
description	Draft a new guide page for the Guides section (src/content/docs/guides/). Use for practical, task-oriented walkthroughs that help developers accomplish a specific goal — like setting up a tool, completing a workflow, or learning a technique. Guides focus on the "how" with real prompts and reproducible results, targeting non-branded search queries.

Draft guide page

Draft a practical guide that walks a developer through accomplishing a specific goal.

Workflow

Follow the workflow in .agents/skills/draft_docs/SKILL.md, using the guide template at .agents/templates/guide-page.md.

Guide pages live in src/content/docs/guides/ (the Guides Astro Starlight space), not in the main product reference sections. When placing the file, use these directories:

• src/content/docs/guides/agent-workflows/ — Using coding agents to explain code, review PRs, run parallel tasks, and attach session context
• src/content/docs/guides/configuration/ — Rules, agent profiles, saved prompts, and related setup guides
• src/content/docs/guides/external-tools/ — MCP servers, third-party tools, and integrations
• src/content/docs/guides/build-an-app-in-warp/ — End-to-end app builds from start to finish
• src/content/docs/guides/devops/ — Cloud logs, Docker, Kubernetes, testing, and database optimization
• src/content/docs/guides/frontend/ — Building and refining UI components with coding agents

The sidebar nav is defined in src/sidebar.ts, which organizes guides into topic-based sections. When adding a new guide, place the file in the appropriate directory above and add the nav entry under the matching section in src/sidebar.ts:

• Getting started — First steps with Warp: setup, appearance, key features
• Agent workflows — Using coding agents to explain code, review PRs, run parallel tasks
• Configuration — Rules, agent profiles, saved prompts, monorepo sync
• External tools & integrations — MCP servers, Ollama, third-party tool setup
• Build an app in Warp — End-to-end app builds with AI coding workflows
• DevOps & infrastructure — Cloud logs, Docker, Kubernetes, testing, database optimization
• Frontend & UI — Building and refining UI components with coding agents

Content type rules

These rules are specific to guide pages (from the "Drafting by content type" section of AGENTS.md):

• Titles should be task-oriented and read like a search query. Use shortened titles in the Astro Starlight nav and full descriptive titles in the article H1.
• For SEO: capture the non-branded query. Write the title a developer would actually search for, not "How to do X in Warp." Example: "How to set up Claude Code" not "How to set up Claude Code in Warp."
• All procedural rules apply (focused steps, motivate steps, expected outcomes).
• Link to relevant feature documentation in the main docs (docs/) where concepts need deeper explanation.
• When a guide has a companion video, the written content should stand alone.
• The optional Productivity tips section should showcase Warp features as natural extensions of the workflow — not as a separate pitch.

SEO and AEO optimization

When drafting a guide, check for relevant SEO and AEO data:

1. Create an AEO brief when source data drives the guide. If the guide request mentions AEO, Peec, AI search prompts, answer-engine visibility, search-query vocabulary, or content gaps, read .agents/skills/aeo_brief/SKILL.md before drafting. Use the brief to map source-data language to natural docs language and to decide whether this should be a new guide or an update to an existing guide.
2. Use SEO and AEO data to inform titles, descriptions, and content coverage. The docs-seo-audit skill (.agents/skills/docs-seo-audit/) can identify technical SEO issues.
3. Write the frontmatter description to include the primary target keyword naturally. Keep under 160 characters.
4. Frame the title for non-branded search. The page should answer the user's actual question, with Warp features as the natural solution in the guide body.
5. Avoid keyword stuffing. Preserve high-intent query terms only where they make the guide clearer or more discoverable. Rewrite awkward source-data phrasing into natural developer language.

Oz CLI and GitHub Actions accuracy

When a guide includes Oz CLI commands or GitHub Actions workflows using warpdotdev/oz-agent-action:

• Verify Oz CLI commands against /reference/cli/. Do not infer flag names or argument formats. Use only flags documented in the CLI reference. When in doubt, link to the reference page instead of showing a command.
• oz-agent-action input format: warp_api_key is a with: input to the action, not an env: variable. GITHUB_TOKEN goes in env:. The correct pattern is:

  - uses: warpdotdev/oz-agent-action@v1
    with:
      skill: SKILL_NAME
      environment: YOUR_OZ_ENVIRONMENT_SLUG
      warp_api_key: ${{ secrets.WARP_API_KEY }}
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  

• Every GitHub Actions workflow example that performs write operations must include a permissions: block at the workflow level, before jobs:. Use the minimum permissions for the task:
  • Triage (label/comment on issues): issues: write
  • Spec/implementation (push branches, open PRs): contents: write, pull-requests: write
  • Review (post PR comments): pull-requests: write Without an explicit permissions: block, workflows fail in repositories with restricted default permissions.
• oz secret create must not include --value on the command line. The --value flag exposes secrets in shell history and process arguments. Show oz secret create --name SECRET_NAME and note that the CLI prompts for the value interactively.
• Slash commands (/command-name) in standalone code fences should use bash as the language identifier, consistent with the docs style guide for terminal input.

Third-party tool accuracy

When a guide documents a third-party tool (Claude Code, Codex, OpenCode, etc.):

• Always verify claims against the tool's official documentation. Do not infer implementation details (programming language, architecture, framework) from GitHub repo language stats or third-party blog posts. These are frequently wrong or outdated.
• Link to official docs rather than reproducing install steps. Installation commands, plan names, pricing, model names, and permission/approval modes change frequently. Link to the tool's official quickstart or setup page and keep the guide focused on the Warp-specific workflow.
• If you must include specific details (e.g., exact commands, plan tier names, approval mode names), fetch and verify them from the tool's current official documentation before publishing. Add a note or link so readers can check for updates.
• Do not include pricing information for third-party tools — it changes and is hard to keep evergreen.
• Avoid brand-specific product mentions that date quickly or exclude users. Use generic terms: "Bluetooth audio device" not "AirPods", "code editor" not a specific IDE unless the guide is about that IDE.
• Avoid specific model version numbers (e.g., "GPT-5.4") unless directly relevant. Link to the tool's model documentation instead.

Link verification

Before adding any internal documentation link:

• Verify the target page exists. Check src/sidebar.ts for sidebar entries and the corresponding file under src/content/docs/ to confirm the page exists. Do NOT generate plausible-looking URLs to pages that don't exist.
• If a target page is planned but not yet published, link to the closest existing page and add a TODO comment with the intended future path: <!-- TODO: Update to [future-path] once [page name] is live -->
• For third-party CLI agent pages, the current paths are under src/content/docs/agent-platform/cli-agents/ (e.g., claude-code.mdx, codex.mdx, opencode.mdx).

Cross-linking

Every guide should link to:

• At least one other guide in the Guides section
• Relevant feature documentation in the main docs (src/content/docs/ or src/content/docs/agent-platform/)
• If applicable, pages in the Third-Party CLI Agents section (src/content/docs/agent-platform/cli-agents/)

Pre-handoff self-review

Before presenting a guide draft, do an editorial pass focused on the issues that often create avoidable review back-and-forth:

• Scannability - Break dense procedure sections into numbered steps, short bullets, or concise subsections. Avoid long H2 sections that mix multiple actions.
• Usefulness - Confirm the guide teaches a real workflow and does not become a junk drawer of loosely related AEO topics.
• Vocabulary translation - Check that Peec/search phrasing is translated into natural docs language while preserving accurate high-intent terms like third-party product names.
• Product and UI names - Check product surfaces against .agents/references/terminology.md and validate UI paths or command names when the guide depends on exact navigation.
• Human-review questions - Surface unresolved questions about product behavior, placement, or terminology instead of hiding them in the draft.

Existing examples

Read 2-3 of these strong examples to match the existing pattern:

• src/content/docs/guides/external-tools/sentry-mcp-fix-sentry-error-in-empower-website.mdx
• src/content/docs/guides/build-an-app-in-warp/building-a-real-time-chat-app-github-mcp-railway.mdx
• src/content/docs/guides/agent-workflows/how-to-explain-your-codebase-using-warp-rust-codebase.mdx