[claude-code-user-docs-review] Claude Code User Documentation Review - 2026-08-22

[github-actions[bot]]

Executive Summary

The docs list Claude Code as a first-class engine, and the example corpus backs that up: 39 workflow files use engine: claude vs. 39 for engine: copilot — real parity. The problem isn't coverage, it's framing and setup gaps: Copilot is repeatedly called the "default" and the "start here" path, gh aw init silently skips Copilot-only automation (custom agent, MCP auto-wiring) for Claude with no replacement documented, and there's a real trap where a Claude Code CLI user's existing CLAUDE_CODE_OAUTH_TOKEN is silently ignored with a misleading error.

Severity Findings

Critical Blockers

• Silent OAuth token rejection with misleading error. CLAUDE_CODE_OAUTH_TOKEN (what a claude login user already has) "are not supported and are ignored if set... the workflow fails with an authentication error from the Claude CLI rather than any message mentioning CLAUDE_CODE_OAUTH_TOKEN." A Claude Code user following muscle memory will hit an opaque failure. — docs/src/content/docs/setup/quick-start.mdx:213

Major Obstacles

• Copilot-only automation on init with no Claude equivalent. gh aw init --engine copilot creates .github/agents/agentic-workflows.md and wires up MCP servers automatically; "Non-Copilot engines skip Copilot-specific artifacts" with no alternative flow documented for Claude users who want the same agent/MCP ergonomics. — docs/src/content/docs/setup/cli.md:159-164
• Copilot framed as the default/easy path. "Built-in engines are GitHub Copilot (default)..." and "If you already have GitHub Copilot, start there — it requires no extra account setup." Both nudge a Claude-only user toward adopting Copilot rather than confirming Claude is equally turnkey. — docs/src/content/docs/introduction/how-they-work.mdx:26, docs/src/content/docs/setup/quick-start.mdx:71
• Anthropic WIF mentioned but not walked through. Quick-start references Anthropic WIF as an alternative to ANTHROPIC_API_KEY but gives no inline setup steps, unlike the API-key path. — docs/src/content/docs/setup/quick-start.mdx:122
• No engine migration/switch guidance. Docs note that removing engine: from frontmatter falls back to Copilot, but nothing explains how to move an existing Copilot workflow to Claude or vice versa. — docs/src/content/docs/setup/quick-start.mdx:116, docs/src/content/docs/setup/cli.md:188

Minor Confusion

• Web search support is ambiguous: "Some engines require third-party MCP servers for web search," and Codex disables it by default with no stated reason or enablement path. — docs/src/content/docs/reference/tools.md:65,68
• Tool operation timeout defaults differ by engine (Claude 60s, Codex 120s) with no rationale given, leaving Claude users unsure if 60s is a hard ceiling. — docs/src/content/docs/reference/tools.md:169
• "Preview" features (Cloud Hypervisor sandbox, API proxy) aren't scoped to specific engines, so it's unclear if they apply to Claude workflows. — docs/src/content/docs/introduction/architecture.mdx:192,288

Engine & Tool Matrix

Engine	Setup	Examples	Auth	Score
Copilot	Full auto (custom agent + MCP wiring on init)	39 files	COPILOT_GITHUB_TOKEN or copilot-requests: write perm	Easiest zero-config path
Claude	Partial — no auto agent/MCP wiring, WIF undocumented inline	39 files (parity with Copilot)	ANTHROPIC_API_KEY (clear) or Anthropic WIF (link-only); OAuth token trap	Strong examples, weaker setup polish
Codex	Same as Claude (non-Copilot path)	11 files (~28% of Claude/Copilot)	CODEX_API_KEY or OPENAI_API_KEY	Fewer examples; web-search off by default, unexplained
Custom	Not automated	1 file	Depends on implementation	Essentially undocumented as a first-class path

Tool support is mostly engine-neutral (10 of 12 classified tools work across all engines per docs/src/content/docs/reference/tools.md), but timeout defaults and web-search enablement are engine-specific and only sparsely explained. Parity observation from the example scan: Claude and Copilot are statistically even in the workflow corpus — the gap is entirely in prose/setup-flow, not example coverage.

Auth Gaps

• ANTHROPIC_API_KEY is documented clearly with a dedicated quick-start tab (docs/src/content/docs/setup/quick-start.mdx:207), the strongest part of the Claude onboarding path.
• Anthropic WIF is referenced as an alternative but has no inline quick-start instructions — users must leave the getting-started flow to find it (quick-start.mdx:122).
• The CLAUDE_CODE_OAUTH_TOKEN rejection is documented but buried in a caveat rather than surfaced as a top-line warning before the auth section, and the resulting CLI error doesn't name the ignored variable, making it hard to self-diagnose (quick-start.mdx:213).
• No documented recovery path once a user hits the OAuth-token failure mode — the fix (switch to ANTHROPIC_API_KEY) isn't spelled out next to the warning.

Recommended Actions

Priority 1

• Add an explicit callout right before/in the Claude auth tab: "If you use claude login locally, that token will NOT work here — set ANTHROPIC_API_KEY instead," to pre-empt the silent-failure trap (quick-start.mdx:207-213).

Priority 2

• Document a Claude-equivalent to the Copilot custom-agent/MCP auto-wiring in gh aw init, or explicitly state "no equivalent exists yet" so users stop searching (cli.md:159-164).
• Add inline Anthropic WIF setup steps to quick-start, matching the API-key path's depth (quick-start.mdx:122).

Priority 3

• Reword "(default)" and "start there" language in how-they-work.mdx:26 and quick-start.mdx:71 to avoid implying Copilot is more supported than Claude, given the example corpus shows parity.
• Add a short "switching engines" note near quick-start.mdx:116 covering what changes (auth secrets, init artifacts) when moving a workflow between engines.

Generated by 📝 Claude Code User Documentation Review · agent · 106.3 AIC · ⌖ 7.31 AIC · ⊞ 6.3K · ◷

• expires on Aug 23, 2026, 4:38 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Claude Code User Documentation Review.

A newer discussion is available at Discussion #55075.