\r \r

Comprehensive Technical Documentation\r

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

Quick Reference\r

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

Background\r

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

• New users need quick start guides\r
• Architects need visual diagrams\r
• Developers need deep technical details\r
• Everyone needs navigation\r \r This skill solves that by creating a layered documentation system with 3-4 complementary documents.\r \r

Solution\r

\r

The Documentation Suite\r

\r Create these documents (adapt based on project scope):\r \r

1. 📖 Technical Principles (技术原理文档.md)\r
   • Deep dive into how the system works\r
   • Design philosophy and decisions\r
   • Implementation details\r
   • Best practices\r
   • Target: Developers, contributors\r
   • Reading time: 30-60 minutes\r \r
2. 📊 Architecture Visualization (架构与流程可视化.md)\r
   • Mermaid diagrams for architecture\r
   • Flow charts and sequence diagrams\r
   • State machines\r
   • Data flow diagrams\r
   • Target: Architects, visual learners\r
   • Reading time: 15-30 minutes\r \r
3. 🔖 Quick Reference Guide (快速参考指南.md)\r
   • Templates and examples\r
   • Command cheat sheets\r
   • Field definitions\r
   • Troubleshooting\r
   • Target: All users (most frequently used)\r
   • Reading time: 5-15 minutes\r \r
4. 🗺️ Navigation Index (README-文档索引.md or 文档索引.md)\r
   • Document comparison table\r
   • Learning paths by role\r
   • Scenario-based navigation\r
   • FAQ with document links\r
   • Target: First-time users, navigators\r
   • Reading time: 5 minutes\r \r

Step-by-Step Workflow\r

\r

Phase 1: Deep Understanding (15-30 minutes)\r

\r Read core files to understand the system:\r \r

MUST READ:\r
- Main entry point (SKILL.md, README.md, main config)\r
- Core implementation files\r
- Configuration files\r
- Integration documentation\r
\r
PARALLEL READ:\r
- Use parallel file reads for independent files\r
- Group related files (e.g., all configs together)\r
```\r
\r
**Decision point**: If system is small (\x3C5 files), might only need 1-2 docs.\r
\r
#### Phase 2: Analysis & Extraction (10-15 minutes)\r
\r
Extract key information:\r
\r
1. **Core Concepts** - What problem does it solve?\r
2. **Architecture** - What are the major components?\r
3. **Data Flow** - How does information move?\r
4. **Integration Points** - How does it connect to other systems?\r
5. **User Workflows** - What are the main use cases?\r
6. **Pain Points** - What commonly goes wrong?\r
\r
#### Phase 3: Document Creation (30-60 minutes)\r
\r
Create documents in this order:\r
\r
**1. Technical Principles (技术原理文档.md)**\r
\r
Structure:\r
```markdown\r
# Title - 技术原理详解\r
\r
## 目录\r
[Table of contents with clear sections]\r
\r
## 核心概念\r
1.1 设计理念\r
1.2 核心机制\r
\r
## 系统架构\r
2.1 组件结构 (with tree diagram)\r
2.2 数据分层\r
\r
## 工作原理\r
3.1 触发条件\r
3.2 处理流程\r
3.3 输出机制\r
\r
## 技术实现\r
4.1 关键代码实现\r
4.2 配置系统\r
4.3 扩展机制\r
\r
## 数据流转\r
5.1 完整生命周期\r
5.2 跨系统通信\r
\r
## 核心循环/机制\r
6.1 主要循环\r
6.2 反馈机制\r
\r
## 集成方式\r
7.1 Platform A\r
7.2 Platform B\r
7.3 Generic setup\r
\r
## 最佳实践\r
8.1 应该做\r
8.2 不应该做\r
8.3 维护建议\r
\r
## 技术洞察\r
9.1 设计哲学\r
9.2 局限性\r
9.3 与其他系统对比\r
\r
## 实际应用示例\r
10.1 场景A\r
10.2 场景B\r
\r
## 总结\r
```\r
\r
**Word count**: 5000-8000 words for complex systems\r
\r
**2. Architecture Visualization (架构与流程可视化.md)**\r
\r
Include these diagram types:\r
\r
```markdown\r
# Title - 架构与流程可视化\r
\r
## 1. 核心架构图\r
### 1.1 系统层次架构\r
[Mermaid: graph TB with subgraphs]\r
\r
### 1.2 数据流架构\r
[Mermaid: flowchart LR showing data movement]\r
\r
## 2. 核心流程\r
### 2.1 主要流程完整序列\r
[Mermaid: sequenceDiagram]\r
\r
### 2.2 子流程\r
[Mermaid: flowchart TD with decision nodes]\r
\r
## 3. 触发条件映射\r
[Mermaid: flowchart TD - decision tree]\r
\r
## 4. 跨系统通信\r
[Mermaid: graph showing system interactions]\r
\r
## 5. 模式识别机制\r
[Mermaid: flowchart showing pattern matching]\r
\r
## 6. 文件系统拓扑\r
[Mermaid: graph TD showing directory structure]\r
\r
## 7. 状态转换图\r
[Mermaid: stateDiagram-v2]\r
\r
## 8. 集成模式对比\r
[Mermaid: comparison graphs]\r
\r
## 9. 性能与扩展性\r
[Mermaid: growth curves]\r
\r
## 10. 监控与度量\r
[Mermaid: metrics dashboard]\r
```\r
\r
**Diagram count**: 10-15 Mermaid diagrams\r
\r
**3. Quick Reference Guide (快速参考指南.md)**\r
\r
Structure:\r
```markdown\r
# Title - 快速参考指南\r
\r
## 📚 一分钟了解\r
[Core concept in 3-5 bullet points]\r
\r
## 🎯 何时使用\r
[Trigger conditions table]\r
\r
## 📝 模板\r
[Copy-paste templates with all fields]\r
\r
## 🎨 优先级/分类指南\r
[Reference tables]\r
\r
## 🚀 提升/决策指南\r
[Decision flowchart in text]\r
\r
## 🔧 快速安装\r
[Copy-paste commands for each platform]\r
\r
## 📊 字段说明\r
[All field definitions in tables]\r
\r
## 🛠️ 常用命令\r
[Bash/PowerShell command examples]\r
\r
## 📦 文件结构\r
[ASCII tree diagrams]\r
\r
## 🔄 工作流程示例\r
[3-5 numbered scenarios with outcomes]\r
\r
## 💡 最佳实践\r
[✅ DO and ❌ DON'T lists]\r
\r
## 🆘 故障排查\r
[Problem-solution pairs]\r
\r
## 🔖 速查卡\r
[Super compact cheat sheet at the end]\r
```\r
\r
**Word count**: 2500-3500 words\r
\r
**4. Navigation Index (README-文档索引.md)**\r
\r
Structure:\r
```markdown\r
# Title - 文档索引\r
\r
## 📚 文档导航\r
[3-column table: Quick Start | Architecture | Deep Dive]\r
\r
## 📖 文档列表\r
[Table with: Doc name, Type, Word count, Summary, Audience]\r
\r
## 🗺️ 学习路径\r
### 路径A: 快速上手（30分钟）\r
[Numbered steps with specific sections to read]\r
\r
### 路径B: 深入理解（1小时）\r
[Longer path]\r
\r
### 路径C: 精通全貌（2小时）\r
[Complete path]\r
\r
## 💡 按场景查找\r
[5-10 common scenarios with recommended docs]\r
\r
## 📊 文档内容对比\r
[Matrix showing topic coverage across all docs]\r
\r
## 🎯 快速问题解答\r
[10 FAQ with links to specific doc sections]\r
\r
## 🔗 相关资源\r
[External links]\r
\r
## 📝 文档更新记录\r
\r
## 💬 反馈与贡献\r
\r
## 🎓 下一步\r
[Role-based next actions in 2x2 table]\r
```\r
\r
**Word count**: 2000-3000 words\r
\r
#### Phase 4: Visualization (20-30 minutes)\r
\r
Create Mermaid diagrams for Architecture doc:\r
\r
**Essential diagrams:**\r
1. System architecture (graph TB with subgraphs)\r
2. Data flow (flowchart LR)\r
3. Main sequence flow (sequenceDiagram)\r
4. Decision tree (flowchart TD)\r
5. State machine (stateDiagram-v2)\r
6. File system topology (graph TD)\r
\r
**Mermaid best practices:**\r
- Use `subgraph` for logical grouping\r
- Apply `style` for visual hierarchy (colors)\r
- Keep each diagram focused on one aspect\r
- Add `Note` annotations for clarity\r
\r
#### Phase 5: Quality Check (10 minutes)\r
\r
Verify completeness:\r
\r
- [ ] All documents use consistent terminology\r
- [ ] Cross-references between docs work\r
- [ ] Code examples are syntactically correct\r
- [ ] Mermaid diagrams render properly\r
- [ ] File paths are accurate\r
- [ ] Tables are properly formatted\r
- [ ] Each doc has clear target audience\r
- [ ] Reading time estimates are realistic\r
- [ ] Documents are in logical reading order\r
\r
### Output Decision Tree\r
\r
```\r
How complex is the system?\r
│\r
├─ Simple (1-2 files, single purpose)\r
│  └─ Create: Quick Reference only\r
│\r
├─ Medium (3-10 files, clear structure)\r
│  └─ Create: Quick Reference + Technical Principles\r
│\r
├─ Complex (10+ files, multiple subsystems)\r
│  └─ Create: All 4 documents\r
│\r
└─ Massive (50+ files, enterprise scale)\r
   └─ Create: All 4 + additional domain-specific docs\r
```\r
\r
## Document Templates\r
\r
### Technical Principles Template\r
\r
```markdown\r
# [System Name] - 技术原理详解\r
\r
## 目录\r
[auto-generated or manual]\r
\r
---\r
\r
## 核心概念\r
\r
### 1.1 设计理念\r
\r
> [One-sentence design philosophy quote]\r
\r
[System Name] 的核心理念是：\r
\r
> **[Core idea in bold quote]**\r
\r
这个框架解决了以下核心问题：\r
\r
1. **[Problem 1]**：[Description]\r
2. **[Problem 2]**：[Description]\r
\r
### 1.2 核心机制\r
\r
[ASCII or text diagram showing the main loop]\r
\r
---\r
\r
## 系统架构\r
\r
### 2.1 组件结构\r
\r
```\r
[Directory tree with comments]\r
project/\r
├── component-a/    # Purpose\r
├── component-b/    # Purpose\r
└── config/         # Purpose\r
```\r
\r
### 2.2 数据分层\r
\r
```\r
[Layer diagram in ASCII]\r
┌──────────────────┐\r
│   Layer 3        │ ← Description\r
└──────────────────┘\r
        ▲\r
        │ relationship\r
        │\r
┌──────────────────┐\r
│   Layer 2        │ ← Description\r
└──────────────────┘\r
```\r
\r
[Continue with all sections...]\r
\r
---\r
\r
## 总结\r
\r
**[System Name]** 是一个[description]，它通过系统化地：\r
\r
1. **[Action 1]**：[Description]\r
2. **[Action 2]**：[Description]\r
\r
[Closing statement about value]\r
\r
---\r
\r
**文档版本**: 1.0\r
**最后更新**: [Date]\r
**作者**: GitHub Copilot (Claude Sonnet 4.5)\r
```\r
\r
### Quick Reference Template\r
\r
```markdown\r
# [System Name] - 快速参考指南\r
\r
## 📚 一分钟了解\r
\r
**[System Name]** [one-line description]\r
\r
### 核心概念\r
```\r
[Simple flow diagram]\r
Step1 → Step2 → Step3\r
```\r
\r
- **[Concept 1]**：[Description]\r
- **[Concept 2]**：[Description]\r
\r
---\r
\r
## 🎯 何时使用\r
\r
| 场景 | 记录位置 | 类别 |\r
|------|---------|------|\r
| [Trigger] | [Location] | [Type] |\r
\r
---\r
\r
## 📝 记录模板\r
\r
### [Template Type 1]\r
\r
```markdown\r
[Actual template content to copy-paste]\r
```\r
\r
[Continue...]\r
\r
---\r
\r
**版本**: 1.0  \r
**更新**: [Date]  \r
**适用**: [System] v[version]+  \r
\r
**提示**: 保持此指南在手边，快速查阅关键信息！ 📖\r
```\r
\r
## Common Variations\r
\r
### Variation A: Codebase Documentation\r
\r
For documenting a code repository:\r
\r
**Focus on:**\r
- Architecture patterns\r
- API design\r
- Code organization\r
- Development workflow\r
- Testing strategy\r
\r
**Additional diagrams:**\r
- Class diagrams\r
- API flow\r
- Database schema\r
\r
### Variation B: Skill Documentation\r
\r
For documenting an AI agent skill:\r
\r
**Focus on:**\r
- When to trigger\r
- Decision logic\r
- Output format\r
- Integration with other skills\r
\r
**Additional sections:**\r
- Trigger conditions\r
- Examples of good/bad prompts\r
\r
### Variation C: Tool/Library Documentation\r
\r
For documenting a tool or library:\r
\r
**Focus on:**\r
- Installation steps\r
- Configuration options\r
- API reference\r
- Usage examples\r
- Troubleshooting\r
\r
**Additional sections:**\r
- Compatibility matrix\r
- Performance benchmarks\r
\r
### Variation D: Process Documentation\r
\r
For documenting a workflow or methodology:\r
\r
**Focus on:**\r
- Step-by-step procedures\r
- Decision points\r
- Quality gates\r
- Roles and responsibilities\r
\r
**Additional diagrams:**\r
- Swimlane diagrams\r
- Gantt charts\r
\r
## Gotchas\r
\r
⚠️ **Don't create all 4 docs for simple systems** - Use judgment. A 50-line script doesn't need 4 documents.\r
\r
⚠️ **Don't duplicate content** - Each document should have a distinct purpose. Cross-reference instead of copy-paste.\r
\r
⚠️ **Don't skip the index** - Without navigation, users get lost. The index document is crucial for multi-doc suites.\r
\r
⚠️ **Don't use broken Mermaid syntax** - Test diagrams before finalizing. Common errors:\r
- Missing closing quotes\r
- Invalid node IDs\r
- Unsupported diagram features\r
\r
⚠️ **Don't ignore reading time estimates** - Help users plan their time. Be realistic about document length.\r
\r
⚠️ **Don't mix languages inconsistently** - If user requests Chinese, use Chinese for all headings and body text. Keep code/commands in original language.\r
\r
⚠️ **Don't assume prior knowledge** - Define acronyms and technical terms, especially in Quick Reference.\r
\r
⚠️ **Don't forget visual hierarchy** - Use emojis (📖 🎯 💡) and formatting to make docs scannable.\r
\r
## Writing Style Guidelines\r
\r
### For Technical Principles Doc\r
\r
- **Tone**: Academic but accessible\r
- **Depth**: Assume reader wants to understand "why" not just "how"\r
- **Code examples**: Include actual implementations with explanations\r
- **Length**: Don't shy away from detail; this is the deep-dive doc\r
\r
### For Architecture Visualization Doc\r
\r
- **Diagram-first**: Let diagrams tell the story\r
- **Minimal text**: Just enough to explain what you're looking at\r
- **Consistent notation**: Use same colors/shapes for same concepts\r
- **Progressive complexity**: Start simple, add detail gradually\r
\r
### For Quick Reference Doc\r
\r
- **Tone**: Practical and direct\r
- **Format**: Heavy use of tables, lists, and code blocks\r
- **No fluff**: Every sentence should provide actionable information\r
- **Scannable**: Use visual markers (✅ ❌ 🔴 🟢) liberally\r
\r
### For Navigation Index Doc\r
\r
- **Tone**: Welcoming and guiding\r
- **Purpose**: Help users find what they need fast\r
- **Structure**: Clear hierarchy with visual tables\r
- **Empathy**: Anticipate what different users need\r
\r
## Localization\r
\r
When creating Chinese documentation:\r
\r
**Do:**\r
- ✅ Use Chinese for all headings and body text\r
- ✅ Keep technical terms in English within backticks: `SKILL.md`\r
- ✅ Use Chinese punctuation (，。；：)\r
- ✅ Provide clear Chinese translations for concepts\r
- ✅ Use emojis universally (work in all languages)\r
\r
**Don't:**\r
- ❌ Mix English and Chinese in the same sentence without backticks\r
- ❌ Translate file names or commands\r
- ❌ Use English-style comma in Chinese text\r
- ❌ Translate acronyms (keep API as API, not 应用程序接口)\r
\r
## Integration with Other Skills\r
\r
**Pairs well with:**\r
\r
- **self-improvement** - After creating docs, log if you learned better documentation patterns\r
- **proactive-agent** - Proactively offer to update docs when code changes\r
- **agent-customization** - Document your custom skills using this approach\r
\r
## Quality Checklist\r
\r
Before delivering documentation:\r
\r
- [ ] All 4 documents created (or justified why fewer)\r
- [ ] Reading time estimates in index\r
- [ ] At least 8 Mermaid diagrams in Architecture doc\r
- [ ] Quick Reference has copy-paste templates\r
- [ ] Technical Principles explains "why" not just "what"\r
- [ ] Index provides learning paths for 3 personas\r
- [ ] Cross-references between docs work\r
- [ ] No broken Mermaid syntax\r
- [ ] Consistent terminology across all docs\r
- [ ] Each doc has version and last-updated date\r
- [ ] Troubleshooting section in Quick Reference\r
- [ ] File tree diagrams use consistent formatting\r
- [ ] Tables are aligned and complete\r
- [ ] Code blocks have language specified\r
- [ ] Chinese localization follows guidelines (if applicable)\r
\r
## Example Prompt Patterns\r
\r
**To trigger this skill:**\r
\r
✅ Good prompts:\r
- "当前skill的原理是什么，写一份详尽文档"\r
- "Write comprehensive documentation for this codebase"\r
- "Document the architecture with diagrams"\r
- "Create a quick reference guide and full technical docs"\r
\r
✅ Clarifying questions (if needed):\r
- "Who is the primary audience?" (if unclear)\r
- "Is this for internal use or public consumption?"\r
- "Do you need Chinese or English documentation?"\r
\r
❌ Avoid confusion with:\r
- "Write a README" (too vague - might just need one doc)\r
- "Add comments to the code" (different skill)\r
- "Create API documentation" (use API-specific skill if available)\r
\r
## Related\r
\r
- **agent-customization** - For creating SKILL.md files specifically\r
- **self-improvement** - For logging documentation patterns you discover\r
- **proactive-agent** - For maintaining docs over time\r
\r
## Source\r
\r
- **Created**: 2026-03-05\r
- **Origin**: Extracted from conversation where comprehensive docs were created for self-improving-agent skill\r
- **Pattern**: Successfully applied to document a complex AI agent skill with multiple subsystems\r
- **Validation**: Created 4 documents totaling ~13,000 words with 10+ diagrams\r
\r
---\r
\r
**Note:** This skill produces 5,000-15,000 words of documentation. Budget 1-2 hours for complete execution on complex systems.\r
\r
**Tip:** Start by reading core files in parallel to save time. The understanding phase is critical - don't rush it.\r
\r
**Remember:** Different users need different depths. The layered approach ensures everyone finds what they need. 📚\r