Manage Apple Reminders via the `remindctl` CLI on macOS (list, add, edit, complete, delete)....
design-doc
1
0
# Install this skill:
npx skills add diskd-ai/design-doc
Or install specific skill: npx add-skill https://github.com/diskd-ai/design-doc
# Description
Create technical design documents for new features, systems, refactoring plans, API designs, and database schemas. Use when asked to write a design doc, TRD (technical requirements document), RFC, or system design document. Triggers on requests like "write a design doc for X", "design the Y feature", "create a technical spec", or "plan the architecture for Z".
# SKILL.md
name: design-doc
description: Create technical design documents for new features, systems, refactoring plans, API designs, and database schemas. Use when asked to write a design doc, TRD (technical requirements document), RFC, or system design document. Triggers on requests like "write a design doc for X", "design the Y feature", "create a technical spec", or "plan the architecture for Z".
Technical Design Document Skill
Create structured technical design documents that communicate system behavior, implementation approach, and acceptance criteria.
Workflow
- Gather context: Understand the feature/system scope, constraints, and goals
- Draft structure: Use template from
references/template.md - Fill sections: Work through each section, asking clarifying questions as needed
- Review: Ensure acceptance criteria are testable and implementation outline is actionable
Template
See references/template.md for the full template structure and section guidelines.
Core sections:
- Context and motivation: Problem statement, goals, non-goals
- Implementation considerations: Constraints and design principles
- High-level behavior: End-to-end system behavior
- Domain-specific sections: Adapt to feature type (discovery, validation, API, state, rendering)
- Error handling and UX: Error surfacing and recovery
- Future-proofing: Design for extensibility
- Implementation outline: Step-by-step approach
- Testing approach: Unit, integration, manual tests
- Acceptance criteria: Testable conditions for "done"
Writing Guidelines
- Use
---underlines for section headers (Setext style) - Write in present tense for behavior ("loads", "validates", "returns")
- Be specific: "max 100 chars" not "reasonable length"
- Include concrete examples where behavior varies
- Non-goals are as important as goals - prevent scope creep
- Acceptance criteria must be verifiable, not subjective
# README.md
Design Document Skill
Install:
npx skills add diskd-ai/design-doc| skills.sh
Create structured technical design documents that communicate system behavior, implementation approach, and acceptance criteria.
Scope & Purpose
This skill provides guidance and templates for writing technical design documents, covering:
- Feature design specifications
- System architecture documents
- Technical requirements documents (TRD)
- Request for comments (RFC)
- Refactoring plans
- API designs
- Database schema designs
When to Use This Skill
Triggers:
* "Write a design doc for X"
* "Design the Y feature"
* "Create a technical spec"
* "Plan the architecture for Z"
* Requests for TRD, RFC, or system design documents
Use cases:
* Planning new features before implementation
* Documenting system architecture decisions
* Creating refactoring proposals
* Specifying API contracts
* Designing database schemas
* Communicating technical decisions to stakeholders
Quick Reference
Template Sections
| Section | Purpose |
|---|---|
| Context and motivation | Problem statement, goals, non-goals |
| Implementation considerations | Constraints, design principles, trade-offs |
| High-level behavior | End-to-end system flow |
| Domain-specific sections | Adapted to feature type |
| Error handling and UX | Error surfacing and recovery |
| Future-proofing | Design for extensibility |
| Implementation outline | Step-by-step approach |
| Testing approach | Unit, integration, manual tests |
| Acceptance criteria | Testable conditions for "done" |
Domain-Specific Section Guide
| Feature Type | Typical Sections |
|---|---|
| File processor | Discovery rules, Format validation, Output model |
| API/Service | Endpoint design, Request/response schemas, Auth |
| UI Feature | Component structure, State management, Rendering |
| Data pipeline | Input sources, Transformations, Output sinks |
| Integration | Protocol, Authentication, Error mapping |
Workflow
- Gather context: Understand the feature/system scope, constraints, and goals
- Draft structure: Use template from
references/template.md - Fill sections: Work through each section, asking clarifying questions as needed
- Review: Ensure acceptance criteria are testable and implementation outline is actionable
Skill Structure
design-doc/
SKILL.md # Skill definition and guidelines
README.md # This file (overview)
references/ # Supporting documentation
template.md # Full template with section guidelines
Writing Guidelines
- Use
---underlines for section headers (Setext style) - Write in present tense for behavior ("loads", "validates", "returns")
- Be specific: "max 100 chars" not "reasonable length"
- Include concrete examples where behavior varies
- Non-goals are as important as goals - prevent scope creep
- Acceptance criteria must be verifiable, not subjective
Section Best Practices
Context and Motivation
- State the problem clearly in 1-2 sentences
- Explain why now (what triggered this work)
- Goals should be measurable outcomes, not implementation details
- Non-goals prevent scope creep and set expectations
High-Level Behavior
- Write as if explaining to a new team member
- Use bullet points for step-by-step flows
- Cover both happy path and edge cases
Acceptance Criteria
Write as testable statements:
* "Given X, when Y, then Z"
* Include both positive and negative cases
* Reference specific behaviors from High-level behavior section
Resources
- Full template: references/template.md
- Skill definition: SKILL.md
License
MIT
# Related Skills
Query Google Places API (New) via the goplaces CLI for text search, place details, resolve, and...
Notion API for creating and managing pages, databases, and blocks.
Manage Things 3 via the `things` CLI on macOS (add/update projects+todos via URL scheme;...
# Supported AI Coding Agents
This skill is compatible with the SKILL.md standard and works with all major AI coding agents:
Amp
Antigravity
Claude Code
Clawdbot
Codex
Cursor
Droid
Gemini CLI
GitHub Copilot
Goose
Kilo Code
Kiro CLI
OpenCode
Roo Code
Trae
Windsurf
Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.