[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-06-15

[github-actions[bot]]

Executive Summary

A Claude Code user can adopt gh-aw: Claude is a first-class engine with auth instructions in the quick start, ~63 example workflows, and full tool parity. No critical blockers. The single most persona-relevant gap persists across runs: a Claude Code user holding a Claude Max/Teams subscription will reach for CLAUDE_CODE_OAUTH_TOKEN, which gh-aw silently ignores — and the only warning lives deep in the auth reference, never in the quick start. Overall score: 7.5/10 (stable).

Severity Findings (Critical → Major → Minor)

🚫 Critical Blockers

None. Claude is documented as a selectable engine with inline ANTHROPIC_API_KEY setup (quick-start.mdx:84-88) and broad example coverage. A Claude-only user can complete onboarding.

⚠️ Major Obstacles

1. CLAUDE_CODE_OAUTH_TOKEN is unsupported and silently ignored. "...not supported... If you have set CLAUDE_CODE_OAUTH_TOKEN as a repository secret, it will be ignored — configure ANTHROPIC_API_KEY instead" (reference/auth.mdx:199-201, also faq.md:368). This caveat is absent from quick-start.mdx and setup/cli.md. A Claude Code user on a Max/Teams plan (no pay-as-you-go API key) hits a dead end with no in-context signal. Fix: add a one-line NOTE beside the ANTHROPIC_API_KEY callout at quick-start.mdx:84.
2. gh aw init / add-wizard default to Copilot-specific artifacts. --engine claude "skip[s] Copilot-specific artifacts" (cli.md:135) and the wizard prompts Copilot billing/PAT by default (cli.md:164), but the quick-start steps never surface --engine claude. A Claude user running the documented happy path generates Copilot dispatcher skills/agents they don't want. Fix: show gh aw init --engine claude in quick-start.
3. Engine omitted = silent Copilot default; inline secret callouts skip Codex/Gemini. 33 example workflows declare no engine and resolve to Copilot (pkg/constants/engine_constants.go:34). Quick-start has dedicated NOTE blocks only for Copilot and Anthropic (quick-start.mdx:77-88); Codex/Gemini keys are named at :71 but get no inline setup. Fix: state the default explicitly; add Codex/Gemini callouts.

💡 Minor Confusion

• Copilot-first ordering everywhere (how-they-work.mdx:26 "GitHub Copilot (default)"; architecture.mdx:279). No "why choose Claude vs Copilot?" guidance.
• Custom engine has zero standalone examples and no dedicated quick-start auth section (its only occurrence is an imported shared/genaiscript.md fragment).

Engine & Tool Matrix

Engine	Setup in quick-start	Examples	Auth (inline callout?)	Score
Copilot	Default; init builds artifacts	~131 (+33 implicit default)	COPILOT_GITHUB_TOKEN / org billing — ✅ NOTE	9/10
Claude	--engine claude (not surfaced)	63	ANTHROPIC_API_KEY — ✅ NOTE; ❌ no OAuth-token warning	7.5/10
Codex	--engine codex	14	OPENAI_API_KEY named, ❌ no inline steps	5.5/10
Custom	Not in quick-start	0 standalone	None in quick-start	2/10

Tool parity (reference/tools.md): 14 tools, 13 engine-agnostic, 0 engine-locked, 1 unclear (web-search, lines 62-67 — Codex disables by default; some engines need a third-party MCP). Only engine-specific defaults: tools.timeout Claude 60s / Codex 120s (:157). No tool is Copilot-only — strong positive for Claude users.

Parity observation (example counter): Copilot effectively dwarfs others (~164 incl. implicit defaults) vs Claude 63 vs Codex 14 vs Custom 0. Claude reaches near-parity within the analysis/docs/review workflow families, but raw counts and the implicit-Copilot default skew first impressions toward Copilot.

Auth Gaps

Per-engine auth from quick-start.mdx

• Copilot — COPILOT_GITHUB_TOKEN; full inline steps (fine-grained PAT, Copilot Requests: Read) :79-81. Explicitly distinct from GITHUB_TOKEN :71.
• Claude — ANTHROPIC_API_KEY; inline steps :85-87. Gap: no mention that CLAUDE_CODE_OAUTH_TOKEN is ignored.
• Codex — OPENAI_API_KEY named :71 only; no inline step-by-step, deferred to /reference/auth/.
• Custom — not mentioned at all in quick-start; no secret, no steps.
• All engines defer full setup to the external /reference/auth/ page.
• (Note: actual file is quick-start.mdx, not .md.)

Recommended Actions

Priority 1 (persona-critical): Add a NOTE at quick-start.mdx:84 — "CLAUDE_CODE_OAUTH_TOKEN (Claude Max/Teams OAuth) is not supported; use ANTHROPIC_API_KEY." Surface gh aw init --engine claude in the quick-start steps.

Priority 2: State the implicit Copilot default explicitly where engine selection is introduced (how-they-work.mdx:26); add inline secret callouts for Codex (OPENAI_API_KEY) and Gemini.

Priority 3: Add a short "Choosing an engine (Copilot vs Claude vs Codex)" comparison; add at least one standalone custom-engine example and a custom-engine auth note.

References: §27553507019

Generated by 📝 Claude Code User Documentation Review · 401.2 AIC · ⌖ 12.2 AIC · ⊞ 4.9K · ◷

• expires on Jun 16, 2026, 6:44 AM UTC-08:00