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

[github-actions[bot]]

Executive Summary

A Claude Code user can complete onboarding end-to-end (install → gh aw init --engine claude → author → engine: claude → auth → compile → run) with no hard blocker — all steps are documented in docs/src/content/docs/engines/claude.md:108-132 and docs/src/content/docs/reference/auth.mdx:201-291. The friction is structural: tooling and examples default to Copilot, and the one credential an existing Claude Code subscriber already has (CLAUDE_CODE_OAUTH_TOKEN) is explicitly rejected, forcing a separate Anthropic Console API-key account. Key finding: gh aw init still auto-scaffolds Copilot-only artifacts (.github/mcp.json, copilot-setup-steps.yml, custom agent file) unless --engine claude is passed explicitly — this default has persisted across the full review history.

Severity Findings

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

Critical Blockers: None found. Every required step has explicit Claude-specific documentation.

Major Obstacles

1. gh aw init defaults to Copilot-specific scaffolding (.github/mcp.json, copilot-setup-steps.yml, custom agent file) unless --engine claude is passed — docs/src/content/docs/setup/cli.md:176.
2. CLAUDE_CODE_OAUTH_TOKEN (the credential from claude login, which every Claude Code subscriber already has) is explicitly not supported — forces a new Anthropic Console API-key/billing setup even for existing subscribers — docs/src/content/docs/reference/auth.mdx:201-223, docs/src/content/docs/engines/claude.md:16-22.
3. One of three documented workflow-creation methods — the GitHub web "Agents" tab — is explicitly gated on Copilot access, leaving Claude-only users 2 of 3 paths — docs/src/content/docs/setup/creating-workflows.mdx:19-21.
4. Troubleshooting's "Engine-Specific Issues" section contains only Copilot sub-sections (license/GHES); Claude gets just two generic timeout/max-turns table rows, no dedicated entries — docs/src/content/docs/troubleshooting/common-issues.md:225,341-342,353.
5. Example parity gap: full worked-example ratio is Copilot 4 : Claude 2 : Codex 2 : Custom 0, and raw mention count is 92:20:9:0. 11 of 13 gallery and 16 of 18 pattern examples omit engine: entirely, implicitly defaulting every copy-pasted example to Copilot — a Claude user must manually edit engine: and swap the auth secret on nearly every copied sample.

Minor Confusion

1. The Serena MCP "Quick Start" example defaults to engine: copilot even though Serena itself is engine-agnostic — docs/src/content/docs/reference/serena.md:20.
2. The ARC Docker-in-Docker runner guide is titled/framed specifically around "GitHub Copilot coding agent," though a caveat note says the topology applies generally — docs/src/content/docs/reference/arc-dind-copilot-agent.md:2.
3. .github/agents/ custom agent files are natively structured config only for Copilot; Claude/Codex receive the same file as plain prompt text, which isn't flagged prominently where the feature is introduced — docs/src/content/docs/reference/copilot-custom-agents.md:8.
4. No dedicated "custom engine" doc page exists; it's a 4-line subsection inside reference/engines.md with a frontmatter snippet but zero full runnable example — docs/src/content/docs/reference/engines.md:213-230.

Engine & Tool Matrix

Engine	Setup	Full Examples / Mentions	Auth	Score
Copilot	Default; auto-scaffolded by gh aw init (cli.md:176)	4 / 92	copilot-requests:write or COPILOT_GITHUB_TOKEN, PAT walkthrough + troubleshooting (auth.mdx:106-165)	5/5
Claude	Explicit --engine claude; dedicated guided-authoring flow (claude.md:108-132)	2 / 20	ANTHROPIC_API_KEY + Anthropic WIF; CLAUDE_CODE_OAUTH_TOKEN explicitly rejected (auth.mdx:201-291)	4/5
Codex	Explicit --engine codex; documented similarly to Claude	2 / 9	OPENAI_API_KEY/CODEX_API_KEY + Azure Entra OIDC (auth.mdx:295-383)	3.5/5
Custom	engine.id pattern only; no gh aw init scaffolding; 8 "unsupported" sample definitions (engines.md:105-120)	0 / 0	Inherits underlying engine's auth; no dedicated section	2/5

Parity observations: Each of Copilot/Claude/Codex has exactly one dedicated docs/src/content/docs/engines/<name>.md page with a near-identical "scheduled repository report" worked example — structurally fair, but Copilot alone gets 2 additional full examples in patterns/. No custom-engine doc file exists at all; the only content is an unsupported-samples table.

Auth Gaps

• Copilot (auth.mdx:23-27, 106-165): most complete — org billing path, PAT creation walkthrough, custom endpoint, dedicated troubleshooting subsection.
• Claude (auth.mdx:29-32, 201-223, 227-291; claude.md:16-22): structurally comparable to Copilot (API key + WIF, field table, emitted env vars), but is the only engine whose docs must call out an explicit anti-pattern — the natural Claude Code login credential is rejected, with no softer fallback offered.
• Codex (auth.mdx:34-37, 295-383): complete, same structure as Claude.
• Gemini (auth.mdx:39-42, 387-469): complete, same structure.

Recommended Actions

Priority 1

• Make gh aw init prompt for engine choice (or default to engine-neutral scaffolding) instead of silently writing Copilot-only artifacts when --engine is omitted (cli.md:176).
• Add a visible callout near the top of quick-start.mdx and claude.md warning that claude login/CLAUDE_CODE_OAUTH_TOKEN won't work, before a user wastes a debugging cycle (auth.mdx:201-223).

Priority 2

• Add engine: claude (or an explicit "swap this line" callout) to the gallery/pattern examples that currently omit engine: and default to Copilot.
• Add Claude/Codex-specific subsections to the troubleshooting "Engine-Specific Issues" section (common-issues.md:225).
• Offer a non-Copilot equivalent, or clearly scope the limitation, for the GitHub web "Agents" tab creation method (creating-workflows.mdx:19-21).

Priority 3

• Generalize the Serena quick-start example's engine value or note it's illustrative only (serena.md:20).
• Reframe the ARC DinD guide title/intro as engine-agnostic (arc-dind-copilot-agent.md:2).
• Add one minimal full worked example for the custom/third-party engine path (engines.md:213-230).

Generated by 📝 Claude Code User Documentation Review · claude · agent · 187.9 AIC · ⌖ 0.853 AIC · ⊞ 2.6K · ◷

• expires on Oct 18, 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 #69928.