diataxis

Use when a documentation request is ambiguous, involves planning a docs structure, or a page seems to mix multiple purposes. Classifies content into Diátaxis quadrants (tutorial, how-to, reference, explanation), proposes a documentation map, and produces a writing plan with ordering. Triggers on phrases like "plan my docs", "what docs do I need", "help me organise my documentation", "docs architecture", "I need to write docs for my project", or when a user asks for a README and a full docs set together.

Use when the user asks to review, audit, improve, classify, or reorganise existing documentation — for a single page or a whole docs set. Evaluates docs against Diátaxis principles: type fit, boundary discipline, user fit, structure, and quality. Returns concrete prioritised fixes and, where needed, recommends splitting overloaded pages. Triggers on phrases like "review my docs", "audit the documentation", "what's wrong with this guide", "improve this README", "tell me what's wrong".

Use when the user asks for conceptual guides, architecture overviews, design rationale, trade-off discussions, background on how a subsystem works, historical context, or "why is it built this way?" documentation. Creates understanding-oriented content that builds mental models — the why, not the how. Do not use for direct task execution (use how-to) or factual lookup (use reference).

Use when the user asks for a how-to guide, step-by-step instructions for a specific goal, troubleshooting guide, configuration guide, deployment steps, migration guide, or operational runbook. Creates goal-oriented guides for competent users who know what they want to achieve. The reader already understands the basics — this is about getting work done. Do not use for beginner onboarding (use tutorial) or conceptual background (use explanation).

Use when the user asks for a README, a GitHub front page, an open source library landing page, or a documentation homepage for a repository. Writes the README as a front door that orients readers and routes them to the right deeper docs — not a tutorial, not a full reference manual, not a conceptual essay. Use a different diataxis skill when the request is specifically for a step-by-step lesson, a task guide, API details, or conceptual background.