Write Tech Spec

This generates a TECH.md file that bridges product intent and implementation reality. It forces you to inspect the actual codebase before writing, grounds the spec in real module boundaries and data flow, and maps product behaviors to concrete tests. The structure scales from 40-line plans for focused changes to longer docs for cross-cutting work. What I like here is the Parallelization section: it pushes you to think about sub-agents upfront, with specific worktrees and branch strategies rather than vague concurrency hopes. Use it when the implementation has architectural choices worth reviewing before code lands, or when multiple modules need coordination. Skip it for straightforward fixes where the code is the clearest explanation.

skills.sh installs: 28.8K
GitHub stars: 684
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add warpdotdev/common-skills --skill write-tech-spec --agent claude-code

Installs into .claude/skills of the current project.

Files

write-tech-spec

Write a TECH.md spec for a significant feature in Warp.

Overview

The tech spec should translate product intent into an implementation plan that fits the existing codebase, documents architectural choices, and makes the work easier for agents to execute and reviewers to evaluate.

Write specs to specs/<id>/TECH.md, where <id> is one of:

a Linear ticket number (e.g. specs/APP-1234/TECH.md)
a GitHub issue id, prefixed with gh- (e.g. specs/gh-4567/TECH.md)
a short kebab-case feature name (e.g. specs/vertical-tabs-hover-sidecar/TECH.md)

Match the id used by the sibling PRODUCT.md when one exists. specs/ should contain only id-named directories as direct children.

Ticket / issue references are optional. If the user has a Linear ticket or GitHub issue, use its id. If they don't, ask them for a feature name to use as the directory. Only create a new Linear ticket or GitHub issue when the user explicitly asks for one; in that case use the Linear MCP tools or gh CLI respectively (and ask_user_question if team, labels, or repo are unclear).