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

[github-actions[bot]]

Executive Summary

A Claude Code user can onboard to gh-aw without Copilot — claude is a documented, first-class engine with its own auth path (ANTHROPIC_API_KEY or Anthropic WIF). No critical blockers found. However, setup depth is uneven: Copilot gets two fully inline auth paths and an auto-scaffolded agent/MCP config from gh aw init, while Claude users hit a one-line WIF mention, a "write your own subagent file" instruction with no template, and a deferral to an external setup page. Example coverage mirrors this: Claude appears in 62 of .github/workflows/*.md declarations vs Copilot's 130 (~2.1x).

Severity Findings

Critical Blockers (0), Major Obstacles (5), Minor Confusion (4)

Critical Blockers: None. Claude auth, frontmatter (engine: claude), and secret setup are all documented in the core six files.

Major Obstacles

1. gh aw init auto-scaffolds Copilot-only artifacts (.github/agents/agentic-workflows.md, MCP wiring); for Claude it says only "author an agent file in your own agent's format" with no template (cli.md:153, cli.md:159, cli.md:179-181).
2. CLAUDE_CODE_OAUTH_TOKEN (the token from claude login) is explicitly rejected, forcing a separate Anthropic Console API-key/billing account even for existing Claude Code subscribers (quick-start.mdx:151, cli.md:287).
3. Anthropic WIF (keyless auth) is one sentence pointing at "a federation rule in your Anthropic workspace," vs Copilot's two fully inlined auth paths (org billing vs fine-grained PAT) (quick-start.mdx:149 vs quick-start.mdx:133-141).
4. Full Claude engine setup is deferred entirely to /gh-aw/engines/claude/, a page outside the six core onboarding docs (quick-start.mdx:153).
5. Example parity gap: Claude engine declarations (62) trail Copilot (130) by ~2.1x across .github/workflows/*.md, so fewer copy-paste starting points exist for Claude users.

Minor Confusion

1. quick-start.mdx:51 says the guide "requires only the GitHub CLI," directly contradicted by the AI-account prerequisite at quick-start.mdx:70.
2. The architecture diagram's generic agent-CLI node is labeled COPILOT, leaving it unclear whether the diagram applies to all engines (architecture.mdx:204, architecture.mdx:232).
3. The add-wizard's default engine selection for its sample workflow is never stated (quick-start.mdx:120-124).
4. The Pi engine's copilot/ model prefix silently requires Copilot auth — a hidden dependency a Claude-only user could trip over (quick-start.mdx:173).

Engine & Tool Matrix

Engine	Setup	Examples	Auth	Score
Copilot	Default; 2 inline auth paths; init auto-scaffolds agent+MCP (cli.md:153)	130	copilot-requests: write (org billing) or COPILOT_GITHUB_TOKEN PAT (quick-start.mdx:133-141)	9/10
Claude	Auth steps present but WIF is a one-liner; init gives no subagent template (cli.md:180)	62	ANTHROPIC_API_KEY or WIF; CLAUDE_CODE_OAUTH_TOKEN rejected (quick-start.mdx:145-151)	6/10
Codex	Steps inline, symmetrical with Copilot's key flow	77	CODEX_API_KEY (precedence) or OPENAI_API_KEY (quick-start.mdx:157-161)	7/10
Custom	No init path, no secrets table, no examples	0	Not documented	2/10

Tool classification (tools.md, 21 entries across 16 classes): only web-fetch/web-search explicitly document per-engine behavior differences (Copilot rejects at compile, Claude is opt-in, Gemini/Pi no-op). The remaining 19 entries list engine_scope: not stated, so a Claude user has no way to tell from tools.md alone which of the other tools behave differently under Claude vs Copilot — this is the matrix's biggest documentation gap, not engine-specific favoritism.

Parity observation from the workflow scan: Codex (77) actually beats Claude (62) in example count, making Claude the third-most-represented engine among examples, not the second — worth correcting any assumption that Claude is the "main alternative" to Copilot.

Auth Gaps

• quick-start.mdx:151 rejects claude login tokens but never states whether a Claude Pro/Max subscription covers API billing — implied only, not confirmed.
• WIF steps for both Claude (quick-start.mdx:149) and Gemini (quick-start.mdx:169) name the mechanism (federation rule / workload identity pool) without showing the steps, unlike Copilot's and Codex's fully inline flows.
• No file in the six-doc set states what GitHub token/permissions a claude-engine workflow uses for MCP calls.
• cli.md:207 describes the Claude API-key upload via add-wizard only for the pull-request path; the direct-push path is unspecified.
• quick-start.mdx:146 links to the Anthropic Console with no guidance on key scope or workspace selection.

Recommended Actions

Priority 1

• Add a concrete gh aw init --engine claude example showing the generated subagent file and an MCP host-config snippet (cli.md:179-181).

Priority 2

• Expand Anthropic WIF into an inline step-by-step (mirroring Copilot's two-path treatment) instead of one sentence (quick-start.mdx:149).
• Pull the Claude-specific quick-start content (currently at /gh-aw/engines/claude/) into the core quick-start page, or add a prominent inline link at quick-start.mdx:153.

Priority 3

• Fix the quick-start.mdx:51 / :70 prerequisite contradiction.
• Relabel the architecture diagram's COPILOT node to indicate it's representative of any engine, or add a note (architecture.mdx:204).
• Fill in engine_scope for the 19 "not stated" tool entries in tools.md, or add a short note that behavior is engine-uniform unless called out.

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

• expires on Oct 19, 2026, 4:42 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 #70257.