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

[github-actions[bot]]

Executive Summary

Reviewing gh-aw's core docs from the perspective of a Claude Code user (no GitHub Copilot) finds zero critical blockers — a workflow can be running within minutes. But onboarding defaults, the gh aw init CLI, and auth documentation consistently steer new users toward Copilot, and Claude requires separate pay-per-token billing with no way to reuse an existing Claude Pro/Max subscription. This is run 36 of a daily-tracking series; the overall score (7.5/10) and the core gaps below have held stable across all prior runs (see cache-memory trend history).

Severity Findings

Critical (0) / Major (3) / Minor (4) — click to expand

Critical: None found. A Claude Code user can set up and run a workflow end-to-end using only public documentation.

Major:

1. No OAuth/subscription reuse for Claude — CLAUDE_CODE_OAUTH_TOKEN is explicitly unsupported and silently ignored; only a separately-billed ANTHROPIC_API_KEY works, unlike Copilot's zero-extra-account-setup path. (docs/src/content/docs/setup/quick-start.mdx:141-148)
2. gh aw init defaults to Copilot-specific artifacts (.github/agents/agentic-workflows.md custom agent, skill file) unless --engine claude is passed; this flag is documented only in the CLI reference, not surfaced in quick-start's Prerequisites or the README's own hidden agent-setup block. (docs/src/content/docs/setup/cli.md:150; README.md:13-45)
3. Omitting engine: from frontmatter silently defaults to Copilot; a Claude Code user hand-writing or copying a workflow snippet without an explicit engine: claude line is routed to a different engine with no warning. (docs/src/content/docs/introduction/how-they-work.mdx:24-37)

Minor:
4. Copilot-first ordering throughout README and quick-start prerequisites, with no why-Claude-vs-Copilot guidance for a user choosing an engine. (README.md:49,75)
5. add-wizard's Copilot PAT setup is documented in rich, step-by-step detail (prefilled token-creation URL, org-billing vs PAT choice); no equivalent depth exists for Claude/Codex/Gemini auth in the same CLI reference. (docs/src/content/docs/setup/cli.md:179)
6. web-search tool behavior per engine is ambiguous — the doc says some engines need third-party MCP servers without naming which ones, and only specifies Codex's disabled-by-default behavior explicitly. (docs/src/content/docs/reference/tools.md:65-67)
7. tools.timeout default values are documented for only 2 of 4 engines (Claude: 60s, Codex: 120s); Copilot and Gemini defaults are unstated. (docs/src/content/docs/reference/tools.md:157)

Engine & Tool Matrix

	Copilot	Claude	Codex	Custom
Setup	PAT / copilot-requests: write, detailed wizard flow (cli.md:179)	ANTHROPIC_API_KEY only, no OAuth reuse (quick-start.mdx:141-148)	OPENAI_API_KEY/CODEX_API_KEY (how-they-work.mdx:24-37)	No dedicated auth section documented
Examples in .github/workflows/*.md	136 (134 files)	67	16 (15 files)	1
Auth clarity	High (prevalidated/prefilled PAT flow)	Medium (single key, OAuth caveat present but easy to miss)	Medium	None
Default engine if omitted	Yes (implicit)	No	No	No
Score (0–10)	9	7	6.5	3

Tool classification: of the built-in tools in tools.md, none are strictly Copilot-only or Claude-only this run — core tool parity is strong. The one clearly engine-specific behavior is web-search, disabled by default only for Codex.

Auth Gaps

• Claude requires a separate ANTHROPIC_API_KEY (Anthropic Console) even for users with an existing Claude Pro/Max/Teams subscription; CLAUDE_CODE_OAUTH_TOKEN is explicitly rejected if set. (quick-start.mdx:141-148)
• No documented step validates an ANTHROPIC_API_KEY end-to-end the way Copilot's PAT is prevalidated/prefilled during add-wizard. (cli.md:179)
• gh aw init's Copilot-artifact default (custom agent + skill files) is a one-way surprise for Claude users unless they already know to pass --engine claude; this isn't mentioned in quick-start's own setup steps. (cli.md:150)

Recommended Actions

Priority 1 (blocks confident adoption):

• Surface gh aw init --engine claude directly in quick-start's own steps, not just the CLI reference, so Copilot-specific artifacts aren't created by default for non-Copilot users.

Priority 2 (reduces friction):

• Add a short "why Claude vs Copilot" note near the AI Account prerequisite, and document tools.timeout/web-search defaults for all four engines, not just two.

Priority 3 (nice-to-have):

• Give Claude/Codex/Gemini auth setup in cli.md the same step-by-step depth currently given only to Copilot's PAT wizard flow.

Generated by 📝 Claude Code User Documentation Review · agent · 145.9 AIC · ⌖ 35.9 AIC · ⊞ 5.4K · ◷

• expires on Aug 4, 2026, 5:32 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-04T13:32:16.221Z.

Closed by Workflow