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

[github-actions[bot]]

Executive Summary

A developer who uses Claude Code and avoids all GitHub Copilot products can adopt gh-aw — there are no hard blockers. A complete Claude-only path exists (pick Claude in the wizard or set engine: claude, supply ANTHROPIC_API_KEY, run gh aw init --engine claude), all 15 documented tools are engine-agnostic, and 63 Claude workflow examples ship in the repo. Key finding: the single biggest friction for this persona is that CLAUDE_CODE_OAUTH_TOKEN is explicitly unsupported (auth.mdx:121-123) — Claude Code users who expect to reuse their Claude Max/Teams subscription OAuth must instead obtain a pay-as-you-go ANTHROPIC_API_KEY, and this caveat is buried in the auth reference rather than surfaced in Quick Start.

Persona Context

• GitHub ✅ — uses GitHub for version control & collaboration
• Claude Code ✅ — primary AI coding tool
• GitHub Copilot ❌ — actively avoids
• Copilot CLI ❌ — does not use

Severity Findings

No 🚫 Critical Blockers were found — a Claude Code user can complete onboarding end-to-end.

⚠️ Major Obstacles (significant friction) — 3

M1 — CLAUDE_CODE_OAUTH_TOKEN is unsupported and the caveat is not surfaced where Claude Code users will look.
docs/.../reference/auth.mdx:121-123: "CLAUDE_CODE_OAUTH_TOKEN is not supported... The only supported authentication method for the Claude engine is ANTHROPIC_API_KEY. Provider-based OAuth (Claude Teams or Claude Max subscription) is not supported... it will be ignored." A Claude Code user's mental model is "I already authenticate Claude Code with my subscription token." They will reach for CLAUDE_CODE_OAUTH_TOKEN, watch it be silently ignored, and have no signpost in Quick Start. Fix: add a one-line callout in quick-start.mdx next to the ANTHROPIC_API_KEY NOTE (quick-start.mdx:84-88): "Claude subscription / Claude Code OAuth tokens are not supported — use an API key."

M2 — Copilot is the silent default engine; gh aw init produces Copilot-specific artifacts unless --engine claude is passed.
how-they-work.mdx:26: "Workflows support GitHub Copilot (default)..." and cli.md:135 / cli.md:139: "use --engine to select a non-Copilot engine and skip Copilot-specific artifacts" / gh aw init --engine claude # Skip Copilot-specific artifacts. Quick Start never mentions gh aw init --engine claude, so a Claude user following Quick Start gets Copilot scaffolding by default. Fix: surface --engine claude in the Quick Start install/init step.

M3 — Quick Start framing is Copilot-first.
quick-start.mdx:71 lists COPILOT_GITHUB_TOKEN first in the secret step, and the dedicated setup NOTE for COPILOT_GITHUB_TOKEN (quick-start.mdx:77-82) precedes the ANTHROPIC_API_KEY NOTE (quick-start.mdx:84-88). The Copilot token also carries extra burden (a separate fine-grained PAT with Copilot Requests: Read), which a non-Copilot reader may assume is mandatory. Fix: reorder or add "pick the one matching your AI account" guidance so Copilot isn't implied as required.

💡 Minor Confusion (paper cuts) — 3

m1 — Example imbalance. Repo ships 126 Copilot vs 63 Claude workflow examples (~2:1). Plenty of Claude coverage, but Copilot-dominant sample browsing reinforces a Copilot-first impression.

m2 — No "why Claude instead of Copilot?" guidance and no engine capability/comparison matrix in the intro docs. A Claude Code user gets no explicit reassurance that Claude is a first-class, fully-capable engine.

m3 — Inline secret callouts in Quick Start exist only for Copilot and Claude. Codex (OPENAI_API_KEY) and Gemini (GEMINI_API_KEY) are link-only (quick-start.mdx:71). Minor for the Claude persona, but inconsistent.

Engine Comparison

Ratings: ⭐ scale 1–5 (Setup ease for a non-Copilot user, Example availability, Auth clarity). Data from sub-agent scans of .github/workflows/*.md, tools.md, quick-start.mdx, and auth.mdx.

Engine	Setup	Examples	Auth	Score	Notes
Copilot	⭐⭐⭐⭐	⭐⭐⭐⭐⭐ (126)	⭐⭐⭐	12/15	Default engine; needs separate fine-grained PAT (COPILOT_GITHUB_TOKEN, Copilot Requests: Read).
Claude	⭐⭐⭐⭐	⭐⭐⭐⭐⭐ (63)	⭐⭐⭐	11/15	Fully supported; ANTHROPIC_API_KEY only. Subscription/OAuth not supported. Must opt out of Copilot default.
Codex	⭐⭐⭐	⭐⭐⭐ (14)	⭐⭐⭐⭐	10/15	OPENAI_API_KEY (or CODEX_API_KEY); no inline Quick Start callout.
Custom	⭐⭐	⭐ (1)	⭐⭐	5/15	Only shared/genaiscript.md; no dedicated secret documented; auth described vaguely.

Tool Availability

Per tool-engine-classifier scan of reference/tools.md: all 15 documented tools/config entries are engine-agnostic. Zero copilot-only, claude-only, or codex-only tools.

• agentic-workflows, playwright, github, bash, edit, web-fetch, web-search, cache-memory, repo-memory, qmd, cli-proxy, mcp-servers + timeout/startup-timeout/registry → all engine-agnostic.
• There is no copilot tool — "copilot" appears only as an engine: value, never under tools:. Nothing is gated to Copilot.
• Only engine-specific material is behavioral caveats on shared tools: web-search is disabled by default on Codex (tools.md:67); timeout defaults differ (Claude 60s / Codex 120s, tools.md:157).

Verdict for the persona: tooling is fully available to Claude users. ✅

Authentication Gaps

From auth-doc-extractor (reference/auth.mdx is the authoritative source; quick-start.mdx links to it):

Engine	Secret(s)	Documented at
Copilot	COPILOT_GITHUB_TOKEN (fine-grained PAT, user account, Copilot Requests: Read)	auth.mdx:76-99; quick-start.mdx:71,77-82
Claude	ANTHROPIC_API_KEY	auth.mdx:103-125; quick-start.mdx:84-88
Codex	OPENAI_API_KEY / CODEX_API_KEY; optional AZURE_OPENAI_API_KEY	auth.mdx:135-165
Custom	none documented	auth.mdx:41 (vague)

Gaps for Claude Code users:

• 🔴 CLAUDE_CODE_OAUTH_TOKEN explicitly ignored (auth.mdx:121-123) — not mentioned in Quick Start (see M1).
• 🟡 ANTHROPIC_BASE_URL custom-endpoint path is documented (auth.mdx:119) — good for enterprise proxies.
• 🟢 ANTHROPIC_API_KEY setup is now covered inline in Quick Start (quick-start.mdx:84-88) — an improvement over the 2026-06-01 review where it was reported buried.

Example Parity

engine-example-counter over .github/workflows/*.md (string + object engine: forms merged, body snippets excluded):

Engine	Count	Sample files
copilot	126	smoke-copilot.md, craft.md, research.md, release.md
claude	63	smoke-claude.md, ci-doctor.md, audit-workflows.md, deep-report.md
codex	14	smoke-codex.md, dev.md, changeset.md, daily-fact.md
custom	1	shared/genaiscript.md
(no engine field)	32	security-review.md, issue-triage-agent.md, smoke-project.md

Parity verdict: Claude has ample, varied examples (63) covering CI, auditing, reporting, and smoke tests. No capability is Claude-exclusive or Claude-excluded. The 2:1 Copilot:Claude ratio is a perception issue, not a functional gap.

Recommended Actions

Priority 1 (address the persona's #1 wall):

1. Add a Quick Start callout next to the ANTHROPIC_API_KEY NOTE stating that CLAUDE_CODE_OAUTH_TOKEN / Claude subscription tokens are not supported and an API key from console.anthropic.com is required (targets M1).

Priority 2 (reduce Copilot-default friction):
2. Surface gh aw init --engine claude in Quick Start so non-Copilot users don't get Copilot scaffolding (M2).
3. Rebalance Quick Start step 3 / engine-selection framing so no single engine reads as required (M3).

Priority 3 (polish):
4. Add a short "Choosing an engine" / capability-parity note reassuring users Claude is first-class (m2).
5. Add inline Codex/Gemini secret callouts for consistency (m3); optionally add a Claude-first example to the guides.

Conclusion

Can Claude Code users adopt gh-aw? — Yes. There are no critical blockers: the engine, tooling, auth, and examples all fully support a Copilot-free, Claude-only workflow. The friction is framing (Copilot-as-default) and one genuine trap — subscription/OAuth tokens don't work, only ANTHROPIC_API_KEY does — that isn't surfaced where this persona will hit it.

Overall score: 7.5 / 10 (stable vs the 2026-06-01 review; the inline ANTHROPIC_API_KEY Quick Start callout is a real improvement, but the CLAUDE_CODE_OAUTH_TOKEN gap and Copilot-default framing remain).

References:

• §26954844898 (this run)
• §26761037603 (prior review, 2026-06-01)

Generated by 📝 Claude Code User Documentation Review · opus48 17.3M · ◷

• expires on Jun 5, 2026, 1:42 PM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #37113.