Add docs-review skill for PR suggestions

[ask-bonk]

Done. Here's a summary of what was created:

New skill: .agents/skills/docs-review/

Files created

• SKILL.md (192 lines) — Main skill definition
• references/content-rules.md (78 lines) — Detailed review checklist

What the skill covers

When to suggest vs. edit — Decision table mapping instructions like "review", "suggest changes", "only make suggestions", "fix", "address this" to the correct action (post suggestions vs. edit files). Defaults to suggestions unless explicitly told to edit.

gh CLI suggestion API — Concrete, copy-paste examples for:

• Single-line suggestions (-F line=N)
• Multi-line suggestions (-F start_line=N -F line=M)
• Plain review comments (no suggestion block)
• Batched reviews (single API call with --input - and JSON body for 3+ comments)

Key rules derived from PR research:

• Use -F (not -f) for numeric fields
• Always set side="RIGHT" and subject_type="line"
• Line numbers reference the new file side of the diff
• Keep prose before suggestion blocks to one sentence

Content review principles — Distilled from ~30 PRs with @elithrar and @irvinebroque feedback:

• Link to sources of truth instead of re-explaining (from Sandbox: production preview URL setup guide for subdomains, request flow, and troubleshooting #28382 — irvinebroque on error codes)
• Substantiate claims with evidence (from Document undocumented siteverify fields #28259 — elithrar on siteverify, Sandbox: production preview URL setup guide for subdomains, request flow, and troubleshooting #28382 — irvinebroque on Next.js)
• Be direct about recommendations (from [Workers] add best practices guide #28295 — irvinebroque on Hyperdrive)
• Qualify scope of statements (from [Workers] add best practices guide #28295 — irvinebroque on bindings)
• Use correct components: TypeScriptExample, WranglerConfig, PackageManagers (from Fix Images docs code examples (7 files) #28396, Add docs for wrangler dev + tunnels #28228, Merge R2 upload & multipart docs #28186 — elithrar)
• Keep changes in scope (from Fix Queues docs code examples & types #28192 — elithrar on skills/ files)
• Research before asserting (from Updated 4 Agents guides to latest #28319 — threepointone on Env types)

Closes #28413

github run

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
*	@cloudflare/pcx-technical-writing

[ask-bonk]

Here's a summary of the changes:

1. Fixed suggest-vs-edit bias (SKILL.md)

Replaced the flat table + "default to suggestions" with a three-step decision logic:

1. Explicit instruction wins — "suggest" means suggest, "fix" means fix
2. Different actor = suggest — when the invoker is not the PR author, post suggestions so the author retains control
3. Same actor or ambiguous = fix by default — MDX syntax errors, broken code, invalid frontmatter, wrong component usage should always be fixed directly

The old default ("suggestions unless clearly asked for edits") is gone. The new default is: fix obvious errors, suggest subjective changes.

2. Reduced duplication with code-review skill (content-rules.md)

• Removed 3 items from "Code Examples" that duplicated code-review guidance (error handling, any types, hardcoded secrets). The code-review skill covers these in depth across common-patterns.md (Error Handling, Security sections) and its anti-patterns table.
• Renamed the section to "Code Examples — Component Usage" to clarify its scope: which docs component to use, not code correctness.
• Replaced the inline file paths in "Content Accuracy" (node_modules/@cloudflare/workers-types/...) with a paragraph that cross-references the code-review skill's sources.
• Added a row to the SKILL.md quick-reference table pointing to the code-review skill for type/API/binding validation.

The code-review skill itself was not modified — its guidance is already more detailed and authoritative for code correctness concerns.

github run

[github-actions]

Preview URL: https://6337108c.preview.developers.cloudflare.com
Preview Branch URL: https://opencode-issue28413-20260218120149.preview.developers.cloudflare.com

[ctdsf]

Thanks for the help i dont know wtf im doing but thanks