write-tech-spec skill (Warp): write TECH.md implementation plans from your code

Warp's skill that makes your agent research your codebase and write a TECH.md: the plan, tests and parallel work for a feature.

Installs: 28.7K; on skills.sh
Stars: 644; on GitHub
Updated: Oct 2026; last repo commit

write-tech-spec loads when you ask for a technical spec, an implementation plan or an architecture doc tied to a product spec. Your agent reads PRODUCT.md if there is one, inspects the relevant code, and notes the current commit with git rev-parse HEAD so file references can be pinned to it.

It writes specs/<id>/TECH.md with four sections: Context, Proposed changes, Testing and validation, and Parallelization. Optional sections are an end-to-end flow, diagrams, risks and follow-ups. The wording is written for Warp, and the parallelization section only applies when a run_agents tool is available.

Good for

Engineers planning a change that spans several modules
Reviewers who would rather review the plan than the raw code
Teams that already have a PRODUCT.md and need the implementation plan

Install write-tech-spec

Claude Code

Copy this prompt.

Install the write-tech-spec skill in Claude Code. Run this command:

npx skills add https://github.com/warpdotdev/common-skills --skill write-tech-spec

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Write a TECH.md spec for a significant Warp feature after researching the current codebase and implementation constraints. Use when the user asks for a technical spec, implementation plan, or architecture doc tied to a product spec.

Sections in SKILL.md

Overview
When to use
Research before writing
Structure
Length heuristic
Writing guidance
Keep the spec current
Related Skills

Key facts

Author: Warp (warpdotdev/common-skills repo)
Installs on skills.sh: 28,713 as of 2026-11-02
GitHub stars: 644 for the whole common-skills repo, 2026-11-02
License: MIT (from GitHub repo data)
Last repo commit: 2026-10-28
Files: 1 file: SKILL.md only
Part of: Warp's common-skills repo, shared skills the README says may still contain Warp-specific wording

What it includes

Read PRODUCT.md, inspect the code, pin references to a commit SHA
The agent finds the main files, types, data flow and ownership boundaries, and links code references to GitHub blob URLs with the commit SHA.
Try: “Write a tech spec for specs/APP-1234 based on its PRODUCT.md.”
Runs code · Research before writing
What is built, how the area works now, key files with lines
Write · Context
Modules, new types and APIs, data flow, tradeoffs
Write · Proposed changes
Maps PRODUCT.md invariants to tests and checks
Owns all verification: unit and integration tests, manual steps, screenshots and videos, each tied to numbered Behavior items.
Write · Testing and validation
Proposes sub-agents with worktrees, branches and PR plans
If run_agents is available, the spec proposes each agent's role, local or remote mode, worktree, branch and PR strategy. It is skipped if the tool is not available.
Write · Parallelization
End-to-end flow, Mermaid diagram, risks, follow-ups
Write · Optional sections
specs/<id>/TECH.md, matching the sibling PRODUCT.md id
Write · Spec location

From the official docs

Permissions

Low risk

It reads your codebase and writes one spec file, and can create a ticket if you ask. Check the team and repo before it files anything.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Ticket creation uses your accounts
If you ask for a new Linear ticket or GitHub issue, the agent uses the Linear MCP tools or gh with your login. Say which team, labels and repo to use. github.com

Technical details

Talks to	Linear or GitHub, only if you ask for a ticket
Scopes	Reads your code and PRODUCT.md, runs git rev-parse HEAD Writes specs/<id>/TECH.md Creates a Linear ticket or GitHub issue only when you explicitly ask

Questions

What does the write-tech-spec skill do?

It makes your agent write a TECH.md, an implementation plan grounded in your actual code. It covers context, proposed changes, how the work will be tested, and whether sub-agents could work in parallel.

How do I install it in Claude Code, the Claude app or Codex?

Use the install box at the top of this page. It is a single-file skill with no scripts.

Do I need a PRODUCT.md first?

SKILL.md prefers one, so the plan is anchored to agreed behavior. If the implementation is too uncertain, it suggests building an end-to-end prototype first and writing the tech spec from what you learned.

When should I skip a tech spec?

SKILL.md says pure UI changes and straightforward fixes often do not need one, and a single-file change with a clear approach can skip it or stay under about 40 lines.

Is it only for Warp?

Its wording and example links refer to Warp's repository. The structure (context, proposed changes, testing, parallelization) is not tied to Warp, and the repo README says shared skills may still contain Warp-specific examples. It also names a run_agents tool for the Parallelization section (skipped if absent) and ask_user_question for ticket details, which your agent may not have.

Does it create tickets for me?

Only if you explicitly ask. SKILL.md then uses the Linear MCP tools or the gh CLI.

Information

updated Nov 2, 2026

Repository: warpdotdev/common-skills
Folder: .agents/skills/write-tech-spec

warpdotdev/common-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 3

write-tech-spec SKILL.md · github.com
common-skills README · github.com
skills.sh listing · skills.sh