[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-07-21

[github-actions[bot]]

Executive Summary

A Claude Code user can onboard end-to-end without ever touching GitHub Copilot — the Claude path is fully documented, with a self-contained auth tab in Quick Start (quick-start.mdx:100-107) and a detailed auth.mdx section (188-278). No critical blockers; overall 7.5/10, unchanged across 30 daily reviews. The one persona-defining friction: Claude subscription OAuth (CLAUDE_CODE_OAUTH_TOKEN) is explicitly unsupported/ignored — the credential a Claude Code user already holds cannot be used; only an ANTHROPIC_API_KEY (or keyless WIF) works.

Severity Findings (Critical → Major → Minor)

🔴 Critical Blockers: None. Copilot-free onboarding is fully possible via gh aw add-wizard --engine claude / gh aw init --engine claude (quick-start.mdx:68-75, cli.md:148).

🟠 Major Obstacles

1. No OAuth / PAT-free path for Claude. "Claude subscription OAuth tokens (CLAUDE_CODE_OAUTH_TOKEN) are not supported and are ignored if set" (quick-start.mdx:105-107; verbatim auth.mdx:206-210, 356). Copilot has a PAT-free org-billing shortcut (copilot-requests: write, auth.mdx:95-119); Claude has no equivalent — every Claude user must create/pay for an Anthropic Console API key. Fix: add a short "why an API key, not your Claude subscription" note beside the caveat, and surface the keyless WIF alternative (auth.mdx:214-278) in Quick Start.
2. Copilot is the silent default everywhere. Omitting engine: yields Copilot (engines.md:16,23; how-they-work.mdx:26); gh aw init emits Copilot-specific skill/agent artifacts unless --engine claude (cli.md:148); 34 of 260 example workflows omit the field entirely. Disclosed only at quick-start.mdx:75, not in prerequisites. Fix: state the default in the prerequisites and put --engine claude in the first add command.
3. Advanced config surfaces are Copilot-only. engine.agent, engine.harness ("only applied during Copilot engine execution"), max-continuations, Copilot SDK/driver, and BYOK are all Copilot-exclusive (engines.md:40,43,178-267,342-373) — 7 copilot-only vs 4 claude-only config surfaces. Fix: a one-line "Copilot-only" badge in the feature table so Claude users don't plan around unavailable features.

🟡 Minor Confusion

• Copilot-first nudge: "If you already have GitHub Copilot, start there — it requires no extra account setup" (quick-start.mdx:30); no why-Claude-vs-Copilot guidance. The ANTHROPIC_API_KEY flow is thinner than Copilot's pre-filled PAT flow (auth.mdx:192-200).
• crush is a listed engine but has zero occurrences — no smoke test, no example (cli.md:260); custom has 0 standalone examples; no default Claude model documented (architecture.mdx:279).

Engine & Tool Matrix

Engine	Setup docs	Examples (.github/workflows)	Auth	Score
Copilot (default)	Richest; wizard PAT flow cli.md:177	124 explicit + 34 implicit ≈ 158	copilot-requests: write (PAT-free) or PAT	9/10
Claude	Self-contained tab quick-start.mdx:100-107 + auth.mdx:188-278	63 (43 inline / 20 object)	ANTHROPIC_API_KEY or keyless WIF; no OAuth	8/10
Codex	Auth tab quick-start.mdx:109-114	15	OPENAI_API_KEY / CODEX_API_KEY	7/10
Gemini	Prereq only, no auth block	1 (smoke only)	GEMINI_API_KEY	5/10
Custom	Overlay only engines.md	0 standalone	inherits engine.env	4/10
pi	—	21 (all object form)	—	6/10
crush	Bootstrap list only	0 (no smoke test)	undocumented	3/10

Tool classification (28 classified): 13 engine-agnostic · 7 copilot-only · 4 claude-only · 2 codex-only · 2 unclear.
Parity for Claude users is strong on tools: all core tools (edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, MCP servers) are engine-agnostic (tools.md:20-210). No Claude-only tool is missing — the copilot-only items are advanced config, not everyday tooling. Claude actually has outsized smoke-test presence: all five smoke-agent-* permission-scenario files use engine: claude.

Ambiguous: web-search is native/opt-in for Codex but MCP-based for others (tools.md:65-67); tools-allowlist enforcement is "No" for OpenCode with no stated replacement (engines.md:44).

Auth Gaps

• Required secrets — Copilot: copilot-requests: write or COPILOT_GITHUB_TOKEN; Claude: ANTHROPIC_API_KEY or WIF (keyless); Codex: OPENAI_API_KEY/CODEX_API_KEY; Gemini: GEMINI_API_KEY (auth.mdx:14-40).
• Gap 1 (persona-defining): OAuth subscription billing (Claude Max/Teams) not supported (auth.mdx:206-210).
• Gap 2: No worked example/screenshot for creating an ANTHROPIC_API_KEY — Claude gets a bare link while Copilot gets a pre-filled PAT page (auth.mdx:192-200 vs 133-146).
• Gap 3: WIF federation-rule setup lives entirely in the external Anthropic Console, only linked (auth.mdx:221-222).
• Gap 4: No Claude-specific troubleshooting section equivalent to Copilot's license/GHES notes (auth.mdx:366-372).

Recommended Actions

Priority 1 — In the Quick Start Claude tab, add one sentence: "gh-aw bills Claude via an Anthropic Console API key, not your Claude Code / Max subscription", and link the keyless WIF option (quick-start.mdx:105-107, auth.mdx:214-278).

Priority 2 — Surface the Copilot default in prerequisites and lead the first add example with --engine claude; badge Copilot-only features in the engine table (quick-start.mdx:30,75, engines.md:40-43).

Priority 3 — Add a Claude troubleshooting block + document the default Claude model; give crush/custom a smoke test or mark them experimental (architecture.mdx:279, cli.md:260).

References:

• §29831587397

Generated by 📝 Claude Code User Documentation Review · age00 424.4 AIC · ⌖ 35.6 AIC · ⊞ 5.1K · ◷

• expires on Jul 22, 2026, 5:03 AM UTC-08:00