Merge pull request #60 from bmad-code-org/module-contribution-guide

docs: refine prose quality across module contribution guide

Author: bmadcode

docs/explanation/module-configuration.md

@@ -5,7 +5,7 @@ description: How BMad modules handle user configuration through a setup skill, w
 
 BMad modules register their capabilities with the help system and optionally collect user preferences. Multi-skill modules use a dedicated **setup skill** for this. Single-skill standalone modules handle registration themselves on first run.
 
-When you create your own custom module, you can choose to either add a configuration skill, or you could just add the feature to every skill following the standalone pattern. for modules with more than 1-2 skills, it would be recommended to just have a setup skill.
+When you create your own module, you can either add a configuration skill or embed the feature in every skill following the standalone pattern. For modules with more than 1-2 skills, a setup skill is the better choice.
 
 ## When You Need Configuration
 
@@ -32,7 +32,7 @@ Module registration serves two purposes:
 
 ### Why Register with the Help System?
 
-The `bmad-help` skill reads `module-help.csv` to understand what capabilities are available, detect which ones have been completed (by checking output locations for artifacts), and recommend next steps based on the dependency graph. Without registration, `bmad-help` cannot discover or recommend your module's capabilities beyond what it knows basically from skill headers. the help provides richer potential info such as args, relationship to other skills, inputs and outputs, and any other relevant authored information. also if you have a skill with multiple capabilities, they each have their own help entry.
+The `bmad-help` skill reads `module-help.csv` to understand what capabilities are available, detect which ones have been completed (by checking output locations for artifacts), and recommend next steps based on the dependency graph. Without registration, `bmad-help` cannot discover or recommend your module's capabilities beyond what it knows basically from skill headers. The help system provides richer detail: arguments, relationships to other skills, inputs and outputs, and any other authored metadata. If a skill has multiple capabilities, each one gets its own help entry.
 
 ### Two Registration Paths
 
@@ -82,7 +82,7 @@ Variables with a `prompt` field are presented to the user during setup. The `def
 
 ## Help Registration Without Configuration
 
-You may not need any configurable values but still want to register your module with the help system. This is worth doing when:
+You may not need any configurable values but still want to register your module with the help system. Registration is still worthwhile when:
 
 - The skill description in SKILL.md frontmatter cannot fully convey what the module offers while staying concise
 - You want to express capability sequencing, phase constraints, or other metadata the CSV supports

docs/explanation/progressive-disclosure.md

@@ -3,7 +3,7 @@ title: 'Progressive Disclosure in Skills'
 description: How to structure skills so they load only the context needed at each moment — from frontmatter through dynamic routing to step files
 ---
 
-Progressive disclosure is the technique that separates basic skills from powerful ones. The core idea: never load more context than the agent needs _right now_. This keeps token usage low, prevents context pollution, and makes skills survive long conversations.
+Progressive disclosure is what separates basic skills from powerful ones. The core idea: never load more context than the agent needs _right now_. This keeps token usage low, prevents context pollution, and lets skills survive long conversations.
 
 ## The Four Layers
 

docs/explanation/scripts-in-skills.md

@@ -3,7 +3,7 @@ title: 'Scripts in Skills'
 description: Why deterministic scripts make skills faster, cheaper, and more reliable — and the technical choices behind portable script design
 ---
 
-Scripts are the reliability backbone of a well-built skill. They handle work that has clear right-and-wrong answers — validation, transformation, extraction, counting — so the LLM can focus on what it does best: judgment, synthesis, and creative reasoning.
+Scripts handle work that has clear right-and-wrong answers — validation, transformation, extraction, counting — so the LLM can focus on judgment, synthesis, and creative reasoning.
 
 ## The Problem: LLMs Do Too Much
 
@@ -17,7 +17,7 @@ The pattern shows up everywhere: skills that try to LLM their way through struct
 
 ## The Determinism Boundary
 
-The core design principle is **intelligence placement** — put each operation where it belongs.
+The design principle is **intelligence placement**: put each operation where it belongs.
 
 | Scripts Handle                     | LLM Handles                                      |
 | ---------------------------------- | ------------------------------------------------ |
@@ -92,7 +92,7 @@ import yaml
 
 When a skill invokes this script with `uv run scripts/analyze.py`, the dependency (`pyyaml` in this example) is automatically resolved. The user never sees an install prompt, never needs to manage a virtual environment, and never pollutes their global Python installation.
 
-**Why this matters for skill authoring:** Without PEP 723, skills that needed libraries like `pyyaml` or `tiktoken` would force users to run `pip install` — a jarring, trust-breaking experience that makes users hesitate to adopt the skill.
+Without PEP 723, skills that need libraries like `pyyaml` or `tiktoken` would force users to run `pip install` — a jarring experience that makes people hesitate to adopt the skill.
 
 ## Graceful Degradation
 
@@ -124,4 +124,4 @@ Look for these signal verbs in a skill's requirements — they indicate script o
 | "compare", "diff", "match against" | Comparison       |
 | "scan for", "find all", "list all" | Pattern scanning |
 
-The builders guide you through script opportunity discovery during the build process. The key insight: if you find yourself writing detailed validation logic in a prompt, it almost certainly belongs in a script instead.
+The builders guide you through script opportunity discovery during the build process. If you find yourself writing detailed validation logic in a prompt, it almost certainly belongs in a script instead.

docs/explanation/skill-authoring-best-practices.md

@@ -103,7 +103,7 @@ Graceful degradation: if subagents are unavailable, the main agent does a single
 
 ### Graceful Degradation
 
-Every subagent-dependent feature should have a fallback path. Skills run across different platforms, models, and configurations. A skill that hard-fails without subagents is fragile. A skill that gracefully falls back to sequential processing is robust everywhere.
+Every subagent-dependent feature should have a fallback path. Skills run across different platforms, models, and configurations. A skill that hard-fails without subagents is fragile. One that falls back to sequential processing works everywhere.
 
 ### Verifiable Intermediate Outputs
 

docs/explanation/subagent-patterns.md

@@ -3,7 +3,7 @@ title: 'Subagent Orchestration Patterns'
 description: Six patterns for using subagents effectively — from simple data delegation through persona-driven parallel reasoning to evolutionary systems
 ---
 
-Subagents are isolated LLM instances that a parent skill spawns to handle specific tasks. They have their own context window, receive instructions, and return results. Used well, they keep the parent context small while enabling massive parallel work.
+Subagents are isolated LLM instances that a parent skill spawns to handle specific tasks. Each gets its own context window, receives instructions, and returns results. Used well, they keep the parent context small while enabling parallel work at scale.
 
 All patterns share one principle: **the filesystem is the single source of truth**. Parent context stays tiny (file pointers + high-level plan). Subagents are stateless black boxes — instructions in, response out, isolated context.
 
@@ -101,7 +101,7 @@ The most powerful pattern for quality. Spawn diverse specialists in parallel —
 
 ## Pattern 6: Evolutionary & Emergent Systems
 
-These turn stateless subagents into something that feels alive. All use the filesystem blackboard as connective tissue.
+These turn stateless subagents into something that feels alive. All build on the filesystem blackboard.
 
 | Variant                        | How It Works                                                                                                                      | Best For                                      |
 | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
@@ -114,9 +114,9 @@ These turn stateless subagents into something that feels alive. All use the file
 
 The single most important thing to get right with subagent patterns is **preventing the parent from reading the data it is delegating**. If the parent reads all the files before spawning subagents, the entire pattern is defeated — you have already spent the tokens, bloated the context, and lost the isolation benefit.
 
-This happens more often than you might expect. You write a skill that should spawn subagents to each read a document and return findings. You run it. The parent agent helpfully reads every document first, then passes them to subagents, then collects distilled summaries. The subagents still provide fresh perspectives (a real benefit), but the context savings — the primary reason for the pattern — are gone.
+This happens often. You write a skill that should spawn subagents to each read a document and return findings. You run it. The parent agent helpfully reads every document first, then passes them to subagents, then collects distilled summaries. The subagents still provide fresh perspectives, but the context savings — the primary reason for the pattern — are gone.
 
-**The fix is defensive language in your skill.** You need to explicitly tell the parent agent what it should and should not do. The key is being specific without being verbose.
+**The fix is defensive language in your skill.** Explicitly tell the parent agent what it should and should not do. Be specific without being verbose.
 
 :::note[Example from the BMad Quality Optimizer]
 The optimizer's instructions say: **"DO NOT read the target skill's files yourself."** It then tells the parent exactly what it _should_ do: run scripts (which return structured JSON), spawn subagents (which do the reading), and synthesize from their outputs. The parent never touches the raw files.
@@ -131,7 +131,7 @@ The optimizer's instructions say: **"DO NOT read the target skill's files yourse
 | **Use pre-pass scripts**                       | Run a lightweight script that extracts metadata (file names, sizes, structure) so the parent can plan without reading |
 | **Be explicit about the boundary**             | "Your role is ORCHESTRATION. Scripts and subagents do all analysis"                                                   |
 
-**Testing is how you catch this.** Run your skill and watch what actually happens. If you see the parent reading files it should be delegating, tighten the language. This is normal iteration — the builders are tuned with these patterns, but different models and tools may need more explicit guidance. Review the existing BMad quality optimizer prompts (`prompts/quality-optimizer.md`) and scanner agents (`agents/quality-scan-*.md`) for working examples of this defensive language in practice.
+**Test and watch what actually happens.** If the parent reads files it should be delegating, tighten the language. This is normal iteration — the builders are tuned with these patterns, but different models and tools may need more explicit guidance. Review the BMad quality optimizer prompts (`prompts/quality-optimizer.md`) and scanner agents (`agents/quality-scan-*.md`) for working examples of this defensive language.
 
 ## Choosing a Pattern
 

docs/explanation/what-are-bmad-agents.md

@@ -15,7 +15,7 @@ Every skill in the BMad ecosystem is ultimately a skill file, but agents carry t
 | **Capabilities** | Actions the agent can perform, either as internal prompt commands or by calling external skills                        |
 | **Memory**       | A sidecar directory where the agent stores what it learns about you, your preferences, and past interactions           |
 
-Together these create something that feels less like running a command and more like talking to a specialist who already knows you.
+Together, they make the interaction feel less like running a command and more like talking to a specialist who already knows you.
 
 ## How Memory Works
 
@@ -55,6 +55,6 @@ If you are unsure, start with a workflow. You can always wrap it inside an agent
 
 ## Building Agents
 
-The **BMad Agent Builder** (`bmad-agent-builder`) walks you through a six-phase conversational discovery process — from intent through capabilities, requirements, drafting, building, and quality optimization. It produces a ready-to-use skill folder you can drop into your tools' skills directory.
+The **BMad Agent Builder** (`bmad-agent-builder`) walks you through six phases of conversational discovery — intent, capabilities, requirements, drafting, building, and quality optimization — and produces a ready-to-use skill folder you can drop into your tools' skills directory.
 
 See the [Builder Commands Reference](/reference/builder-commands.md) for details on the build process phases and capabilities.

docs/explanation/what-are-modules.md

@@ -18,7 +18,7 @@ The `.claude-plugin/` convention originates from Claude Code, but the format wor
 
 The Module Builder generates the appropriate `marketplace.json` during the Create Module (CM) step - but you will want to verify it lists the proper relative paths to the skills you want to deliver with your module.
 
-This is very powerful also if you want to include remote URL skills in your own module to combine them.
+This also means you can include remote URL skills in your own module to combine them.
 
 ## What a Module Contains
 
@@ -43,7 +43,7 @@ The first architecture decision when planning a module is whether to use a singl
 | **Hybrid**                         | Some capabilities need persistent persona/memory while others are procedural | Best of both worlds but more skills to build and maintain                                                     |
 
 :::tip[Agent-First Thinking]
-Many users default to building multiple single-purpose agents. Consider whether one agent with rich internal capabilities and routing would serve users better. A single agent accumulates context, maintains memory across interactions, and provides a more seamless experience.
+Many users default to building multiple single-purpose agents. Consider whether one agent with rich internal capabilities and routing would serve users better. A single agent accumulates context, maintains memory across interactions, and provides a smoother experience.
 :::
 
 ## Multi-Agent Modules and Memory
@@ -103,7 +103,7 @@ When a module has external dependencies, the setup skill should check for their
 
 Modules can include user interfaces — dashboards, progress views, interactive visualizations, or even full web applications. A UI skill might show shared progress across the module's capabilities, provide a visual map of how skills relate, or offer an interactive way to navigate the module's features.
 
-Not every module needs a UI. But for complex modules with many capabilities, a visual layer can make the experience significantly more accessible.
+Not every module needs a UI. But for complex modules with many capabilities, a visual layer makes the experience much more accessible.
 
 ## Building a Module
 

docs/explanation/what-are-workflows.md

@@ -3,7 +3,7 @@ title: 'What Are BMad Workflows?'
 description: How workflows guide users through structured processes, how they differ from agents and simple skills, and when to build one
 ---
 
-BMad Workflows are skills that guide users through a **structured process** to produce a specific output. They are the workhorses of the BMad ecosystem — focused, composable, and generally stateless.
+BMad Workflows are skills that guide users through a **structured process** to produce a specific output. They do most of the heavy lifting in the BMad ecosystem — focused, composable, and generally stateless.
 
 ## What Makes a Workflow a Workflow
 
@@ -64,6 +64,6 @@ Workflows are also excellent as the **internal capabilities** of an agent. Build
 
 ## Building Workflows
 
-The **BMad Workflow Builder** (`bmad-workflow-builder`) uses the same six-phase conversational discovery as the Agent Builder — intent, classification, requirements, drafting, building, and quality optimization. It produces a ready-to-use skill folder.
+The **BMad Workflow Builder** (`bmad-workflow-builder`) uses the same six-phase conversational discovery as the Agent Builder — intent, classification, requirements, drafting, building, and quality optimization — and produces a ready-to-use skill folder.
 
 See the [Builder Commands Reference](/reference/builder-commands.md) for details on the build process phases and capabilities.