Add write-feature-docs skill by rachaelrenk · Pull Request #26 · warpdotdev/common-skills

rachaelrenk · 2026-06-12T19:34:59Z

Summary

Adds two companion skills for the eng-owned docs workflow:

write-feature-docs -- engineer-facing skill that drafts the first ~80% documentation page for a new Warp feature from its PRODUCT.md and/or TECH.md spec
scan-new-specs -- ambient scheduled skill that scans warp-internal and warp-server for recently merged specs without a corresponding docs PR, and posts Slack nudges to #growth-docs

Platform engineers run write-feature-docs from warp-internal or warp-server alongside the existing write-product-spec / write-tech-spec skills. scan-new-specs is designed to run as a scheduled Oz agent (suggested: Mon/Wed/Fri at 9am PT) to catch docs gaps automatically.

How `write-feature-docs` works

Reads specs/<id>/PRODUCT.md + optionally TECH.md
Generates a concise outline (proposed placement, content sections, procedural steps, key terms) and prints it to the terminal
Engineer confirms accuracy via free-form terminal reply
Generates a complete ~80% MDX draft following Warp docs conventions
Tells the engineer how to open a draft PR in warpdotdev/docs

No-spec fallback uses Ask_User_Question to interview the engineer when no spec exists.

How `scan-new-specs` works

Uses gh CLI to find merged PRs in warp-internal/warp-server from the last N days (default: 3) that added a specs/*/PRODUCT.md
For each spec found, checks warpdotdev/docs for any open/merged/draft PR covering it
Posts a grouped Slack nudge to #growth-docs for uncovered specs
Prints to the terminal instead if the Slack webhook URL is not configured

Key design decisions

Outline before draft -- engineer validates technical accuracy on a concise outline, not a full document
Terminal reply for outline confirmation -- lower friction than a multi-choice prompt for free-form corrections
Style rules baked in -- sentence case headings, bold+dash list format, bold UI elements, active voice, frontmatter description standards from warpdotdev/docs AGENTS.md
[TODO: docs reviewer] placeholders -- skill marks screenshots, video embeds, and unconfirmed UI paths so the docs team knows what to fill in
PR-based deduplication for scan-new-specs -- a spec stops generating nudges once any docs PR is opened (even a draft)

Feedback requested from reviewers

1. The outline step (in write-feature-docs)
The current design shows engineers a concise outline first and asks them to confirm before generating the full draft. This is meant to keep the accuracy check lightweight.

Does this feel like the right tradeoff, or would engineers prefer to skip the outline and review the full ~80% draft directly?
Is the ~2-5-minute outline review actually lower friction, or does it add a step engineers will want to bypass?

2. The automated trigger (scan-new-specs)

Does surfacing nudges in #growth-docs feel right, or should they go somewhere the engineer is more likely to see them (e.g., a dedicated #docs-nudges channel, or a GitHub comment on their spec PR)?
Is a Mon/Wed/Fri cadence appropriate, or would a different frequency (daily, weekly) reduce noise without missing things?
Should the nudge @-mention the engineer by GitHub username, or just surface the spec to the docs team to follow up?
Is there a better mechanism than Slack (e.g., creating a GitHub issue in warpdotdev/docs)?

Co-Authored-By: Oz oz-agent@warp.dev

Engineer-facing skill that drafts the first ~80% documentation page for a new Warp feature from its PRODUCT.md and/or TECH.md spec. Part of the eng-owned docs workflow: reads the feature spec, generates a concise outline for the engineer to confirm technical accuracy, then produces a complete MDX draft ready for a draft PR to warpdotdev/docs. Includes: - Outline generation with terminal-based confirmation (no Ask_User_Question for the main flow — free-form reply keeps it low friction for engineers) - No-spec fallback via Ask_User_Question interview - Warp docs style rules baked in (sentence case headings, bold+dash lists, UI element formatting, active voice, frontmatter description standards) - Handoff instructions pointing engineers to warpdotdev/docs draft PR Companion to write-product-spec and write-tech-spec. Co-Authored-By: Oz <oz-agent@warp.dev>

oz-for-oss · 2026-06-12T19:35:12Z

@rachaelrenk

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR adds a new write-feature-docs common skill that turns PRODUCT.md and optional TECH.md specs into an outline and MDX draft for Warp feature documentation.

Concerns

The no-spec fallback references Ask_User_Question, but existing common-skills guidance uses ask_user_question; this can break the interactive fallback path when no spec files exist.
The handoff instructions tell engineers to open public docs draft PRs for feature docs by default, which can disclose unreleased feature details before launch approval.
README.md was not updated to list write-feature-docs under the current skills, so repository-level discovery will be stale.

Security

The docs handoff should not default to public PRs unless the feature is already safe to discuss publicly.

Verdict

Found: 0 critical, 2 important, 1 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>

Scheduled Oz agent skill that scans warp-internal and warp-server for recently merged PRODUCT.md specs without a corresponding docs PR in warpdotdev/docs. Posts Slack nudges to #growth-docs for each gap. This is the automated trigger companion to write-feature-docs — removes the dependency on engineers remembering to kick off the docs workflow. Behavior: - Looks back N days (default: 3) for merged PRs that added specs/*/PRODUCT.md - Checks warpdotdev/docs for any open/merged/draft PR covering each spec - Posts grouped Slack nudge(s) to #growth-docs for uncovered specs - Falls back to stdout if SLACK_WEBHOOK_URL is not configured - Prints a run summary every time Suggested schedule: Mon/Wed/Fri at 9am PT. Note: deduplication is PR-based (no persistent state). A spec stops generating nudges once any docs PR is opened, even a draft. Co-Authored-By: Oz <oz-agent@warp.dev>

hongyi-chen · 2026-06-20T05:32:39Z

@@ -0,0 +1,138 @@
+---
+name: scan-new-specs
+description: Scan warp-internal and warp-server for recently merged PRODUCT.md specs that don't yet have a corresponding docs PR in warpdotdev/docs, then post Slack nudges to a configured channel. Designed to run as a scheduled Oz ambient agent (e.g., every 2-3 days). Use when setting up the automated docs trigger, running a manual docs coverage sweep, or checking whether any new specs are missing documentation.


this should be the open-source warp repo (not warp-internal)

hongyi-chen · 2026-06-20T05:33:26Z

@@ -0,0 +1,213 @@
+---
+name: write-feature-docs
+description: Draft the first ~80% documentation page for a new Warp feature from its PRODUCT.md and/or TECH.md spec. Use when an engineer has written a spec and needs to produce a first-pass MDX draft for the warpdotdev/docs repo. Also handles features without specs via an interactive interview. Invoke this skill whenever an engineer mentions writing docs for a feature, drafting a docs page, creating feature documentation, starting the eng-docs workflow, or converting a spec into documentation. Works from warp-internal or warp-server.


i don't think you need to mention 80% -- i'd rather the agent try to handle 100% and miss 20% than tell the agent to aim for 80%, if that makes sense

hongyi-chen · 2026-06-20T05:33:58Z

+- `:::tip` — confirmation of expected outcomes
+
+**What to leave as placeholders**
+Mark these with `[TODO: docs reviewer — ...]` in the draft:


is there some way to use computer use to generate screenshots such that the reviewer doesnt need to do this?

hongyi-chen · 2026-06-20T05:37:55Z

+
+Draft the first ~80% documentation page for a new Warp feature. You read the feature's spec, generate a concise outline for the engineer to confirm, then produce a complete MDX draft ready for a draft PR to `warpdotdev/docs`.
+
+The engineer's job is to verify **technical accuracy** — not polish prose, fix formatting, or know docs conventions. Your job is everything else.


this should also be the agent's job to verify as much as possible the technical accuracy, such that the eng has to do minimal work

hongyi-chen · 2026-06-20T05:38:26Z

+2. Generate a concise outline and present it in the terminal
+3. Engineer confirms the outline is accurate (or replies with corrections)
+4. Generate the full ~80% MDX draft from the confirmed outline
+5. Tell the engineer how to submit it as a draft PR to `warpdotdev/docs`


for 5. it should automatically generate the PR and tag one of rachael, petra, or myself

hongyi-chen · 2026-06-20T05:39:43Z

+  File:     <feature-name>.mdx
+  URL:      docs.warp.dev/<path>/<feature-name>
+
+CONTENT SECTIONS


can you please verify with the engineer if some are internal implementation details that are not worth mentioning in the docs?

especially if there is any private about our server that we should keep confidential

hongyi-chen · 2026-06-20T05:40:39Z

+
+If `specs/<id>/PRODUCT.md` and `specs/<id>/TECH.md` don't exist, use `ask_user_question` to interview the engineer. Ask about:
+
+1. What this feature does in one sentence


before the agent interviews the engineer, it should do as much as possible to research itself (potentially using multi-agent orchestration), and confirm with the eng

rachaelrenk self-assigned this Jun 12, 2026

oz-for-oss Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread .agents/skills/write-feature-docs/SKILL.md Outdated

Comment thread .agents/skills/write-feature-docs/SKILL.md

hongyi-chen and others added 2 commits June 16, 2026 11:05

Apply suggestion from @oz-for-oss[bot]

33e983e

Co-authored-by: oz-for-oss[bot] <277970191+oz-for-oss[bot]@users.noreply.github.com>

rachaelrenk requested review from hongyi-chen and petradonka June 18, 2026 17:22

rachaelrenk commented Jun 18, 2026

View reviewed changes

Comment thread .agents/skills/scan-new-specs/SKILL.md Outdated

Apply suggestion from @rachaelrenk

fbab782

hongyi-chen reviewed Jun 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add write-feature-docs skill#26

Add write-feature-docs skill#26
rachaelrenk wants to merge 4 commits into
mainfrom
docs/write-feature-docs-skill

rachaelrenk commented Jun 12, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

oz-for-oss Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hongyi-chen Jun 20, 2026

Uh oh!

hongyi-chen Jun 20, 2026

Uh oh!

hongyi-chen Jun 20, 2026

Uh oh!

hongyi-chen Jun 20, 2026

Uh oh!

hongyi-chen Jun 20, 2026

Uh oh!

hongyi-chen Jun 20, 2026

Uh oh!

hongyi-chen Jun 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		Draft the first ~80% documentation page for a new Warp feature. You read the feature's spec, generate a concise outline for the engineer to confirm, then produce a complete MDX draft ready for a draft PR to `warpdotdev/docs`.

		The engineer's job is to verify technical accuracy — not polish prose, fix formatting, or know docs conventions. Your job is everything else.


		If `specs/<id>/PRODUCT.md` and `specs/<id>/TECH.md` don't exist, use `ask_user_question` to interview the engineer. Ask about:

		1. What this feature does in one sentence

Conversation

rachaelrenk commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How write-feature-docs works

How scan-new-specs works

Key design decisions

Feedback requested from reviewers

Uh oh!

oz-for-oss Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Security

Verdict

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hongyi-chen Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rachaelrenk commented Jun 12, 2026 •

edited

Loading

How `write-feature-docs` works

How `scan-new-specs` works

oz-for-oss Bot commented Jun 12, 2026 •

edited

Loading