Add write-feature-docs skill#26
Conversation
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>
|
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 Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
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 usesask_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.mdwas not updated to listwrite-feature-docsunder 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>
| @@ -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. | |||
There was a problem hiding this comment.
this should be the open-source warp repo (not warp-internal)
| @@ -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. | |||
There was a problem hiding this comment.
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
| - `:::tip` — confirmation of expected outcomes | ||
|
|
||
| **What to leave as placeholders** | ||
| Mark these with `[TODO: docs reviewer — ...]` in the draft: |
There was a problem hiding this comment.
is there some way to use computer use to generate screenshots such that the reviewer doesnt need to do this?
|
|
||
| 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. |
There was a problem hiding this comment.
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
| 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` |
There was a problem hiding this comment.
for 5. it should automatically generate the PR and tag one of rachael, petra, or myself
| File: <feature-name>.mdx | ||
| URL: docs.warp.dev/<path>/<feature-name> | ||
|
|
||
| CONTENT SECTIONS |
There was a problem hiding this comment.
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
|
|
||
| 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 |
There was a problem hiding this comment.
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
2 participants
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 itsPRODUCT.mdand/orTECH.mdspecscan-new-specs-- ambient scheduled skill that scanswarp-internalandwarp-serverfor recently merged specs without a corresponding docs PR, and posts Slack nudges to#growth-docsPlatform engineers run
write-feature-docsfromwarp-internalorwarp-serveralongside the existingwrite-product-spec/write-tech-specskills.scan-new-specsis designed to run as a scheduled Oz agent (suggested: Mon/Wed/Fri at 9am PT) to catch docs gaps automatically.How
write-feature-docsworksspecs/<id>/PRODUCT.md+ optionallyTECH.mdwarpdotdev/docsNo-spec fallback uses
Ask_User_Questionto interview the engineer when no spec exists.How
scan-new-specsworksghCLI to find merged PRs inwarp-internal/warp-serverfrom the last N days (default: 3) that added aspecs/*/PRODUCT.mdwarpdotdev/docsfor any open/merged/draft PR covering it#growth-docsfor uncovered specsKey design decisions
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 inscan-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.
2. The automated trigger (
scan-new-specs)#growth-docsfeel right, or should they go somewhere the engineer is more likely to see them (e.g., a dedicated#docs-nudgeschannel, or a GitHub comment on their spec PR)?warpdotdev/docs)?Co-Authored-By: Oz oz-agent@warp.dev