[agent-setup] Improvements & updates to agent setup instructions - #32610
Draft
ajhawkings wants to merge 1 commit into
Draft
[agent-setup] Improvements & updates to agent setup instructions#32610ajhawkings wants to merge 1 commit into
ajhawkings wants to merge 1 commit into
Conversation
- Adds desktop app apps in agent setup instructions - Users filtering by desktop app will be taken to the desktop app tab in the setup pages - Removes redundant mcp servers just leaving the codemode server - Update install instructions for multiple agents - Prioritise installing skills + MCPs via plugins where possible (more agents will support plugins in very near future due to the Agent Plugins 1.0 spec having just released) - Change instructions to install plugin before launching the agent so that the user doesn't have to reload
github-actions
Bot
added
size/l
product:agents
Contributor
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
Contributor
ajhawkings
marked this pull request as ready for review
August 7, 2026 18:22
ajhawkings
requested review from
a team,
elithrar,
irvinebroque,
kodster28 and
rita3ko
as code owners
August 7, 2026 18:22
Contributor
Review
👉 Fix in your agent 👈Fix the following review findings in PR #32610 (https://github.com/cloudflare/cloudflare-docs/pull/32610).
Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g. the fix requires disproportionate effort for minimal benefit,
or the finding is factually incorrect), explain why
- If you need clarification before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order
After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.
The comment must come before the commit — the bot reads PR comments when a new
push triggers a review, so skip comments posted after the push will be missed.
---
## Code Review
### Warnings (4)
#### CR-962b6ddd63b2 · Inconsistent configuration filename
- **File:** `src/content/docs/agent-setup/opencode.mdx` line 46
- **Issue:** The quick-start steps (lines 46 and 88) tell users to put the MCP configuration in `opencode.json`, but the unchanged FAQ (line 141) and troubleshooting (line 168) still refer to `.opencode.jsonc`. Users will be unsure which file OpenCode actually reads.
- **Fix:** Make the documentation consistent: either keep `.opencode.jsonc` in the quick-start or update the FAQ/troubleshooting references to `opencode.json`.
#### CR-1a78b721b844 · Missing Cloudflare MCP servers
- **File:** `src/content/docs/agent-setup/opencode.mdx` line 50
- **Issue:** The new quick-start JSON (lines 50-54 and 90-96) only registers the `cloudflare` MCP server. The previous version of this page and the other agent-setup pages (e.g. windsurf.mdx, github-copilot.mdx) also register `cloudflare-docs`, `cloudflare-bindings`, `cloudflare-builds`, and `cloudflare-observability`. The troubleshooting section still expects a docs-capable MCP server.
- **Fix:** Either add the other Cloudflare MCP servers back to the quick-start config or add a note explaining that the single `cloudflare` server now covers docs/bindings/builds/observability.
#### CR-5392d46bd3a2 · Do not nest Tabs inside Tabs
- **File:** `src/content/docs/agent-setup/claude-code.mdx` line 33
- **Issue:** The Terminal tab's first step introduces a nested `<Tabs>` block for macOS/Linux/Windows install commands inside the outer `<Tabs urlParam="view">`. The repository's component reference prohibits nested tabs and recommends restructuring into separate headings.
- **Fix:** Remove the nested `<Tabs>` and present the macOS/Linux and Windows install instructions as separate sub-steps or headings within the Terminal tab.
#### CR-78356eb20fcd · URL sync ignores manual trigger values
- **File:** `src/components/ui/tabs/tabs.client.ts` line 74
- **Issue:** The click handler reads `event.currentTarget.dataset.nbTabValue` (line 74) and the query-string selector matches `trigger.dataset.nbTabValue` (line 92). Manual `<TabsTrigger>` elements emit `data-nb-value` (src/components/ui/tabs/TabsTrigger.astro), not `data-nb-tab-value`, so URL sync will silently fail for the manually-composed `<TabsList>` / `<TabsTrigger>` API.
- **Fix:** Read the trigger value from `trigger.dataset.nbValue ?? trigger.dataset.nbTabValue` so `urlParam` works for both synthesized `<TabItem>` usage and manual trigger usage.
### Suggestions (3)
#### CR-ce4ac9416d15 · Duplicate source of truth for filter keys
- **File:** `src/components/agent-setup/CatalogWithFilter.astro` line 142
- **Issue:** VALID_FILTERS is a separate string[] while the same keys already live in the FILTERS array at the top of the file. Keeping them in sync is manual and easy to miss when a new workflow filter is added, which could cause URL-driven filters to be wrongly rejected by the client-side validation.
- **Fix:** Derive the valid filter list from FILTERS — for example, by exposing the keys via a data attribute or moving the filter definitions to a shared module imported by both the Astro frontmatter and the client script.
#### CR-6e5e49ccd93e · Redundant conditional after unconditional filter
- **File:** `src/components/agent-setup/McpServerList.astro` line 16
- **Issue:** Filtering `allServers` down to only URLs matching `CODE_MODE_URL` makes the `s.data.url === CODE_MODE_URL` check on line 34 and the `BUNDLED.has(s.data.url)` check on line 39 always true.
- **Fix:** Remove the now-redundant conditional checks inside the map, or reconsider whether this component should only show the Code Mode server.
#### CR-c1b6c0c43907 · Misleading type name
- **File:** `src/components/agent-setup/types.ts` line 4
- **Issue:** The exported type `AgentWorkflow` shares its name with the `AgentWorkflow` class from the `agents/workflows` SDK, which is documented extensively throughout this repository. In an agent-setup component, the name reads like the SDK class rather than a local set of setup workflows (terminal/desktop/cloud/extension).
- **Fix:** Rename the type to something scope-specific such as `AgentSetupWorkflow` or `SetupWorkflow` to avoid confusion with the Agents SDK class and potential import conflicts in pages that use both.
---
## Style Guide Review
### Warnings (3)
#### SG-a7b672d69b68 · No nested Tabs
- **File:** `src/content/docs/agent-setup/github-copilot.mdx` line 68
- **Issue:** Inner `<Tabs>` (macOS and Linux / Windows) is nested inside the Terminal tab of the outer `<Tabs urlParam="view">` block
- **Fix:** Restructure the nested tabs into separate headings or place the OS choice before the IDE/Terminal/Desktop split.
#### SG-c24ac4745910 · Do not nest Tabs components
- **File:** `src/content/docs/agent-setup/claude-code.mdx` line 33
- **Issue:** A `<Tabs>` block (lines 33-44) is nested inside the outer `<Tabs urlParam="view">` block (lines 28-97).
- **Fix:** Restructure the OS-specific install instructions into separate headings, steps, or prose instead of nesting a Tabs component inside another Tabs component.
#### SG-984e8eb1b32c · Do not nest tabs
- **File:** `src/content/docs/agent-setup/codex.mdx` line 34
- **Issue:** Line adds a `<Tabs>` block inside an outer `<Tabs urlParam="view">` / `<TabItem label="Terminal">` block.
- **Fix:** Restructure the macOS/Linux and Windows install options into separate headings instead of nested tabs.
### Suggestions (3)
#### SG-d9a9d4a979a6 · Use `refer to` instead of `see the [link]`
- **File:** `src/content/docs/agent-setup/codex.mdx` line 47
- **Issue:** Prose reads `For Homebrew or other install methods, see the [Codex CLI setup guide]...`
- **Fix:** Change to `For Homebrew or other install methods, refer to [Codex CLI setup guide].`
#### SG-e5eee298d7e1 · Serial comma
- **File:** `src/content/docs/agents/model-context-protocol/cloudflare/servers-for-cloudflare/index.mdx` line 13
- **Issue:** clients like [Claude](...), [Windsurf](...), our own [AI Playground](...) or any [SDK...]
- **Fix:** Add a comma before the final `or`: `..., [AI Playground](...), or any [SDK...]`
#### SG-4f503da96743 · Avoid `see [link]`
- **File:** `src/content/docs/agents/model-context-protocol/cloudflare/servers-for-cloudflare/index.mdx` line 55
- **Issue:** For more details about installing skills and MCPs across agents, see [Agent setup](/agent-setup/)
- **Fix:** Use `refer to [Agent setup](/agent-setup/)` (e.g., `For more information, refer to [Agent setup](/agent-setup/).`)
Code ReviewThis code review is in beta and may not always be helpful — use your judgment. Warnings (4)
Suggestions (3)
ConventionsNo convention issues found. Style Guide ReviewWarnings (3)
Suggestions (3)
CommandsOnly codeowners can run commands. Post a comment with the command to trigger it.
|
ajhawkings
marked this pull request as draft
August 7, 2026 22:17
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation checklist