diff --git a/docs/src/content/docs/reference/inline-sub-agents.md b/docs/src/content/docs/reference/inline-sub-agents.md
index e329d194f87..21834413dd1 100644
--- a/docs/src/content/docs/reference/inline-sub-agents.md
+++ b/docs/src/content/docs/reference/inline-sub-agents.md
@@ -36,27 +36,19 @@ You are a file summarization assistant.
 ## end agent: `file-summarizer`
 ```
 
-Use the explicit end marker when:
+Use the explicit end marker when the block appears in the middle of a document — for example via an [import](/gh-aw/reference/imports/) — or when the sub-agent instructions themselves need `##` headings.
 
-- The sub-agent block is embedded in the middle of a document — for example, brought in via an [import](/gh-aw/reference/imports/) — so content that follows it is not accidentally swallowed into the block.
-- The sub-agent's own instructions need to contain `##` headings (structured guidance, section breaks, etc.) without those headings being mistaken for the block's boundary.
+Without an explicit end marker, the block still ends at the next `##` heading or EOF.
 
-Without an explicit end marker, the block still ends at the next `##` heading or EOF, matching the original behavior.
-
-When a sub-agent block is brought in via `{{#runtime-import ...}}` and has no explicit end marker of its own, the runtime import resolver automatically inserts one at the point the implicit boundary would otherwise fall, so the imported block can never expand to swallow content spliced in after it (a subsequent import, or the rest of the workflow body). Authoring an explicit end marker is still recommended for clarity, but this makes every runtime import import-safe by default.
+When a sub-agent block is brought in via `{{#runtime-import ...}}` and has no explicit end marker, the runtime import resolver automatically inserts one at the implicit boundary. This prevents the imported block from swallowing later content, such as another import or the rest of the workflow body. An explicit end marker is still recommended for clarity.
 
 ### Name constraints
 
-- Must start with a lowercase letter (`a–z`)
-- May contain only `a–z`, `0–9`, `_`, and `-`
-- Examples: `file-summarizer`, `code_reviewer`, `pr-analyst`
+Names must start with a lowercase letter (`a–z`) and may contain only `a–z`, `0–9`, `_`, and `-`. Examples: `file-summarizer`, `code_reviewer`, `pr-analyst`.
 
 ### Structure
 
-Each sub-agent block contains:
-
-1. **YAML frontmatter** (optional) — wrapped in `---` delimiters
-2. **Instructions** — natural language prompt for the agent
+Each sub-agent block contains optional YAML frontmatter wrapped in `---` delimiters, followed by the agent instructions.
 
 ```markdown
 ## agent: `file-summarizer`
@@ -129,7 +121,7 @@ The sub-agent block at the bottom is extracted before the workflow runs and has
 
 ## Example: Multiple Sub-Agents in One Workflow
 
-A single workflow file may contain more than one sub-agent block. Each block starts with its own `## agent: \`name\`` heading and ends at a matching `## end agent: \`name\`` marker, the next `##` heading, or EOF.
+A workflow file may contain multiple sub-agent blocks. Each starts with `## agent: \`name\`` and ends at a matching `## end agent: \`name\`` marker, the next `##` heading, or EOF.
 
 ```aw wrap
 ## agent: `summarizer`
@@ -149,8 +141,8 @@ Review the given code for bugs, style issues, and potential improvements.
 
 ## Related Documentation
 
-- [Importing Copilot Agent Files](/gh-aw/reference/copilot-custom-agents/) — Importing agents from `.github/agents/`
-- [DeterministicOps](/gh-aw/patterns/deterministic-ops/) — Combining deterministic steps with AI reasoning
-- [Markdown](/gh-aw/reference/markdown/) — Workflow markdown body reference
-- [Workflow Structure](/gh-aw/reference/workflow-structure/) — Overall workflow file organization
-- [Frontmatter](/gh-aw/reference/frontmatter/) — YAML configuration options
+- [Importing Copilot Agent Files](/gh-aw/reference/copilot-custom-agents/) for agents stored in `.github/agents/`
+- [DeterministicOps](/gh-aw/patterns/deterministic-ops/) for combining deterministic steps with AI reasoning
+- [Markdown](/gh-aw/reference/markdown/) for workflow markdown syntax
+- [Workflow Structure](/gh-aw/reference/workflow-structure/) for overall file organization
+- [Frontmatter](/gh-aw/reference/frontmatter/) for YAML configuration options