diataxis-writing

What This Skill Does

The diataxis-writing skill is an advanced documentation assistant designed to help developers, technical writers, and product managers create high-quality technical content based on the industry-standard Diátaxis framework. The framework classifies all documentation into four distinct categories: Tutorials (learning-oriented), How-to Guides (problem-oriented), Reference (information-oriented), and Explanation (understanding-oriented). This skill acts as an intelligent guide that ensures your documentation is structured correctly to meet specific user needs. It manages the entire lifecycle of a document, from initial requirement gathering and template selection to rigorous quality assessment using predefined checklists. It also integrates with external tools like Feishu via MCP or local file systems to ensure your documentation is published where you need it.

Installation

To install this skill into your OpenClaw agent, execute the following command in your terminal: clawhub install openclaw/skills/skills/amumulam/diataxis-writing Once installed, ensure your local configuration (e.g., ~/.mcporter/mcporter.json) is updated if you intend to use the Feishu document export features.

Use Cases

1. Standardizing internal developer documentation to ensure engineers can find information quickly.
2. Writing user-facing product manuals that distinguish clearly between beginner tutorials and advanced configuration references.
3. Auditing existing documentation repositories to identify gaps in content types.
4. Automating the creation of formatted Markdown documentation files that adhere to best-practice templates.

Example Prompts

1. "I need to write a new tutorial for our API authentication flow. Please use the diataxis-writing skill to guide me through the template and structure."
2. "Can you review my current draft for our 'deployment' page? I want to make sure it functions correctly as a How-to guide rather than an explanation."
3. "Help me create a new reference document for the database schema, I'd like to output it directly to a local Markdown file."

Tips & Limitations

• Tip: Always start by identifying which of the four types your content belongs to; confusing a Tutorial with a Reference is the most common documentation mistake.
• Tip: Leverage the built-in quality assessment step before finalizing your draft; it acts as a gatekeeper to ensure consistency.
• Limitation: The skill relies on the presence of MCP tools for external publishing; if these are not configured, you will be restricted to Chat or local file output.
• Limitation: The skill does not generate actual technical logic or code; it is strictly a content structure and formatting assistant.