diff --git a/.agents/skills/merge-pr/SKILL.md b/.agents/skills/merge-pr/SKILL.md
index 4d8f01f4cf8..54d6439f212 100644
--- a/.agents/skills/merge-pr/SKILL.md
+++ b/.agents/skills/merge-pr/SKILL.md
@@ -104,6 +104,8 @@ Stop if any are true:
 - Required checks are failing.
 - Branch is behind main.
 
+If `.local/prep.md` contains `Docs-only change detected with high confidence; skipping pnpm test.`, that local test skip is allowed. CI checks still must be green.
+
 ```sh
 # Checks
 gh pr checks <PR>
diff --git a/.agents/skills/prepare-pr/SKILL.md b/.agents/skills/prepare-pr/SKILL.md
index 8a7450cc3d6..fe56b10a118 100644
--- a/.agents/skills/prepare-pr/SKILL.md
+++ b/.agents/skills/prepare-pr/SKILL.md
@@ -38,7 +38,7 @@ Prepare a PR branch for merge with review fixes, green gates, and an updated hea
 
 - Rebase PR commits onto `origin/main`.
 - Fix all BLOCKER and IMPORTANT items from `.local/review.md`.
-- Run gates and pass.
+- Run required gates and pass (docs-only PRs may skip `pnpm test` when high-confidence docs-only criteria are met and documented).
 - Commit prep changes.
 - Push the updated HEAD back to the PR head branch.
 - Write `.local/prep.md` with a prep summary.
@@ -163,17 +163,46 @@ If `committer` is not found:
 git commit -m "fix: <summary> (#<PR>) (thanks @$contrib)"
 ```
 
-8. Run full gates before pushing
+8. Decide verification mode and run required gates before pushing
+
+If you are highly confident the change is docs-only, you may skip `pnpm test`.
+
+High-confidence docs-only criteria (all must be true):
+
+- Every changed file is documentation-only (`docs/**`, `README*.md`, `CHANGELOG.md`, `*.md`, `*.mdx`, `mintlify.json`, `docs.json`).
+- No code, runtime, test, dependency, or build config files changed (`src/**`, `extensions/**`, `apps/**`, `package.json`, lockfiles, TS/JS config, test files, scripts).
+- `.local/review.md` does not call for non-doc behavior fixes.
+
+Suggested check:
+
+```sh
+changed_files=$(git diff --name-only origin/main...HEAD)
+non_docs=$(printf "%s\n" "$changed_files" | grep -Ev '^(docs/|README.*\.md$|CHANGELOG\.md$|.*\.md$|.*\.mdx$|mintlify\.json$|docs\.json$)' || true)
+
+docs_only=false
+if [ -n "$changed_files" ] && [ -z "$non_docs" ]; then
+  docs_only=true
+fi
+
+echo "docs_only=$docs_only"
+```
+
+Run required gates:
 
 ```sh
 pnpm install
 pnpm build
 pnpm ui:build
 pnpm check
-pnpm test
+
+if [ "$docs_only" = "true" ]; then
+  echo "Docs-only change detected with high confidence; skipping pnpm test." | tee -a .local/prep.md
+else
+  pnpm test
+fi
 ```
 
-Require all to pass. If something fails, fix, commit, and rerun. Allow at most 3 fix and rerun cycles. If gates still fail after 3 attempts, stop and report the failures. Do not loop indefinitely.
+Require all required gates to pass. If something fails, fix, commit, and rerun. Allow at most 3 fix and rerun cycles. If gates still fail after 3 attempts, stop and report the failures. Do not loop indefinitely.
 
 9. Push updates back to the PR head branch
 
@@ -245,4 +274,4 @@ Otherwise, list remaining failures and stop.
 - Do not delete the worktree on success. `/mergepr` may reuse it.
 - Do not run `gh pr merge`.
 - Never push to main. Only push to the PR head branch.
-- Run and pass all gates before pushing.
+- Run and pass all required gates before pushing. `pnpm test` may be skipped only for high-confidence docs-only changes, and the skip must be explicitly recorded in `.local/prep.md`.