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

[github-actions[bot]]

Executive Summary

A developer who uses Claude Code and deliberately avoids GitHub Copilot can adopt gh-aw — Claude is a first-class engine (engine: claude), ANTHROPIC_API_KEY setup is documented in two places, every documented tools: entry is engine-agnostic, and gh aw init --engine claude skips all Copilot scaffolding. There are no Critical blockers. The friction is structural: GitHub Copilot is the documented default engine, and all 7 example workflows in docs/.../examples/ set no engine — so a Claude user who copies an example silently runs on Copilot and is asked for COPILOT_GITHUB_TOKEN they neither have nor want.

Persona Context

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

Severity Findings

🚫 Critical Blockers (none found)

No documentation gap fully prevents a Claude Code user from starting. Claude is supported end-to-end:

• Engine selectable: engine: claude — quick-start.mdx:131
• API key acquisition documented: quick-start.mdx:84-87 and reference/auth.mdx:103-125 (console URL at auth.mdx:109)
• Copilot-free init: gh aw init --engine claude — setup/cli.md:140

⚠️ Major Obstacles (significant friction)

M1 — Copilot is the default engine; a Claude user must opt out everywhere.

"Workflows support GitHub Copilot (default), Claude by Anthropic, Codex, and Gemini by Google." — introduction/how-they-work.mdx:26

Verified in source: pkg/constants/engine_constants.go:34 (DefaultEngine = CopilotEngine). Any workflow that omits engine: runs on Copilot. Fix: state the default consequence next to every "engine optional" mention, and add a one-line "Using Claude? add engine: claude" callout in Quick Start Step 4 (quick-start.mdx:127-133).

M2 — Every example workflow defaults to Copilot. All 7 files under docs/src/content/docs/examples/** set no engine (the lone engine: hit in dependabot-rollout.md is a concurrency sub-block). A Claude user copying examples/maintaining-repos.md or examples/multi-repo.md will be prompted for COPILOT_GITHUB_TOKEN. Fix: add engine: claude (or an engine-agnostic note) to example frontmatter, or a banner: "examples default to Copilot — change engine: to match your account."

M3 — gh aw init produces Copilot-specific scaffolding by default.

"Use --no-skill or --no-agent to skip either artifact, or --engine to select a non-Copilot engine and skip Copilot-specific artifacts." — setup/cli.md:135

The default init writes .github/skills/agentic-workflows/SKILL.md and .github/agents/agentic-workflows.md (Copilot dispatcher artifacts). A Claude user must know to pass --engine claude up front or they get Copilot-only files. Fix: surface gh aw init --engine claude as a first-class example at the top of the init docs, not a footnote.

💡 Minor Confusion (paper cuts)

• Wizard lists Copilot first and the only "Set up the required secret" prose leads with COPILOT_GITHUB_TOKEN — quick-start.mdx:70-71. (Mitigated: there is an inline ANTHROPIC_API_KEY NOTE box at quick-start.mdx:84-87.)
• No "why Claude vs Copilot" / engine-capability comparison for a reader choosing an engine. The feature differences exist (max-turns is Claude-only, max-continuations is Copilot-only — reference/engines.md:37,41) but aren't framed as a decision aid.
• Example parity gap (Claude lags Copilot). Copilot test fixtures cover ~25 safe-outputs that have no Claude counterpart (project boards, review-thread resolve/submit, dispatch-workflow, comment-memory, etc.). This is fixtures, not a hard limitation, but a Claude user has fewer copy-paste references for advanced features.
• custom engine is undocumented as an engine. There is no engine: custom value anywhere in docs/ — the substitute is engine.command / engine.harness / custom endpoints (engines.md:130-217). Worth an explicit "there is no custom engine; here's how to bring your own" note.

Engine Comparison

Engine	Setup docs	Examples	Auth	Score /5
Copilot	Wizard + inline NOTE (quick-start.mdx:78-81); default	~269 occ. / broadest	Fiddly: fine-grained PAT, user-not-org, Copilot license (auth.mdx:76-99)	4
Claude	--engine claude documented (cli.md:140); inline NOTE (quick-start.mdx:84-87)	~103 occ. / solid core, lacks advanced	Simplest: one API key, console URL given (auth.mdx:103-125)	4
Codex	No inline NOTE box in quick-start; relies on auth.mdx link	~35 occ. / thin	OPENAI_API_KEY or CODEX_API_KEY (auth.mdx:129-167)	3
Custom	Not a real engine; engine.command/harness only (engines.md:130-217)	0	User-named secret, no canonical name	2

(occurrence = repo-wide engine: frontmatter field count, includes docs/specs; treat as relative volume not a workflow census.)

Tool Availability

tool-engine-classifier found every documented tools: entry is engine-agnostic — 0 copilot-only, 0 claude-only, 0 codex-only.

Tool	Class	Ref
github, bash, edit, web-fetch, playwright, cache-memory, repo-memory, mcp-servers	engine-agnostic	reference/tools.md:20-210
web-search	engine-agnostic (Codex native opt-in; others via MCP)	tools.md:61-67, engines.md:40
agentic-workflows	engine-agnostic (gated on actions: read, not engine)	tools.md:116-127

Note: there is no copilot tool — Copilot-specific knobs (engine.agent, engine.harness, max-continuations) live under engine:, not tools:. So a Claude user loses no tooling.

Authentication Gaps

From auth-doc-extractor (reference/auth.mdx):

Engine	Secret	Acquisition documented?
Copilot	COPILOT_GITHUB_TOKEN	✅ auth.mdx:76-99
Claude	ANTHROPIC_API_KEY	✅ auth.mdx:103-125 (+ quick-start.mdx:84-87)
Codex	OPENAI_API_KEY / CODEX_API_KEY	✅ auth.mdx:129-167

• Good for Claude users: the Anthropic key path is the simplest of all engines and is documented.
• Explicit warning worth surfacing: CLAUDE_CODE_OAUTH_TOKEN is not supported and silently ignored — only ANTHROPIC_API_KEY works (auth.mdx:121-123). A Claude Code user who expects to reuse their Claude subscription OAuth token will be confused; this is in auth.mdx but not in Quick Start.
• Gap: no canonical secret guidance for the "custom" path.

Example Parity

engine-example-counter: Claude has broad coverage of core safe-outputs (create-issue, create-pull-request, add-comment/labels, mcp, github-remote-mcp, noop) across all engines, but Copilot-only fixtures exist for ~25 newer features (projects, review-thread resolve/submit, dispatch-workflow, comment-memory). Claude sample workflows: .github/workflows/scout.md, deep-report.md, smoke-claude.md.

Recommended Actions

Priority 1 (close the silent-Copilot trap):

1. Add engine: claude (or an engine note) to the 7 docs/.../examples/** workflows, or a prominent "examples default to Copilot" banner.
2. Add a Quick Start callout: "Not a Copilot user? Choose Claude at the engine step and set ANTHROPIC_API_KEY."

Priority 2 (reduce opt-out friction):
3. Promote gh aw init --engine claude to a top-level example in setup/cli.md.
4. Surface the CLAUDE_CODE_OAUTH_TOKEN-unsupported warning in Quick Start, not only auth.mdx.

Priority 3 (parity & guidance):
5. Add an engine-capability comparison ("why Claude vs Copilot", max-turns vs max-continuations).
6. Add Claude examples for advanced safe-outputs to match Copilot fixture coverage.
7. Document that there is no custom engine; point to engine.command/engine.harness.

Conclusion

Can Claude Code users adopt gh-aw? — Yes. Claude is genuinely first-class: documented auth, engine-agnostic tools, and a clean Copilot-free init path. The problems are defaults and discoverability, not capability — the biggest risk is a Claude user copying an engine-less example and being unexpectedly funneled into Copilot.

Overall adoptability score: 7.5 / 10 — fully usable today, held back by Copilot-default framing and example workflows that don't declare an engine.

References:

• §27062726552

Generated by 📝 Claude Code User Documentation Review · 359.5 AIC · ⌖ 14.1 AIC · ◷

• expires on Jun 7, 2026, 12:58 PM UTC