[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-05-31

[github-actions[bot]]

Executive Summary

A developer who uses Claude Code and avoids GitHub Copilot can adopt gh-aw: Claude is a supported, first-class engine with documented auth (ANTHROPIC_API_KEY), 52 example workflows, and full CLI coverage (--engine claude). No hard blockers. But every default path frames Copilot as primary — the compiler default engine is Copilot, the Quick Start sets up the Copilot token first, gh aw init provisions Copilot artifacts unless told otherwise, and engine tables list Copilot first with "(default)". A Claude-only user succeeds but must opt out of Copilot at four steps — and one (the sample's implicit default) is a documented first-run failure (#32423).

Key finding: a defaults & framing problem, not a capability one. The fix is mostly editorial.

Persona Context

• GitHub ✅ · Claude Code ✅ · GitHub Copilot ❌ · Copilot CLI ❌

---

🚫 Critical Blockers (cannot proceed)

None. A Claude user has a complete documented path: pick Claude in gh aw add-wizard, set ANTHROPIC_API_KEY, set engine: claude. This is the review's most important conclusion.

---

⚠️ Major Obstacles (significant friction)

1. Default engine is Copilot — silent for Claude-only users

pkg/constants/engine_constants.go:34 → DefaultEngine = CopilotEngine; engines.md:24: "Copilot CLI is the default — engine: can be omitted." A workflow with no engine: field compiles to Copilot. A Claude user copying any of the 29 no-engine examples gets a Copilot run that fails without COPILOT_GITHUB_TOKEN. Docs never state Claude users must add engine: claude to every workflow.

Fix: callout in how-they-work.mdx:26 + Quick Start: "No engine: → Copilot. Claude users must set engine: claude."

2. Quick Start leads with Copilot; sample defaults to Copilot (known issue #32423)

quick-start.mdx:78-88: the COPILOT_GITHUB_TOKEN note (3 sub-steps, PAT link) precedes the shorter ANTHROPIC_API_KEY note. The sample (githubnext/agentics/daily-repo-status) carries no engine: claude, so skipping the wizard's engine prompt yields a Copilot run. Already flagged in README.md:237: "Quick Start sample workflow defaults to Copilot — Claude-only users will fail their first run (#32423) — closed 2026-05-15, no confirmed PR linkage." Closed without a confirmed fix, and the quick-start still leads with Copilot — the issue appears to persist.

Fix: add a "Using Claude?" branch showing engine: claude before the first run.

3. `gh aw init` provisions Copilot artifacts by default

cli.md:135: gh aw init creates the dispatcher skill + custom agent; "Use --engine to select a non-Copilot engine and skip Copilot-specific artifacts." cli.md:139: gh aw init --engine claude. creating-workflows.mdx:102-104 frames init as authoring "using the Copilot coding agent" with no Claude equivalent. Bare gh aw init gives Claude users Copilot scaffolding they can't use.

Fix: document gh aw init --engine claude as first-class; clarify which artifacts are Copilot-only.

4. Example parity: Copilot outnumbers Claude ~2:1

.github/workflows/*.md: Copilot 110, Claude 52, Codex 10, Gemini 0, plus 29 no-engine (→ Copilot). Most examples a Claude user finds are Copilot-flavored, and engine-specific features (max-turns Claude-only, max-continuations Copilot-only — engines.md:34-46) mean copying a Copilot example isn't always a clean swap.

Fix: add engine: claude to curated flagship examples; tag examples by engine.

---

💡 Minor Confusion (paper cuts)

1. No "Why Claude instead of Copilot?" guidance

engines.md has a feature matrix but no decision guidance on cost, reasoning depth, context, or when Claude's max-turns is preferable. A Claude user gets no affirmation they're on a good path.

2. `CLAUDE_CODE_OAUTH_TOKEN` limitation is under-signaled

Only ANTHROPIC_API_KEY works — provider OAuth / CLAUDE_CODE_OAUTH_TOKEN is unsupported. This lives in faq.md:337-339 and auth.mdx:121-123, not the Quick Start auth step where Claude users (who have an OAuth token) would hit it. Most likely "I have Claude, why won't it auth?" trap.

3. `tools.md` Copilot mentions / no `copilot` tool clarity

tools.md documents tools as engine-agnostic; only engine notes are web-search disabled on Codex (tools.md:67) and timeout defaults Claude 60s / Codex 120s (tools.md:157). No copilot tool exists, but "Copilot" appears in cli.md:185 (importing the Copilot automation API JSON), readable as a dependency at a glance. A one-line "tool catalog is engine-agnostic" note would help.

4. Copilot-first ordering throughout reference docs

Engines table (engines.md:16), feature matrix (engines.md:34), config examples, and BYOK section all list Copilot first with dedicated subsections; Claude has no equivalent advanced-config subsection. Reads as "Copilot is the real product, others are alternatives."

---

Engine Comparison

Engine	Setup	Examples	Auth	Score /5
Copilot	First-class, default, init artifacts	110 (+29 implicit)	Detailed (PAT, license, GHES)	5
Claude	Documented, secondary framing	52	Documented; OAuth caveat buried	4
Codex	Documented	10	Documented (OPENAI/CODEX, Azure)	3
Gemini	Listed, minimal	0	Documented (GEMINI_API_KEY)	2
Custom (crush/opencode/pi)	Matrix only	0	Sparse	1

Claude loses points only on framing/ordering and the buried OAuth caveat — its mechanics are complete.

Tool Availability

Tools are overwhelmingly engine-agnostic: edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy, mcp-servers, startup-timeout (tools.md:20-211). Engine coupling is limited to web-search (disabled by default on Codex only, tools.md:67) and tools.timeout defaults (Claude 60s / Codex 120s, tools.md:157). No copilot-named tool exists and no Claude-only/Copilot-only tools — playwright, github, agentic-workflows are all agnostic.

Authentication Gaps

Engine	Secret	Source
Copilot	COPILOT_GITHUB_TOKEN (PAT, Copilot Requests: Read)	settings/personal-access-tokens
Claude	ANTHROPIC_API_KEY	console.anthropic.com/settings/keys
Codex	OPENAI_API_KEY / CODEX_API_KEY	platform.openai.com/api-keys
Gemini	GEMINI_API_KEY	aistudio.google.com/api-keys

Gaps for Claude users: (1) CLAUDE_CODE_OAUTH_TOKEN unsupported but buried (faq.md:337-339, auth.mdx:121-123); (2) Copilot troubleshooting (license, GHES, enterprise) far more detailed than Claude's (auth.mdx:189-215); (3) no Anthropic-key walkthrough matching the Copilot PAT depth.

Example Parity

copilot 110 · claude 52 · codex 10 · gemini 0 · no-engine 29 (→ Copilot). Claude has solid absolute coverage but ~2:1 less than Copilot, and "neutral" examples lean Copilot by default.

---

Recommended Actions

Priority 1 (fixes a real first-run failure):

• Resolve [deep-report] Quick Start sample workflow defaults to Copilot — Claude-only users will fail their first run #32423: set engine: claude in the Quick Start sample path / add a "Using Claude?" branch before first run.
• Surface "no engine: → Copilot default; Claude users must set engine: claude" in Quick Start + how-they-work.mdx.
• Move the CLAUDE_CODE_OAUTH_TOKEN-unsupported caveat into the Quick Start auth step.

Priority 2 (parity & confidence):

• Document gh aw init --engine claude as a first-class step.
• Add a "Choosing an engine" section highlighting Claude strengths (max-turns, reasoning/context).
• Tag/curate engine: claude flagship examples.

Priority 3 (polish):

• Give Claude an advanced-config subsection in engines.md matching Copilot's BYOK section.
• One-line "tool catalog is engine-agnostic" note in tools.md.

Conclusion

Can Claude Code users adopt gh-aw? Yes — with deliberate opt-in at every default. Capability is fully there (auth, 52 examples, agnostic tools, full CLI flags); friction is entirely Copilot-primary defaults and framing. Zero hard blockers, but a hurried Claude-only user will likely hit the Copilot-default trap on first run (#32423).

Overall adoption score: 6/10 — fully feasible, well-supported underneath, held back by Copilot-primary defaults and one persistent first-run pitfall. Closing Priority 1 would lift this to ~8/10 at near-zero engineering cost.

_{Note: the four .claude/agents/ definitions reference setup/quick-start.md, but the file is quick-start.mdx — the .md path won't resolve.}

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

• expires on Jun 1, 2026, 1:00 PM UTC