From 9ffa9ae50bd3b66db52c7dbdfabba488266090c7 Mon Sep 17 00:00:00 2001 From: "ask-bonk[bot]" Date: Wed, 18 Feb 2026 12:07:11 +0000 Subject: [PATCH 1/4] Add docs-review skill for PR suggestions via gh CLI Teaches the agent when and how to post GitHub PR suggestions using the REST API instead of making direct edits. Includes single-line, multi-line, and batched review examples. Content rules reference covers MDX, frontmatter, links, style guide, code examples, and accuracy checks. --- .agents/skills/docs-review/SKILL.md | 192 ++++++++++++++++++ .../docs-review/references/content-rules.md | 77 +++++++ 2 files changed, 269 insertions(+) create mode 100644 .agents/skills/docs-review/SKILL.md create mode 100644 .agents/skills/docs-review/references/content-rules.md diff --git a/.agents/skills/docs-review/SKILL.md b/.agents/skills/docs-review/SKILL.md new file mode 100644 index 000000000000000..349df2e59787486 --- /dev/null +++ b/.agents/skills/docs-review/SKILL.md @@ -0,0 +1,192 @@ +--- +name: docs-review +description: Reviews documentation PRs and provides GitHub PR suggestions. Load when asked to review, suggest changes, or provide feedback on docs content. Covers MDX, frontmatter, style guide, components, and content accuracy. +--- + +Review documentation changes for correctness, style, and structure. Use AGENTS.md and the style guide at `src/content/docs/style-guide/` as primary references. + +## When to Suggest vs. When to Edit + +| Instruction | Action | +| -------------------------------------------------- | ------------------------------------------------------------- | +| "review", "suggest changes", "provide suggestions" | Post **suggestions only** via `gh` CLI — do not push commits | +| "only make suggestions", "do not make changes" | Post **suggestions only** — never edit files or push | +| "fix", "address this", "update" | Edit files directly and commit | +| "review and fix" | Fix low-severity issues directly; suggest high-impact changes | + +Default to **suggestions** unless the instruction clearly asks for direct edits. + +## Posting GitHub Suggestions + +Use the GitHub REST API via `gh api` to post line-level suggestions on PRs. This is the **only** way to propose changes when operating in suggestion-only mode. + +### Prerequisites + +Determine the PR number and the latest commit SHA before posting: + +```bash +PR_NUMBER=$(gh pr view --json number -q '.number') +COMMIT_SHA=$(gh pr view --json commits -q '.commits[-1].oid') +``` + +### Single-line suggestion + +Replace one line in the diff. Use `subject_type: "line"`. + +````bash +gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \ + -f body='Tighten the phrasing: + +```suggestion +Workers use an event-driven architecture. Each incoming request triggers a `fetch` handler. +```' \ + -f commit_id="${COMMIT_SHA}" \ + -f path="src/content/docs/workers/get-started/index.mdx" \ + -F line=42 \ + -f side="RIGHT" \ + -f subject_type="line" +```` + +### Multi-line suggestion + +Replace a range of lines. Add `start_line` and `start_side`. + +````bash +gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \ + -f body='Simplify this paragraph: + +```suggestion +Bindings provide direct, in-process access to Cloudflare services like R2, KV, and D1. +They require no network hop, no authentication token, and add no extra latency. +```' \ + -f commit_id="${COMMIT_SHA}" \ + -f path="src/content/docs/workers/runtime-apis/bindings.mdx" \ + -F start_line=18 \ + -F line=22 \ + -f start_side="RIGHT" \ + -f side="RIGHT" \ + -f subject_type="line" +```` + +### Comment without suggestion + +For feedback that does not map to a specific replacement, post a plain review comment (no suggestion block): + +```bash +gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/comments \ + -f body="This claim needs a source. Link to the relevant API reference or remove it." \ + -f commit_id="${COMMIT_SHA}" \ + -f path="src/content/docs/workers/observability/index.mdx" \ + -F line=55 \ + -f side="RIGHT" \ + -f subject_type="line" +``` + +### Rules for suggestion blocks + +- The content inside a `suggestion` fenced block replaces the target line(s) exactly. Include the full replacement text with correct indentation. +- For single-line: set `line` to the diff line number. Do not set `start_line`. +- For multi-line: set `start_line` to the first line and `line` to the last line of the range being replaced. +- Always set `side` to `"RIGHT"` (the new file side of the diff). +- Always set `subject_type` to `"line"`. +- Line numbers refer to the **new file** in the diff (the right side), not the old file. +- Use `-F` (not `-f`) for numeric fields (`line`, `start_line`) so `gh` sends them as integers. +- Keep the prose before the suggestion block to one sentence. Do not over-explain. + +### Batching with a review object + +When posting 3+ suggestions, use a single review with multiple comments to avoid notification spam: + +```bash +gh api repos/{owner}/{repo}/pulls/${PR_NUMBER}/reviews \ + --input - <` in prose must be escaped or in backticks | +| Component imports | Every component used must be imported from `~/components` | +| Code block languages | Must be lowercase and in the supported set (see AGENTS.md) | +| Internal links | Absolute paths, no file extensions, no `https://developers.cloudflare.com` | +| Heading hierarchy | Sequential: H2 then H3 then H4 — never skip | +| Frontmatter | `title` required; `pcx_content_type` must be a valid value | +| Style guide | Active voice, no contractions, "select" not "click", bold for UI elements | +| Workers code | Must use `TypeScriptExample` component, not bare `js`/`ts` fences | +| Config blocks | Must use `WranglerConfig` component with TOML input | +| Accuracy | Claims must be substantiated — link to sources of truth, do not explain inline what other docs cover | + +### 3. Assess What to Flag + +| Flag | Do not flag | +| --------------------------------------------------------------- | ---------------------------------------------------- | +| Incorrect technical content | Style preferences not in the style guide | +| Broken MDX (build will fail) | Pre-existing issues in unchanged lines | +| Wrong API usage or types | "Could be cleaner" when code is correct | +| Missing component usage (`TypeScriptExample`, `WranglerConfig`) | Theoretical concerns without evidence | +| Inaccurate or unsubstantiated claims | Missing features outside the PR scope | +| Security or safety issues in examples | Minor wording differences that do not change meaning | +| Scope creep (changes to files outside the PR intent) | | + +### 4. Prioritize + +Review in severity order: + +1. **Build breakers** — unescaped MDX, missing imports, invalid frontmatter +2. **Incorrect content** — wrong API, wrong behavior description, broken examples +3. **Missing best practices** — no `TypeScriptExample`, hardcoded compat dates, bare code fences +4. **Style and structure** — heading levels, link format, prose quality + +## Content Review Principles + +These principles are derived from recurring review feedback on this repo: + +- **Link to sources of truth.** Do not re-explain concepts that have their own docs page. Link to the canonical page instead. Example: do not explain HTTP error 522 inline — link to `/support/troubleshooting/http-status-codes/`. +- **Substantiate claims.** If docs say "X behaves this way", verify it. Reference source code, API docs, or config schemas. Flag unverified claims. +- **Be direct about recommendations.** "Always use Hyperdrive when connecting to a remote PostgreSQL database" is better than "Connecting directly adds latency; consider using Hyperdrive." +- **Qualify scope.** "Bindings provide direct access to Cloudflare services like R2, KV, and D1" is better than "Bindings provide direct access to Cloudflare services" (which implies all services). +- **Code examples must be safe to copy.** Treat every code block as something a developer will paste into production. Examples must handle errors, use correct types, and follow current best practices. +- **Use the right component.** Workers code should use `TypeScriptExample`. Config should use `WranglerConfig` with `$today` for compatibility dates. Package install commands should use `PackageManagers`. +- **Keep changes in scope.** If a review uncovers issues in files outside the PR, note them but do not fix them in the same PR. +- **Research before asserting.** If uncertain whether an API, flag, or behavior is correct, look it up in the types, schema, or docs before flagging. + +## Output Format + +When posting suggestions, keep commentary minimal. One sentence of context, then the suggestion block. + +When posting a summary comment (not line-level), list issues by severity with file and line references. Severity levels: **CRITICAL** (build break, security) | **HIGH** (incorrect content, wrong API) | **MEDIUM** (missing component, outdated pattern) | **LOW** (minor style, wording) diff --git a/.agents/skills/docs-review/references/content-rules.md b/.agents/skills/docs-review/references/content-rules.md new file mode 100644 index 000000000000000..5596bf372c56f50 --- /dev/null +++ b/.agents/skills/docs-review/references/content-rules.md @@ -0,0 +1,77 @@ +# Content Review Rules + +Checklist for reviewing MDX documentation changes. Each rule includes what to check and how to fix it. + +## MDX Syntax + +| Check | Fix | +| ------------------------------------------------ | ----------------------------------------------------------- | +| `{` `}` in prose (outside code blocks) | Wrap in backticks or escape: `\{` `\}` | +| `<` `>` in prose (outside code blocks) | Use `<` `>` or wrap in backticks | +| Component used without import | Add import from `~/components` after frontmatter | +| Code block without language | Add lowercase language identifier | +| Unsupported code block language | Use `txt` for generic output; check AGENTS.md for full list | +| Capitalized language name (`JSON`, `JavaScript`) | Use lowercase (`json`, `javascript`) | + +## Frontmatter + +| Check | Fix | +| -------------------------- | --------------------------------------------- | +| Missing `title` | Add a descriptive title | +| Invalid `pcx_content_type` | Use a valid value from AGENTS.md list | +| Invalid `tags` | Check against `src/schemas/tags.ts` allowlist | +| `reviewed` date in future | Set to today or a past date | + +## Links + +| Check | Fix | +| ---------------------------------------------------------- | ------------------------------------------- | +| Full URL to docs (`https://developers.cloudflare.com/...`) | Use root-relative path (`/workers/...`) | +| Relative file link (`./page`) | Use root-relative path (`/workers/page/`) | +| File extension in link (`/workers/page.mdx`) | Remove extension (`/workers/page/`) | +| Missing trailing slash (`/workers/page`) | Add trailing slash (`/workers/page/`) | +| Vague link text ("here", "this page", "read more") | Use descriptive text: the target page title | + +## Headings + +| Check | Fix | +| ---------------------------------------------- | ----------------- | +| Skipped heading level (H2 then H4) | Insert missing H3 | +| H1 in content (only frontmatter title uses H1) | Demote to H2 | + +## Style Guide + +| Check | Fix | +| ---------------------------------- | -------------------------------------------------------- | +| Contractions ("don't", "can't") | Expand ("do not", "cannot") | +| "click" for UI actions | Use "select" | +| "navigate to" | Use "go to" | +| "enable/disable" | Use "turn on/turn off" | +| UI element not bolded | Bold clickable elements: **Save**, **DNS** > **Records** | +| Code/paths/IPs not in monospace | Wrap in backticks | +| `$` prefix in terminal commands | Remove — copy button copies verbatim | +| Two trailing spaces for line break | Use `
` | +| Passive voice | Rewrite in active voice | + +## Code Examples + +| Check | Fix | +| ----------------------------------------- | ------------------------------------------------ | +| Workers JS/TS in bare code fence | Use `TypeScriptExample` component | +| Wrangler config in bare code fence | Use `WranglerConfig` component with TOML input | +| Hardcoded compatibility date | Use `$today` in `WranglerConfig` | +| Package install without `PackageManagers` | Use `PackageManagers` component | +| `js` fence for Workers code | Convert to TypeScript first | +| Missing error handling in examples | Add minimal null checks and fetch error handling | +| `any` type in examples | Use proper types | +| Hardcoded secrets or API keys | Use `env` bindings | + +## Content Accuracy + +| Check | Action | +| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | +| Unverified API behavior claim | Look up in types (`node_modules/@cloudflare/workers-types/index.d.ts`) or config schema (`node_modules/wrangler/config-schema.json`) | +| Inline explanation of something with its own docs page | Replace with link to canonical page | +| Recommendation without rationale | Add brief "why" or link to supporting docs | +| Outdated API pattern | Check latest types and update | +| Nested tabs (tabs inside tabs) | Restructure into separate headings | From 28b2210406f6f11c8db44ad1062fc776fc6b9312 Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Wed, 18 Feb 2026 07:16:33 -0500 Subject: [PATCH 2/4] Apply suggestion from @elithrar --- .agents/skills/docs-review/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/docs-review/SKILL.md b/.agents/skills/docs-review/SKILL.md index 349df2e59787486..241264e30a16a61 100644 --- a/.agents/skills/docs-review/SKILL.md +++ b/.agents/skills/docs-review/SKILL.md @@ -11,7 +11,7 @@ Review documentation changes for correctness, style, and structure. Use AGENTS.m | -------------------------------------------------- | ------------------------------------------------------------- | | "review", "suggest changes", "provide suggestions" | Post **suggestions only** via `gh` CLI — do not push commits | | "only make suggestions", "do not make changes" | Post **suggestions only** — never edit files or push | -| "fix", "address this", "update" | Edit files directly and commit | +| "fix", "address this", "update" | Always edit files directly and commit changes | | "review and fix" | Fix low-severity issues directly; suggest high-impact changes | Default to **suggestions** unless the instruction clearly asks for direct edits. From 828e89960c1823cdf07ff91d23ad87d754ffe887 Mon Sep 17 00:00:00 2001 From: "ask-bonk[bot]" Date: Wed, 18 Feb 2026 12:23:03 +0000 Subject: [PATCH 3/4] Fix suggest-vs-edit bias and reduce duplication with code-review skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rewrite decision logic: fix obvious errors by default (MDX syntax, broken code, invalid frontmatter), only suggest when explicitly asked or when the invoker differs from the PR author - Remove duplicated code correctness checks (error handling, any types, hardcoded secrets) from content-rules.md — defer to code-review skill - Add cross-references to code-review skill for type checking, API usage, and binding patterns - Slim down Content Accuracy table to reference shared sources instead of inlining paths already documented in code-review --- .agents/skills/docs-review/SKILL.md | 25 ++++++++---- .../docs-review/references/content-rules.md | 39 ++++++++++--------- 2 files changed, 38 insertions(+), 26 deletions(-) diff --git a/.agents/skills/docs-review/SKILL.md b/.agents/skills/docs-review/SKILL.md index 241264e30a16a61..dbc9ff7fbfb4c12 100644 --- a/.agents/skills/docs-review/SKILL.md +++ b/.agents/skills/docs-review/SKILL.md @@ -7,14 +7,24 @@ Review documentation changes for correctness, style, and structure. Use AGENTS.m ## When to Suggest vs. When to Edit -| Instruction | Action | -| -------------------------------------------------- | ------------------------------------------------------------- | -| "review", "suggest changes", "provide suggestions" | Post **suggestions only** via `gh` CLI — do not push commits | -| "only make suggestions", "do not make changes" | Post **suggestions only** — never edit files or push | -| "fix", "address this", "update" | Always edit files directly and commit changes | -| "review and fix" | Fix low-severity issues directly; suggest high-impact changes | +### Decision logic -Default to **suggestions** unless the instruction clearly asks for direct edits. +1. **Explicit instruction wins.** If the user says "suggest", "only make suggestions", or "do not make changes" — post suggestions via `gh` CLI, never push commits. If they say "fix", "address this", or "update" — edit files directly and commit. +2. **Different actor = suggest.** If the person invoking the review is not the PR author (and no explicit fix instruction was given), post suggestions so the author retains control. +3. **Same actor or ambiguous = fix by default.** When the invoker is the PR author (or it is unclear), default to **editing files directly**. MDX syntax errors, broken code, invalid frontmatter, wrong component usage, and other obvious errors should always be fixed, not suggested. + +### Quick reference + +| Instruction | Action | +| -------------------------------------------------- | --------------------------------------------------------------------- | +| "review", "suggest changes", "provide suggestions" | Post **suggestions only** via `gh` CLI — do not push commits | +| "only make suggestions", "do not make changes" | Post **suggestions only** — never edit files or push | +| "fix", "address this", "update" | Always edit files directly and commit changes | +| "review and fix" | Fix low-severity issues directly; suggest high-impact changes | +| Invoked by someone other than PR author | Post suggestions unless explicitly told to fix | +| Invoked by PR author (or unclear) | Fix directly — especially MDX syntax, code errors, and build breakers | + +When in doubt, **fix obvious errors** (build breakers, MDX syntax, wrong imports, broken code) and **suggest subjective changes** (wording, restructuring, style preferences). ## Posting GitHub Suggestions @@ -149,6 +159,7 @@ See `references/content-rules.md` for the full checklist. Quick reference: | Style guide | Active voice, no contractions, "select" not "click", bold for UI elements | | Workers code | Must use `TypeScriptExample` component, not bare `js`/`ts` fences | | Config blocks | Must use `WranglerConfig` component with TOML input | +| Code correctness | For type checking, API usage, and binding patterns, load the `code-review` skill | | Accuracy | Claims must be substantiated — link to sources of truth, do not explain inline what other docs cover | ### 3. Assess What to Flag diff --git a/.agents/skills/docs-review/references/content-rules.md b/.agents/skills/docs-review/references/content-rules.md index 5596bf372c56f50..aa7422685f7f71c 100644 --- a/.agents/skills/docs-review/references/content-rules.md +++ b/.agents/skills/docs-review/references/content-rules.md @@ -53,25 +53,26 @@ Checklist for reviewing MDX documentation changes. Each rule includes what to ch | Two trailing spaces for line break | Use `
` | | Passive voice | Rewrite in active voice | -## Code Examples - -| Check | Fix | -| ----------------------------------------- | ------------------------------------------------ | -| Workers JS/TS in bare code fence | Use `TypeScriptExample` component | -| Wrangler config in bare code fence | Use `WranglerConfig` component with TOML input | -| Hardcoded compatibility date | Use `$today` in `WranglerConfig` | -| Package install without `PackageManagers` | Use `PackageManagers` component | -| `js` fence for Workers code | Convert to TypeScript first | -| Missing error handling in examples | Add minimal null checks and fetch error handling | -| `any` type in examples | Use proper types | -| Hardcoded secrets or API keys | Use `env` bindings | +## Code Examples — Component Usage + +These checks are docs-specific (which component to use). For deeper code correctness (types, API usage, binding access, error handling, security), load the `code-review` skill. + +| Check | Fix | +| ----------------------------------------- | ---------------------------------------------- | +| Workers JS/TS in bare code fence | Use `TypeScriptExample` component | +| Wrangler config in bare code fence | Use `WranglerConfig` component with TOML input | +| Hardcoded compatibility date | Use `$today` in `WranglerConfig` | +| Package install without `PackageManagers` | Use `PackageManagers` component | +| `js` fence for Workers code | Convert to TypeScript first | ## Content Accuracy -| Check | Action | -| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -| Unverified API behavior claim | Look up in types (`node_modules/@cloudflare/workers-types/index.d.ts`) or config schema (`node_modules/wrangler/config-schema.json`) | -| Inline explanation of something with its own docs page | Replace with link to canonical page | -| Recommendation without rationale | Add brief "why" or link to supporting docs | -| Outdated API pattern | Check latest types and update | -| Nested tabs (tabs inside tabs) | Restructure into separate headings | +| Check | Action | +| ------------------------------------------------------ | ------------------------------------------------- | +| Unverified API behavior claim | Verify against types or config schema (see below) | +| Inline explanation of something with its own docs page | Replace with link to canonical page | +| Recommendation without rationale | Add brief "why" or link to supporting docs | +| Outdated API pattern | Check latest types and update | +| Nested tabs (tabs inside tabs) | Restructure into separate headings | + +To verify API behavior, types, or config fields, use the same sources as the `code-review` skill: `node_modules/@cloudflare/workers-types/index.d.ts` for APIs and `node_modules/wrangler/config-schema.json` for config. Read these files directly — do not rely on pre-training. From 6337108c6453414ac415744f5862ca52f01620c6 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 18 Feb 2026 14:47:16 +0000 Subject: [PATCH 4/4] Apply suggestions from code review --- .agents/skills/docs-review/references/content-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/docs-review/references/content-rules.md b/.agents/skills/docs-review/references/content-rules.md index aa7422685f7f71c..662ce2edbeefb37 100644 --- a/.agents/skills/docs-review/references/content-rules.md +++ b/.agents/skills/docs-review/references/content-rules.md @@ -52,7 +52,7 @@ Checklist for reviewing MDX documentation changes. Each rule includes what to ch | `$` prefix in terminal commands | Remove — copy button copies verbatim | | Two trailing spaces for line break | Use `
` | | Passive voice | Rewrite in active voice | - +| "See" | Use "Refer to" | ## Code Examples — Component Usage These checks are docs-specific (which component to use). For deeper code correctness (types, API usage, binding access, error handling, security), load the `code-review` skill.