Technical Principles (深度原理解析) - For developers who want to understand deeply
Architecture Visualization (架构图表) - For visual learners and architects
Quick Reference Guide (快速参考) - For everyone who needs practical info fast
Navigation Index (文档索引) - For first-time users to find their way

🎯 When to Use

Trigger phrases:

"写技术文档"
"Write comprehensive documentation"
"Explain how this works"
"Document the architecture"
"Create technical docs"

📁 Files

comprehensive-tech-documentation/
├── SKILL.md                    # Main skill definition (you are here)
├── README.md                   # This overview
├── assets/                     # Templates
│   ├── technical-principles-template.md
│   ├── quick-reference-template.md
│   └── mermaid-examples.md
└── references/                 # Examples
    ├── example-output.md       # Sample documentation output
    └── documentation-patterns.md

🚀 Quick Start

As an AI Agent

When user asks to document something:

Understand: Read core project files (SKILL.md, configs, main code)
Analyze: Extract architecture, data flow, key concepts
Create: Generate the 4-document suite following the workflow in SKILL.md
Visualize: Add 10+ Mermaid diagrams to Architecture doc
Quality check: Verify completeness using checklist

As a Human

To use this skill with your AI agent:

You: "写技术文档 for [project-name]"

Agent: [Reads project files, creates documentation suite]

Or be more specific:

You: "Create comprehensive documentation for this OpenClaw skill.
Include Chinese language with English technical terms."

Agent: [Creates 4 documents with proper localization]

📊 Output Structure

Typical output for a complex system:

project/
├── 技术原理文档.md             # 6000-8000 words, 45-60 min read
├── 架构与流程可视化.md          # 10-15 Mermaid diagrams, 20-30 min
├── 快速参考指南.md             # 3000 words, 10-15 min read
└── README-文档索引.md          # Navigation hub, 5 min read

Total: ~13,000 words, 3-4 hours of user reading time

💡 Key Features

✅ Layered approach - Different depths for different needs
✅ Visual-first - Heavy use of diagrams and charts
✅ Practical - Copy-paste templates and commands
✅ Scannable - Tables, emojis, visual hierarchy
✅ Localized - Proper Chinese/English mixing
✅ Cross-referenced - Documents link to each other
✅ Quality-checked - Built-in verification checklist

🎓 Documentation Philosophy

From the skill:

The mindset shift: Don't create one massive document that no one reads. Create a documentation system where each document has a clear purpose and audience.

Core principles:

Serve different readers - Quick-starters vs deep-divers
Visual + Text - Diagrams are often clearer than prose
Practical first - Templates and examples before theory
Navigate explicitly - Index document is not optional
Quality over speed - Take time to understand before documenting

📝 Example Use Cases

✅ Perfect for:

OpenClaw skills (like self-improving-agent)
Complex codebases with multiple subsystems
System architectures with data flows
Tools and libraries with configuration
Workflows and methodologies

⚠️ Overkill for:

Simple scripts (<100 lines)
Single-purpose utilities
Well-documented external libraries (just add integration notes)

agent-customization - For creating SKILL.md specifically
self-improvement - Log documentation patterns learned
proactive-agent - Maintain docs proactively as code evolves

🏆 Success Metrics

A successful documentation suite should:

✅ Allow a new user to get started in <15 minutes (Quick Reference)
✅ Give an architect complete understanding in <30 minutes (Architecture)
✅ Enable a developer to contribute in <60 minutes (Technical Principles)
✅ Let anyone find what they need in <5 minutes (Index)

📈 Evolution

v1.0 (2026-03-05)

Initial extraction from self-improving-agent documentation work
4-document structure defined
Chinese localization guidelines
Quality checklist
Mermaid diagram standards

Future enhancements:

Auto-generate from code comments
Interactive diagram generation
Multi-language support beyond Chinese/English
Integration with documentation hosting platforms

🤝 Contributing

To improve this skill:

Use it to document a project
Note what works and what doesn't
Log learnings to .learnings/LEARNINGS.md
When pattern is validated, update this SKILL.md

📄 License

MIT - Use freely, modify, share

Created by: Extracted from conversation with user liuxxxu
Proven on: self-improving-agent v1.0.11 documentation
Output: ~13,000 words across 4 documents, 10+ diagrams

Remember: Great documentation is about empathy - understanding what your reader needs and delivering it in the format they prefer. 📚✨

README.md

Comprehensive Technical Documentation Skill

📖 What This Does