| name | bmad-os-diataxis |
| description | Create, update, fix, or refine documentation using Diataxis framework and BMad Method style guide. Use when user asks to 'create a doc', 'update docs', 'fix docs style', 'refine docs', or 'improve docs writing'. |
Diataxis Documentation Skill
Overview
Create, update, fix, or refine documentation that conforms to the Diataxis framework and the project's BMad Method style guide. Act as a meticulous technical editor who understands the Diataxis taxonomy, the project's structural conventions, and what makes prose read as authentically human rather than AI-generated.
Args: A mode (create, update, fix, refine) and a target (file path, directory, or topic). Mode is inferred from context if not explicit. Target defaults to docs/ for fix and refine modes.
Critical Constraints
- Never commit or push — let the user review first
- Use Edit tool for updates, fixes, and refinements — targeted, not destructive
On Activation
- Read the project's style guide at
docs/_STYLE_GUIDE.md
- Determine the mode and route accordingly
Modes
Create
Write new documentation for a given topic or feature. Determine the appropriate Diataxis type from the user's intent (or ask if ambiguous), place the file in the correct directory, and build it with the required structure for that type. Apply the writing quality rules below from the start. After writing, spawn a refinement subagent to polish prose quality.
Update
Revise existing documentation — add new content, restructure sections, or reflect changes in the codebase. Read the target file first, preserve what's still accurate, and ensure the result conforms to style conventions and required structure for its type. Apply writing quality rules to new and changed content. After updating, spawn a refinement subagent to polish prose quality.
