Comprehensive Tech Documentation

---

name: comprehensive-tech-documentation description: "Creates layered, comprehensive technical documentation for projects, skills, or systems. Use when user requests 'write technical documentation', 'explain how this works', or 'document the architecture'. Produces 3-4 documents with different depths and purposes."

---

Comprehensive Technical Documentation

Creates a complete documentation suite that serves different audiences and use cases, from quick reference to deep technical analysis.

Quick Reference

| User Request | Documentation Output | |--------------|---------------------| | "写技术文档" or "Write docs" | Full 4-document suite | | "解释原理" or "Explain how it works" | Technical Principles doc + Architecture | | "快速参考" or "Quick reference" | Quick Reference Guide only | | "画架构图" or "Draw architecture" | Architecture Visualization doc | | "写导航索引" or "Create index" | Navigation Index doc |

Background

When documenting complex systems, a single monolithic document fails to serve different audiences:

New users need quick start guides

Architects need visual diagrams

Developers need deep technical details

Everyone needs navigation

This skill solves that by creating a layered documentation system with 3-4 complementary documents.

Solution

The Documentation Suite

Create these documents (adapt based on project scope):

1. 📖 Technical Principles (技术原理文档.md) - Deep dive into how the system works - Design philosophy and decisions - Implementation details - Best practices - Target: Developers, contributors - Reading time: 30-60 minutes

2. 📊 Architecture Visualization (架构与流程可视化.md) - Mermaid diagrams for architecture - Flow charts and sequence diagrams - State machines - Data flow diagrams - Target: Architects, visual learners - Reading time: 15-30 minutes

3. 🔖 Quick Reference Guide (快速参考指南.md) - Templates and examples - Command cheat sheets - Field definitions - Troubleshooting - Target: All users (most frequently used) - Reading time: 5-15 minutes

4. 🗺️ Navigation Index (README-文档索引.md or 文档索引.md) - Document comparison table - Learning paths by role - Scenario-based navigation - FAQ with document links - Target: First-time users, navigators - Reading time: 5 minutes

Step-by-Step Workflow

#### Phase 1: Deep Understanding (15-30 minutes)

Read core files to understand the system:

MUST READ:
Main entry point (SKILL.md, README.md, main config)
Core implementation files
Configuration files
Integration documentation
PARALLEL READ:
Use parallel file reads for independent files
Group related files (e.g., all configs together)

Decision point: If system is small (<5 files), might only need 1-2 docs.

#### Phase 2: Analysis & Extraction (10-15 minutes)

Extract key information:

1. Core Concepts - What problem does it solve? 2. Architecture - What are the major components? 3. Data Flow - How does information move? 4. Integration Points - How does it connect to other systems? 5. User Workflows - What are the main use cases? 6. Pain Points - What commonly goes wrong?

#### Phase 3: Document Creation (30-60 minutes)

Create documents in this order:

1. Technical Principles (技术原理文档.md)

Structure:

# Title - 技术原理详解
目录
[Table of contents with clear sections]
核心概念
1.1 设计理念
1.2 核心机制
系统架构
2.1 组件结构 (with tree diagram)
2.2 数据分层
工作原理
3.1 触发条件
3.2 处理流程
3.3 输出机制
技术实现
4.1 关键代码实现
4.2 配置系统
4.3 扩展机制
数据流转
5.1 完整生命周期
5.2 跨系统通信
核心循环/机制
6.1 主要循环
6.2 反馈机制
集成方式
7.1 Platform A
7.2 Platform B
7.3 Generic setup
最佳实践
8.1 应该做
8.2 不应该做
8.3 维护建议
技术洞察
9.1 设计哲学
9.2 局限性
9.3 与其他系统对比
实际应用示例
10.1 场景A
10.2 场景B
总结

Word count: 5000-8000 words for complex systems

2. Architecture Visualization (架构与流程可视化.md)

Include these diagram types:

# Title - 架构与流程可视化
1. 核心架构图
1.1 系统层次架构
[Mermaid: graph TB with subgraphs]
1.2 数据流架构
[Mermaid: flowchart LR showing data movement]
2. 核心流程
2.1 主要流程完整序列
[Mermaid: sequenceDiagram]
2.2 子流程
[Mermaid: flowchart TD with decision nodes]
3. 触发条件映射
[Mermaid: flowchart TD - decision tree]
4. 跨系统通信
[Mermaid: graph showing system interactions]
5. 模式识别机制
[Mermaid: flowchart showing pattern matching]
6. 文件系统拓扑
[Mermaid: graph TD showing directory structure]
7. 状态转换图
[Mermaid: stateDiagram-v2]
8. 集成模式对比
[Mermaid: comparison graphs]
9. 性能与扩展性
[Mermaid: growth curves]
10. 监控与度量
[Mermaid: metrics dashboard]

Diagram count: 10-15 Mermaid diagrams

3. Quick Reference Guide (快速参考指南.md)

Structure:

# Title - 快速参考指南
📚 一分钟了解
[Core concept in 3-5 bullet points]
🎯 何时使用
[Trigger conditions table]
📝 模板
[Copy-paste templates with all fields]
🎨 优先级/分类指南
[Reference tables]
🚀 提升/决策指南
[Decision flowchart in text]
🔧 快速安装
[Copy-paste commands for each platform]
📊 字段说明
[All field definitions in tables]
🛠️ 常用命令
[Bash/PowerShell command examples]
📦 文件结构
[ASCII tree diagrams]
🔄 工作流程示例
[3-5 numbered scenarios with outcomes]
💡 最佳实践
[✅ DO and ❌ DON'T lists]
🆘 故障排查
[Problem-solution pairs]
🔖 速查卡
[Super compact cheat sheet at the end]

Word count: 2500-3500 words

4. Navigation Index (README-文档索引.md)

Structure:

# Title - 文档索引
📚 文档导航
[3-column table: Quick Start | Architecture | Deep Dive]
📖 文档列表
[Table with: Doc name, Type, Word count, Summary, Audience]
🗺️ 学习路径
路径A: 快速上手（30分钟）
[Numbered steps with specific sections to read]
路径B: 深入理解（1小时）
[Longer path]
路径C: 精通全貌（2小时）
[Complete path]
💡 按场景查找
[5-10 common scenarios with recommended docs]
📊 文档内容对比
[Matrix showing topic coverage across all docs]
🎯 快速问题解答
[10 FAQ with links to specific doc sections]
🔗 相关资源
[External links]
📝 文档更新记录
💬 反馈与贡献
🎓 下一步
[Role-based next actions in 2x2 table]

Word count: 2000-3000 words

#### Phase 4: Visualization (20-30 minutes)

Create Mermaid diagrams for Architecture doc:

Essential diagrams: 1. System architecture (graph TB with subgraphs) 2. Data flow (flowchart LR) 3. Main sequence flow (sequenceDiagram) 4. Decision tree (flowchart TD) 5. State machine (stateDiagram-v2) 6. File system topology (graph TD)

Mermaid best practices:

Use subgraph for logical grouping

Apply style for visual hierarchy (colors)

Keep each diagram focused on one aspect

Add Note annotations for clarity

#### Phase 5: Quality Check (10 minutes)

Verify completeness:

[ ] All documents use consistent terminology

[ ] Cross-references between docs work

[ ] Code examples are syntactically correct

[ ] Mermaid diagrams render properly

[ ] File paths are accurate

[ ] Tables are properly formatted

[ ] Each doc has clear target audience

[ ] Reading time estimates are realistic

[ ] Documents are in logical reading order

Output Decision Tree

How complex is the system?
│
├─ Simple (1-2 files, single purpose)
│  └─ Create: Quick Reference only
│
├─ Medium (3-10 files, clear structure)
│  └─ Create: Quick Reference + Technical Principles
│
├─ Complex (10+ files, multiple subsystems)
│  └─ Create: All 4 documents
│
└─ Massive (50+ files, enterprise scale)
   └─ Create: All 4 + additional domain-specific docs

Document Templates

Technical Principles Template

# [System Name] - 技术原理详解
目录
[auto-generated or manual]
核心概念
1.1 设计理念
> [One-sentence design philosophy quote]
[System Name] 的核心理念是：
> [Core idea in bold quote]
这个框架解决了以下核心问题：
1. [Problem 1]：[Description]
2. [Problem 2]：[Description]
1.2 核心机制
[ASCII or text diagram showing the main loop]
系统架构
2.1 组件结构

[Directory tree with comments] project/ ├── component-a/ # Purpose ├── component-b/ # Purpose └── config/ # Purpose

2.2 数据分层

[Layer diagram in ASCII] ┌──────────────────┐ │ Layer 3 │ ← Description └──────────────────┘ ▲ │ relationship │ ┌──────────────────┐ │ Layer 2 │ ← Description └──────────────────┘

[Continue with all sections...]
总结
[System Name] 是一个[description]，它通过系统化地：
1. [Action 1]：[Description]
2. [Action 2]：[Description]
[Closing statement about value]
文档版本: 1.0
最后更新: [Date]
作者: GitHub Copilot (Claude Sonnet 4.5)

Quick Reference Template

# [System Name] - 快速参考指南
📚 一分钟了解
[System Name] [one-line description]
核心概念

[Simple flow diagram] Step1 → Step2 → Step3

[Concept 1]：[Description]
[Concept 2]：[Description]
🎯 何时使用
| 场景 | 记录位置 | 类别 |
|------|---------|------|
| [Trigger] | [Location] | [Type] |
📝 记录模板
[Template Type 1]

markdown [Actual template content to copy-paste]

[Continue...]
版本: 1.0  
更新: [Date]  
适用: [System] v[version]+  
提示: 保持此指南在手边，快速查阅关键信息！ 📖

Common Variations

Variation A: Codebase Documentation

For documenting a code repository:

Focus on:

Architecture patterns

API design

Code organization

Development workflow

Testing strategy

Additional diagrams:

Class diagrams

API flow

Database schema

Variation B: Skill Documentation

For documenting an AI agent skill:

Focus on:

When to trigger

Decision logic

Output format

Integration with other skills

Additional sections:

Trigger conditions

Examples of good/bad prompts

Variation C: Tool/Library Documentation

For documenting a tool or library:

Focus on:

Installation steps

Configuration options

API reference

Usage examples

Troubleshooting

Additional sections:

Compatibility matrix

Performance benchmarks

Variation D: Process Documentation

For documenting a workflow or methodology:

Focus on:

Step-by-step procedures

Decision points

Quality gates

Roles and responsibilities

Additional diagrams:

Swimlane diagrams

Gantt charts

Gotchas

⚠️ Don't create all 4 docs for simple systems - Use judgment. A 50-line script doesn't need 4 documents.

⚠️ Don't duplicate content - Each document should have a distinct purpose. Cross-reference instead of copy-paste.

⚠️ Don't skip the index - Without navigation, users get lost. The index document is crucial for multi-doc suites.

⚠️ Don't use broken Mermaid syntax - Test diagrams before finalizing. Common errors:

Missing closing quotes

Invalid node IDs

Unsupported diagram features

⚠️ Don't ignore reading time estimates - Help users plan their time. Be realistic about document length.

⚠️ Don't mix languages inconsistently - If user requests Chinese, use Chinese for all headings and body text. Keep code/commands in original language.

⚠️ Don't assume prior knowledge - Define acronyms and technical terms, especially in Quick Reference.

⚠️ Don't forget visual hierarchy - Use emojis (📖 🎯 💡) and formatting to make docs scannable.

Writing Style Guidelines

For Technical Principles Doc

Tone: Academic but accessible

Depth: Assume reader wants to understand "why" not just "how"

Code examples: Include actual implementations with explanations

Length: Don't shy away from detail; this is the deep-dive doc

For Architecture Visualization Doc

Diagram-first: Let diagrams tell the story

Minimal text: Just enough to explain what you're looking at

Consistent notation: Use same colors/shapes for same concepts

Progressive complexity: Start simple, add detail gradually

For Quick Reference Doc

Tone: Practical and direct

Format: Heavy use of tables, lists, and code blocks

No fluff: Every sentence should provide actionable information

Scannable: Use visual markers (✅ ❌ 🔴 🟢) liberally

For Navigation Index Doc

Tone: Welcoming and guiding

Purpose: Help users find what they need fast

Structure: Clear hierarchy with visual tables

Empathy: Anticipate what different users need

Localization

When creating Chinese documentation:

Do:

✅ Use Chinese for all headings and body text

✅ Keep technical terms in English within backticks: SKILL.md

✅ Use Chinese punctuation (，。；：)

✅ Provide clear Chinese translations for concepts

✅ Use emojis universally (work in all languages)

Don't:

❌ Mix English and Chinese in the same sentence without backticks

❌ Translate file names or commands

❌ Use English-style comma in Chinese text

❌ Translate acronyms (keep API as API, not 应用程序接口)

Integration with Other Skills

Pairs well with:

self-improvement - After creating docs, log if you learned better documentation patterns

proactive-agent - Proactively offer to update docs when code changes

agent-customization - Document your custom skills using this approach

Quality Checklist

Before delivering documentation:

[ ] All 4 documents created (or justified why fewer)

[ ] Reading time estimates in index

[ ] At least 8 Mermaid diagrams in Architecture doc

[ ] Quick Reference has copy-paste templates

[ ] Technical Principles explains "why" not just "what"

[ ] Index provides learning paths for 3 personas

[ ] Cross-references between docs work

[ ] No broken Mermaid syntax

[ ] Consistent terminology across all docs

[ ] Each doc has version and last-updated date

[ ] Troubleshooting section in Quick Reference

[ ] File tree diagrams use consistent formatting

[ ] Tables are aligned and complete

[ ] Code blocks have language specified

[ ] Chinese localization follows guidelines (if applicable)

Example Prompt Patterns

To trigger this skill:

✅ Good prompts:

"当前skill的原理是什么，写一份详尽文档"

"Write comprehensive documentation for this codebase"

"Document the architecture with diagrams"

"Create a quick reference guide and full technical docs"

✅ Clarifying questions (if needed):

"Who is the primary audience?" (if unclear)

"Is this for internal use or public consumption?"

"Do you need Chinese or English documentation?"

❌ Avoid confusion with:

"Write a README" (too vague - might just need one doc)

"Add comments to the code" (different skill)

"Create API documentation" (use API-specific skill if available)

Related

agent-customization - For creating SKILL.md files specifically

self-improvement - For logging documentation patterns you discover

proactive-agent - For maintaining docs over time

Source

Created: 2026-03-05

Origin: Extracted from conversation where comprehensive docs were created for self-improving-agent skill

Pattern: Successfully applied to document a complex AI agent skill with multiple subsystems

Validation: Created 4 documents totaling ~13,000 words with 10+ diagrams

---

Note: This skill produces 5,000-15,000 words of documentation. Budget 1-2 hours for complete execution on complex systems.

Tip: Start by reading core files in parallel to save time. The understanding phase is critical - don't rush it.

Remember: Different users need different depths. The layered approach ensures everyone finds what they need. 📚