From bmad-utility-skills
Creates, updates, fixes, and refines documentation using the Diataxis framework and BMad Method style guide. Activated when users ask to create, update, fix, or refine docs.
How this skill is triggered — by the user, by Claude, or both
Slash command
/bmad-utility-skills:bmad-os-diataxisThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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.
docs/_STYLE_GUIDE.mdWrite 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.
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.
Scan existing files for structural and formatting violations only. For each file, determine its Diataxis type from location, apply the universal style rules and type-specific structure requirements below, and present a per-file summary of all changes. Does not touch prose quality — use Refine for that.
Improve prose quality of existing documentation without changing structure or meaning. When given a directory, spawn parallel subagents — one per file — for concurrent processing. When given a single file, spawn one subagent. Collect and present the combined per-file summaries when all subagents complete.
Subagent prompt (used for Refine and post-Create/Update polish):
You are a prose quality editor. Read
{skill-path}/references/writing-quality.mdfor the complete pattern reference. Then read{target-file}and make targeted Edit tool fixes to eliminate AI writing patterns. Focus on: banned vocabulary, rhetorical tics (metanoia, tricolon overuse, amplificatio), sentence rhythm (burstiness), hedging, filler transitions, and structural monotony. Preserve all meaning and technical accuracy. Use the Edit tool for each fix. Present a summary of changes when done. Never commit or push.
Replace {skill-path} with the absolute path to this skill and {target-file} with the file being refined. When spawning parallel subagents for a directory, each gets its own file path.
Apply when generating or revising prose (Create, Update, Refine). Not applicable to Fix mode.
| Location | Type |
|---|---|
docs/tutorials/ | Tutorial |
docs/how-to/ | How-to guide |
docs/explanation/ | Explanation |
docs/reference/ | Reference |
docs/glossary/ | Glossary |
Project conventions — apply to all document types, all modes:
---) — Never use outside frontmatter; use ## headers or admonitions instead#### headers — Use bold text or admonitions instead## sections beyond that:::note[Example] admonitions:::caution, :::tip, etc.)## per doc, 2-3 ### per sectionTutorials — Outcome-focused hook, "What You'll Learn" bullets, :::note[Prerequisites], :::tip[Quick Path] TL;DR, tables for phases/commands/agents, "What You've Accomplished", Quick Reference table, Common Questions, Getting Help, :::tip[Key Takeaways]
How-to guides — Hook starting "Use the X workflow to...", "When to Use This" (3-5 bullets), :::note[Prerequisites], numbered ### steps with action verbs, "What You Get" outputs section
Explanation — Hook stating what it explains, scannable ## sections, comparison tables for 3+ options, links to how-to guides for procedural topics, max 2-3 admonitions
Reference — Hook stating what it references, consistent item structure, tables for structured/comparative data, links to explanation docs for depth, max 1-2 admonitions
Glossary — Categories as ## headers, terms in tables (not individual headers), definitions 1-2 sentences max, bold term names
npx claudepluginhub bmad-code-org/bmad-utility-skills --plugin bmad-utility-skillsCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.