Skill: liuxxxu/comprehensive-tech-documentation (version 1.0.0)

--- 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: ```markdown 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: ```markdown # 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: ```markdown # 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: ```markdown # 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: ```markdown # 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 ```markdown # [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 ```markdown # [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. 📚

path: _meta.json
content: {
  "ownerId": "user-generated",
  "slug": "comprehensive-tech-documentation",
  "version": "1.0.0",
  "publishedAt": 1709654400000,
  "tags": ["documentation", "technical-writing", "architecture", "visualization", "mermaid"],
  "description": "Creates layered, comprehensive technical documentation with multiple documents serving different audiences and depths",
  "keywords": [
    "documentation",
    "technical writing",
    "architecture diagrams",
    "quick reference",
    "mermaid diagrams",
    "chinese localization",
    "documentation suite",
    "layered documentation"
  ],
  "category": "documentation",
  "extractedFrom": {
    "conversation": "2026-03-05",
    "project": "self-improving-agent",
    "output": {
      "documentCount": 4,
      "totalWords": 13000,
      "diagramCount": 10
    }
  },
  "compatibility": {
    "platforms": ["OpenClaw", "Claude Code", "GitHub Copilot", "Cursor"],
    "languages": ["Chinese", "English"]
  }
}


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)