diff --git a/.claude/skills/create-pr/SKILL.md b/.claude/skills/create-pr/SKILL.md
index c9d86c00..771e9e35 100644
--- a/.claude/skills/create-pr/SKILL.md
+++ b/.claude/skills/create-pr/SKILL.md
@@ -45,20 +45,22 @@ Use this structure:
 ```markdown
 ## Motivation
 
-<Why this change is needed. 1-2 sentences.>
+<High-level description of the issue or feature this PR addresses. 1-2 sentences a reader can follow without opening the diff.>
 
-## Changes
+## Solution
 
-- Bullet point per meaningful change
-- Group related changes together
+<High-level description of the solution — written so a reviewer can read it and thumbs-up or thumbs-down the approach.>
 
-## Review
+<details>
+<summary>Docs</summary>
 
-<Self-merge candidate — one-line reason. Or: Human review advised — one-line reason.>
+<Context for technical writers to pick up: user-facing changes, new/changed commands, flags, env vars, or behavior worth documenting. Always include this section — when nothing is user-facing, say so explicitly and why (e.g. test-only change, internal refactor), so writers can triage from the PR alone.>
 
-## Tests
+</details>
 
-<How this was tested — new tests added, manual verification, etc.>
+## Review
+
+<Self-merge candidate — one-line reason. Or: Human review advised — one-line reason.>
 
 ## Todo
 
diff --git a/CLAUDE.md b/CLAUDE.md
index dba1270a..fd4c99e0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -87,6 +87,7 @@ When `DOCKER_HOST` isn't set, `DockerRuntime` resolves the daemon endpoint in or
 - Never commit or push unless explicitly asked.
 - PRs are squash-merged; titles start with an action verb and stay under ~70 characters.
 - Every PR needs exactly one `semver:` label (`patch`/`minor`/`major`) and one `docs:` label (`skip`/`needed`) — enforced by `check-release-label.yml`. Use `/create-pr` to scaffold title, body, and labels.
+- PR descriptions follow the Motivation / Solution / Docs / Review structure (template in the `/create-pr` skill): a high-level description of the issue or feature, a solution summary a reviewer can thumbs-up or -down, and a collapsible Docs section technical writers triage from — always present, stating explicitly when there is nothing to document.
 - Issues and tickets live in Linear, not GitHub Issues. Typical flow: Linear issue → branch named from the issue (e.g. `devx-123-...`) → PR body ends with `Closes DEVX-123` (or `Towards DEVX-123` if partial). Ask which Linear team if unclear (e.g. PRO = product, DEVX = developer experience).
 - Small PRs and straightforward bug fixes may merge without a human approval when the author is confident; bigger features/PRs still need review and an approval, as usual. This shifts weight onto self-review rather than lowering the bar — before treating any PR-sized change as done, run `/review-pr` against it, confirm tests pass, and add integration tests per the Testing section below. Before creating a PR, say in the session whether a human review looks advisable and why, and add a short "Review" line in the PR description itself (new/changed user-facing behavior, undiscussed or speculative work → advise review; straightforward, small, already-discussed → self-merge candidate) so the assessment is visible to both the author and anyone reading the PR, not just implied. If unsure, advise review.