technical-design-docs

Write standalone technical design documents, RFCs, and architecture proposals in Markdown.

1|Updated Dec 18, 2009
One-click install
npx skills add https://github.com/thurn/dotfiles --skill technical-design-docs-thurn
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: technical-design-docs
Source: https://github.com/thurn/dotfiles/tree/main/.llms/skills/technical-design-docs
Command: npx skills add https://github.com/thurn/dotfiles --skill technical-design-docs-thurn

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Writing technical design documents that are complete, standalone, and readable is hard: drafts often assume hidden conversation context, bury decisions in walls of prose, or omit validation guidance. This Skill produces a full design document in one pass that any reader can understand without the original discussion. ## Core Features & Use Cases - One-pass document generation: Gathers only the scope that matters, asks material clarifying questions up front, then writes the complete document without section-by-section approval cycles. - ADHD-optimized structure: Enforces short orienting paragraphs, liberal bulleted lists, frequent fenced code examples, inline term definitions, and prominent related-information links so readers can scan and resume easily. - Cold-reader validation: Runs a fresh sub-agent comprehension test to flag jargon, ordering problems, and missing context before delivery. - Use Case: Ask for an RFC describing a new caching layer; receive a standalone Markdown document covering the problem, proposed design, concrete mechanics, migration behavior, and a final Manual QA section. ## Quick Start Write a technical design document for adding rate limiting to our public API, including the proposed design, failure handling, and a Manual QA section.

Frequently Asked Questions about technical-design-docs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a technical design document with an AI assistant?▼

Provide the problem, audience, fixed constraints, and relevant existing docs, then request the full design document. The Skill asks only material clarifying questions up front, then writes the complete standalone Markdown document in one pass without outline approvals.

What sections should a technical design document include?▼

A typical structure is Title, Introduction, Related Information, Proposed Design, Concrete Mechanics, Migration and Compatibility, and a mandatory final Manual QA section. Sections like Open Questions, Risks and Tradeoffs, and Non-Goals are explicitly omitted.

Can this Skill revise an existing design doc or RFC?▼

Yes. It preserves the author's intent while adding missing standalone context, breaking walls of prose into bullets and code examples, defining jargon inline, reordering dependent concepts, and adding or revising the final Manual QA section.

Does the design document include diagrams or implementation plans?▼

No. Diagrams of any kind are excluded, and the document specifies what to build rather than milestones, phases, or MVP slices. Behavior is illustrated with short fenced code samples, payloads, and configuration examples instead.

How is the generated design document validated for readability?▼

A fresh sub-agent with no conversation context performs a cold-reader pass, flagging undefined jargon, out-of-order concepts, walls of prose, and missing examples. Comprehension gaps are fixed, and a second pass runs if meaningful issues were found.