Agent skill

tech-design-doc

Generate technical design documents with proper structure, diagrams, and implementation details. Default language is English unless user requests Chinese.

View SKILL.md on GitHub Repository
Stars 6
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/acking-you/myclaude-skills/tree/main/skills/tech-design-doc

SKILL.md

Technical Design Document Skill

When to Use

  • Designing a new feature or system
  • Documenting architecture decisions (ADR/RFC)
  • Planning refactoring or optimization work

Execution Flow

1. Assess Complexity

Level Scope Sections Required
Small Single component, <100 LOC TL;DR, Design, Implementation
Medium Cross-component, API changes + Background, Solution Analysis
Large System-level, new service Full template

2. Gather Context

Before writing, explore the codebase:

  • Identify affected components (grep/glob for related code)
  • Read existing implementations and patterns
  • Note dependencies and potential side effects
  • Check for similar solutions already in codebase

3. Write Document

Follow the template structure below, scaled to complexity level.

4. Verify Before Handoff

  • Problem clearly defined (what breaks if we do nothing?)
  • Options compared with trade-offs (not just one solution)
  • Decision rationale documented
  • Diagrams illustrate key flows
  • Implementation steps are concrete and actionable
  • Risks identified with mitigations

Document Template

markdown
# [Feature/System Name] Technical Design

## TL;DR
- 3-5 bullets: problem, solution, key decisions, expected outcome

## Background (Medium/Large)

### Current State
- Existing behavior and limitations

### Problem Statement
- What breaks if we do nothing?
- Who is affected and how?

### Goals / Non-Goals
- Goals: what this design achieves
- Non-Goals: explicitly out of scope

## Solution Analysis (Medium/Large)

### Option 1: [Name]
Pros: ...
Cons: ...

### Option 2: [Name]
Pros: ...
Cons: ...

### Comparison
| Criteria | Option 1 | Option 2 |
|----------|----------|----------|
| Performance | ... | ... |
| Complexity | ... | ... |

### Recommendation
Selected: Option X
Rationale: [why]

## Detailed Design

### Architecture
[Mermaid diagram - see examples below]

### Component Design
- Responsibilities
- Interfaces
- Dependencies

### Data Model (if applicable)
[Schema or structure]

### API Design (if applicable)
[Endpoints, request/response]

## Implementation Plan

### Phase 1: [Name]
- [ ] Task 1
- [ ] Task 2

### Migration Strategy (if applicable)

## Risk Assessment

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| ... | High/Med/Low | High/Med/Low | ... |

## References
- Related docs, external resources

Mermaid Diagram Examples

Architecture (flowchart):

mermaid
flowchart TD
    A[Client] --> B[API Gateway]
    B --> C[Service]
    C --> D[(Database)]

Sequence:

mermaid
sequenceDiagram
    Client->>Server: Request
    Server->>DB: Query
    DB-->>Server: Result
    Server-->>Client: Response

State:

mermaid
stateDiagram-v2
    [*] --> Pending
    Pending --> Processing: start
    Processing --> Done: complete
    Processing --> Failed: error

Handling Feedback

When user requests changes:

  1. Understand which section needs revision
  2. Update only affected sections
  3. Ensure changes don't contradict other sections
  4. Re-verify the checklist items related to changes

Output Location

  • Check if project has docs/, ai_docs/, or design/ directory
  • Ask user if location is unclear
  • Use descriptive filename: design-[feature-name].md

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

acking-you/myclaude-skills

github-wrapped

Generate a verifiable GitHub Wrapped year-in-review as a single-file HTML (raw gh API JSON saved, Python-built dataset embedded), with a Bilibili-style narrative, smooth transitions, and mobile-friendly paged mode. Requires gh CLI to be authenticated.

6 1
Explore
acking-you/myclaude-skills

codex-session-history

Search Codex local session history stored in SQLite and session_index.jsonl. Use this skill when the user wants to list, search, filter, or inspect locally saved Codex sessions by session id, provider, time range, preview text, thread name, or archived status.

6 1
Explore
acking-you/myclaude-skills

tech-impl-doc

Write precise technical implementation docs (developer or user) with clear structure, accurate flows, render-safe Mermaid diagrams, and audience-appropriate detail; avoid boilerplate; include a meaningful Code Index for developer docs.

6 1
Explore
acking-you/myclaude-skills

gemini-image

Generate images using AI when user wants to create pictures, draw, paint, or generate artwork. Supports text-to-image and image-to-image generation.

6 1
Explore
acking-you/myclaude-skills

excalidraw

Generate hand-drawn style diagrams (architecture, flowcharts, system design) as .excalidraw.json files. Use when user wants diagrams, mentions Excalidraw, or needs Mermaid-to-visual conversion.

6 1
Explore
acking-you/myclaude-skills

research

Structured web research with multi-source validation. Output reports with complete citation links. Focus on key results, verify information quality.

6 1
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results