skills.rest
PeteRichardson
PeteRichardsonCOMMUNITY
Explore all skills by this author →
GitHub

design-doc

Generate a living technical design document from an existing codebase.

Updated Jun 4, 2026
Search Tags:#architecture#documentation#markdown#onboarding#technical writing#design document#codebase analysis
One-click install
npx skills add https://github.com/PeteRichardson/skills --skill design-doc-peterichardson
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: design-doc
Source: https://github.com/PeteRichardson/skills/tree/main/design-doc
Command: npx skills add https://github.com/PeteRichardson/skills --skill design-doc-peterichardson

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases often lack up-to-date architecture documentation, forcing new contributors to reverse-engineer the system from source files. This Skill synthesizes README, CLAUDE.md, project structure, and key source files into a cohesive prose design document at docs/design.md. ## Core Features & Use Cases - Codebase Synthesis: Reads entry points, core modules, data models, and dependency manifests to build an accurate mental model of the system. - Living Document Updates: Preserves accurate sections of an existing docs/design.md while revising stale parts as the project evolves. - Structured Template: Produces sections for Overview, Goals and Non-Goals, Architecture, Data Flow, Key Design Decisions, Dependencies, and Open Questions. - Use Case: After a major refactor, ask for a design doc refresh so new team members can understand the system in 15 minutes instead of reading every file. ## Quick Start Ask the assistant to generate a design document for this project and write it to docs/design.md.

Frequently Asked Questions about design-doc

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

FAQPage Schema
How do I generate a design document from my codebase?▼

Invoke the skill and it reads your README, CLAUDE.md, project structure, dependency manifests, and key source files, then writes a prose-first design document to docs/design.md covering architecture, data flow, and design decisions.

What should a technical design document include?▼

A useful design doc includes an overview, goals and non-goals, architecture narrative, component descriptions, data flow walkthrough, key design decisions with trade-offs, external dependencies, and an honest open questions section.

Does it work with existing design documentation?▼

Yes. If docs/design.md already exists, the skill preserves sections that are still accurate and revises or replaces stale sections rather than overwriting everything from scratch.

Which programming languages does it support?▼

It scans for Swift, Python, TypeScript, JavaScript, Rust, and Go source files, and reads dependency manifests like Package.swift, package.json, Cargo.toml, requirements.txt, and go.mod.

When should I not use a generated design doc?▼

Avoid relying on it when architectural intent is not visible in the code, since the skill notes unclear points as open questions rather than guessing. Very small scripts may also not need a full design document.

Related Skills

Explore More Software Engineering Skills→
jacobcyjacobcy
6

vibe-drift

Detect deviations between a repository's current codebase and its documented intent using CLAUDE.md, SOUL.md, git history, and governance thresholds.

Community
Intermediate
tigredonortetigredonorte

create-jira-wiki

Publish Jira task design documents to a wiki repository.

Community
Advanced
Mte90Mte90
51

Documentation Standards

Enforce documentation standards for code comments, READMEs, and architectural docs.

Community
Basic
VSF-QC-TTSVSF-QC-TTS

common-architecture-diagramming

Standardize architecture diagrams using C4 and UML models with Mermaid syntax.

Official
Intermediate