Tessl • The management layer for AI agent skills

SkillPublic

write-feature-docs

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 first. 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. Requires an interactive session with the engineer present - it confirms a content design plan, then an outline, before drafting, and cannot run unattended. For automated, release-triggered docs, use the missing_docs skill in warpdotdev/docs instead. Works from warp-internal or warp-server.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

77%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A highly actionable, well-sequenced workflow with genuine validation checkpoints and executable commands throughout. Its weaknesses are verbosity from repeated justifications and a monolithic single-file structure that inlines large blocks (screenshot protocol, style guide, MDX template) better suited to reference files.

Suggestions

State the plan-before-outline rationale once (in the workflow overview) and reduce Steps 3 and 4 to the operational instruction plus the confirmation prompt, cutting the three repeated explanations of anchoring risk.

Move the Step 5.5 screenshot capture protocol, the style-rules section, and the MDX template into references/ files (e.g., references/screenshot-protocol.md, references/style-rules.md) and link to them from the main workflow.

Condense the five-step engineer-handle discovery chain into a reference file as well, keeping only the validation rule and the placeholder fallback inline in Step 2.

Dimension	Reasoning	Score
Conciseness	The operational content (gh/git commands, checklists, templates) earns its tokens, but the plan-before-outline rationale is re-explained four times (workflow intro, Step 3 twice, Step 4) and the file runs ~460 lines where tightening would cut substantial duplication without losing guidance.	3 / 5
Actionability	Guidance is fully executable: exact shell pipelines for the engineer-handle discovery, validated feature-token handling, verbatim prompts to print, a complete MDX template, concrete PR-body rules, and a copy-paste `gh pr create --draft --body-file` command.	5 / 5
Workflow Clarity	A clearly sequenced 1-6 workflow with two explicit human confirmation checkpoints, error-recovery loops (revise and re-confirm the plan, retry-once screenshot capture, discard on failure), and validation gates at both the screenshot quality gate and the Step 6 docs-worthiness check.	5 / 5
Progressive Disclosure	The file is well-sectioned and its out-of-bundle template pointers (.agents/templates/, .agents/references/) are clearly signaled, but there is no bundle at all: the ~120-line screenshot protocol, the full style-rules section, and the MDX template are inlined in SKILL.md when they clearly belong in separate reference files.	3 / 5
	Total	16 / 20 Passed

Description

96%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

An excellent description: concrete capabilities, a comprehensive set of natural trigger phrases, and explicit what/when guidance, with the interactive-session requirement and the missing_docs redirect adding useful boundary information. The only deduction is minor intra-family trigger overlap from fairly generic docs phrasing.

Dimension	Reasoning	Score
Specificity	"Draft a complete documentation page for a new Warp feature from its PRODUCT.md and/or TECH.md spec" plus "researching the codebase first" and "confirms a content design plan, then an outline, before drafting" list multiple concrete actions with comprehensive coverage of the skill's behavior, including the no-spec fallback.	5 / 5
Completeness	Both questions are answered explicitly: the what is "Draft a complete documentation page... from its PRODUCT.md and/or TECH.md spec" and the when is a dedicated "Use when an engineer has written a spec" clause plus an "Invoke this skill whenever" enumeration, going beyond weak implication.	5 / 5
Trigger Term Quality	Triggers span the natural phrasings an engineer would use — "writing docs for a feature, drafting a docs page, creating feature documentation, starting the eng-docs workflow, or converting a spec into documentation" — with synonyms (docs/documentation/draft) and concrete file artifacts (MDX, PRODUCT.md, TECH.md).	5 / 5
Distinctiveness Conflict Risk	The niche (spec-to-docs for the warpdotdev/docs repo) is clear and the automated case is explicitly redirected to missing_docs, but broad phrases like "writing docs for a feature" carry minor overlap risk with the closely related spec-writing and general documentation skills in the same family.	4 / 5
	Total	19 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 1 missing, 2 suspicious	Warning

	Total	15 / 16 Passed

Repository: warpdotdev/common-skills
Path: .agents/skills/write-feature-docs/SKILL.md
Revision: 8792394

Reviewed: 1 month ago

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

write-feature-docs

Table of Contents

Is this your skill?