[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-10-19

[github-actions[bot]]

Executive Summary

Claude Code users can get a gh-aw workflow running, but the onboarding path still defaults to Copilot at every fork in the road: the quickstart nudges new users toward Copilot first, gh aw init's scaffolding is Copilot-only, and an existing Claude Code subscription credential is explicitly rejected. Key finding: example/smoke-test parity has not closed — Claude engine declarations sit at 62 vs Copilot's 132 across .github/workflows/*.md (~2.13x), the same ~2x gap seen in every prior run.

Severity Findings (Critical / Major / Minor)

Critical Blockers

None found this run — a Claude Code user can complete setup, just with more friction than a Copilot user.

Major Obstacles

1. CLAUDE_CODE_OAUTH_TOKEN explicitly rejected. A claude login subscription token is not supported; the CLI errors on it, forcing subscribers to create a separate Anthropic Console API-key account. (quick-start.mdx:151, cli.md:287)
2. gh aw init custom-agent/MCP scaffolding is Copilot-only. --engine copilot auto-generates .github/agents/agentic-workflows.md, .github/mcp.json, and copilot-setup-steps.yml; --engine claude just skips these with no equivalent Claude template provided. (cli.md:153, cli.md:159, cli.md:174-181, cli.md:180)
3. Anthropic WIF is one line; Copilot auth gets two fully inlined paths. Copilot's PAT and copilot-requests: write permission paths are spelled out inline (quick-start.mdx:135-141); the Claude WIF path is a single sentence with no federation-rule steps. (quick-start.mdx:149)
4. Example/smoke-test parity gap persists. engine: claude appears 62 times vs engine: copilot 132 times in .github/workflows/*.md (~2.13x) — consistent with the 1.9–2.1x band observed across the last several runs.
5. Full Claude engine setup is deferred outside core onboarding. The quickstart defers detailed Claude configuration to an external /gh-aw/engines/claude/ page rather than including it inline like the other engine sections. (quick-start.mdx:153)

Minor Confusion

1. docs/src/content/docs/setup/quick-start.md does not exist; the real file is quick-start.mdx. A reviewer following the filename literally hits a 404-equivalent.
2. playwright tool's runtime classification is not stated in the tools reference, leaving its engine-compatibility ambiguous. (tools.md:134-144)
3. Web-search's per-engine behavior (disabled by default for Claude/Codex, rejected outright for Copilot, absent for Gemini/Pi) is buried in one paragraph rather than surfaced per-engine where users configure tools. (tools.md:128-132)
4. gh auth login --scopes repo,workflow is given as one generic prerequisite without noting that Copilot-specific flows may need additional scope/permission context. (quick-start.mdx:74)

Engine & Tool Matrix

Engine	Setup	Examples	Auth	Score
Copilot	Inline, two full auth paths (PAT or copilot-requests: write) + auto-scaffolded init artifacts (cli.md:153,181)	132 workflows	COPILOT_GITHUB_TOKEN or copilot-requests: write (quick-start.mdx:137-141)	9/10
Claude	Partial — deferred to external engine page, WIF under-documented (quick-start.mdx:149,153)	62 workflows	ANTHROPIC_API_KEY or WIF (no subscription-token support) (quick-start.mdx:151)	5/10
Codex	Inline, single secret	77 workflows	CODEX_API_KEY / OPENAI_API_KEY (quick-start.mdx:159-161)	7/10
Custom MCP	User-defined, documented in tools.md:280-320	0 workflows	Engine-independent	n/a

Tool classification (tools.md): 5 built-in, 2 built-in-MCP, 2 third-party remote MCP (Linear, Jira — both engine-independent), 2 engine-dependent (web-fetch/web-search), 2 experimental (drive-memory, qmd), 1 custom-MCP, 3 config modifiers. playwright and github mode remain ambiguous entries needing an explicit engine-scope column.

Parity observation: the 2.13x copilot:claude example ratio and the Major-Obstacle #2/#3 scaffolding gap are the same root cause — Copilot is still gh-aw's "paved path," and every other engine inherits leftover friction rather than a parallel first-class path.

Auth Gaps

• Claude: ANTHROPIC_API_KEY or Anthropic WIF (id-token: write, --no-secret); no subscription-token (CLAUDE_CODE_OAUTH_TOKEN) support (quick-start.mdx:145-151, cli.md:207,287). WIF federation-rule setup is link-only, not step-by-step.
• Codex: CODEX_API_KEY or OPENAI_API_KEY, CODEX_API_KEY takes precedence (quick-start.mdx:159-161).
• Copilot: PAT (COPILOT_GITHUB_TOKEN) or copilot-requests: write permission (no secret needed) — both paths fully inlined (quick-start.mdx:135-141).
• Gemini: GEMINI_API_KEY or Google WIF; pool/provider setup not given step-by-step (quick-start.mdx:165-169).

Recommended Actions

Priority 1

• Add a concrete Claude (and Codex) equivalent to the --engine copilot auto-scaffold in gh aw init, or document the manual steps to reach parity (cli.md:153-181).
• Expand the Anthropic WIF paragraph into the same two-fully-inlined-paths treatment Copilot gets (quick-start.mdx:149 vs 135-141).

Priority 2

• Pull the external /gh-aw/engines/claude/ setup content inline into quickstart, matching how Copilot's steps are inlined (quick-start.mdx:153).
• Fix the quick-start.md → quick-start.mdx filename mismatch wherever it's referenced.

Priority 3

• Add an explicit per-tool "engine scope" column to tools.md to resolve the playwright/github/web-search ambiguous entries.
• Grow the Claude example/smoke-test set toward parity with Copilot's (62 vs 132 today).

Generated by 📝 Claude Code User Documentation Review · claude · agent · 62.5 AIC · ⌖ 0.811 AIC · ⊞ 5.3K · ◷

• expires on Oct 20, 2026, 4:49 AM UTC-08:00