write-feature-docs

Name: write-feature-docs
Author: warpdotdev

146stars1forks

How to install write-feature-docs?

warpdotdev/common-skills/write-feature-docs

$npx -y skills add warpdotdev/common-skills --skill write-feature-docs

Installs into the current project.

Summary

Draft a complete 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 by researching the codebase fi

Files · 1

View on GitHub

SKILL.md

1	# write-feature-docs
2
3	Draft a complete documentation page for a new Warp feature. You read the feature's spec, verify technical claims by researching the codebase yourself, present a concise outline for the engineer to confirm, then produce a complete MDX draft and open a draft PR in `warpdotdev/docs` — tagging the docs team for review.
4
5	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.
6
7	## The workflow
8
9	1. Find and read the spec files
10	2. Research the codebase to verify technical claims — minimize what the engineer needs to check
11	3. Generate a concise outline and wait for engineer confirmation
12	4. Generate the complete MDX draft
13	4.5. Attempt screenshot capture via computer use (if available)
14	5. Open a draft PR in `warpdotdev/docs` and tag the docs team
15
16	---
17
18	## Step 1: Find and read the spec
19
20	Ask the engineer for the spec ID if they haven't provided it. The spec ID is one of:
21	- A Linear ticket number: `APP-1234`, `REMOTE-1234`, `QUALITY-408`
22	- A GitHub issue (prefixed with `gh-`): `gh-4567`
23	- A short kebab-case feature name: `vertical-tabs-hover-sidecar`
24
25	Look for the spec files at:
26	- `specs/<id>/PRODUCT.md` — primary source: user-facing behavior, what and why
27	- `specs/<id>/TECH.md` — secondary source: implementation, data model
28
29	Read both files if both exist. `PRODUCT.md` is the primary driver for the docs content.
30
31	When reading `TECH.md`: (Interactive mode only — in ambient mode, treat all TECH.md-derived content as internal without review; see [Ambient mode](#ambient-mode-called-by-scan-new-specs).) 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.
32
33	If neither file exists, skip to [No-spec fallback](#no-spec-fallback).
34
35	---
36
37	## Step 2: Research the codebase
38
39	Before presenting 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.
40
41	Things to verify from code:
42	- 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`.
43	- UI strings: search for user-visible button labels, menu item names, or setting names referenced in the spec
44	- Settings paths: confirm exact Settings menu paths (e.g., `Settings > AI > Knowledge`)
45	- CLI commands or keyboard shortcuts mentioned in the spec
46	- Related features: identify other features that cross-reference this one for "Related pages"
47	- Engineer to tag: identify the GitHub handle of the engineer who owns the spec.
48	- 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.
49	- Ambient mode and non-author interactive runs: 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:
50	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:
51	```bash
52	git log --follow -1 --format="%B" -- "specs/${SPEC_ID}/PRODUCT.md" \
53	\| grep -i "^Co-authored-by:" \
54	\| grep -v "\[bot\]" \
55	\| head -1 \
56	\|

People who liked this also viewed

6 picks

Type

write-feature-docs

146stars1forks

View on GitHub

How to install write-feature-docs?

warpdotdev/common-skills/write-feature-docs

$npx -y skills add warpdotdev/common-skills --skill write-feature-docs

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# write-feature-docs
2
3	Draft a complete documentation page for a new Warp feature. You read the feature's spec, verify technical claims by researching the codebase yourself, present a concise outline for the engineer to confirm, then produce a complete MDX draft and open a draft PR in `warpdotdev/docs` — tagging the docs team for review.
4
5	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.
6
7	## The workflow
8
9	1. Find and read the spec files
10	2. Research the codebase to verify technical claims — minimize what the engineer needs to check
11	3. Generate a concise outline and wait for engineer confirmation
12	4. Generate the complete MDX draft
13	4.5. Attempt screenshot capture via computer use (if available)
14	5. Open a draft PR in `warpdotdev/docs` and tag the docs team
15
16	---
17
18	## Step 1: Find and read the spec
19
20	Ask the engineer for the spec ID if they haven't provided it. The spec ID is one of:
21	- A Linear ticket number: `APP-1234`, `REMOTE-1234`, `QUALITY-408`
22	- A GitHub issue (prefixed with `gh-`): `gh-4567`
23	- A short kebab-case feature name: `vertical-tabs-hover-sidecar`
24
25	Look for the spec files at:
26	- `specs/<id>/PRODUCT.md` — primary source: user-facing behavior, what and why
27	- `specs/<id>/TECH.md` — secondary source: implementation, data model
28
29	Read both files if both exist. `PRODUCT.md` is the primary driver for the docs content.
30
31	When reading `TECH.md`: (Interactive mode only — in ambient mode, treat all TECH.md-derived content as internal without review; see [Ambient mode](#ambient-mode-called-by-scan-new-specs).) 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.
32
33	If neither file exists, skip to [No-spec fallback](#no-spec-fallback).
34
35	---
36
37	## Step 2: Research the codebase
38
39	Before presenting 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.
40
41	Things to verify from code:
42	- 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`.
43	- UI strings: search for user-visible button labels, menu item names, or setting names referenced in the spec
44	- Settings paths: confirm exact Settings menu paths (e.g., `Settings > AI > Knowledge`)
45	- CLI commands or keyboard shortcuts mentioned in the spec
46	- Related features: identify other features that cross-reference this one for "Related pages"
47	- Engineer to tag: identify the GitHub handle of the engineer who owns the spec.
48	- 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.
49	- Ambient mode and non-author interactive runs: 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:
50	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:
51	```bash
52	git log --follow -1 --format="%B" -- "specs/${SPEC_ID}/PRODUCT.md" \
53	\| grep -i "^Co-authored-by:" \
54	\| grep -v "\[bot\]" \
55	\| head -1 \
56	\|

People who liked this also viewed

6 picks

Type