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

[github-actions[bot]]

Executive Summary

Reviewed gh-aw docs from the perspective of a Claude Code user who does not use GitHub Copilot. No critical blockers — Claude is a fully documented, first-class engine with its own auth flow and near-parity example coverage (43 workflows versus 35 for Copilot in this scan). The recurring friction is that Copilot is the implicit default everywhere (silent fallback when engine: is omitted, gh aw init artifacts assume Copilot unless flagged), and Claude subscription users (Pro/Max/Teams) have no OAuth/token-reuse path — only a separately-billed ANTHROPIC_API_KEY works. This matches the stable pattern observed across 33 prior daily reviews (score 7.5/10, 0 critical, same 3 core gaps).

Severity Findings (click to expand)

Critical Blockers: None identified.

Major Obstacles

1. No OAuth/subscription path for Claude. CLAUDE_CODE_OAUTH_TOKEN is explicitly unsupported and silently ignored; only ANTHROPIC_API_KEY works, unlike the zero-secret copilot-requests: write org-billing shortcut Copilot offers. This is the single most persona-relevant gap and has persisted unchanged since the first tracked review. — quick-start.mdx:147-148
2. gh aw init defaults to Copilot-specific artifacts (dispatcher skill + custom agent file) unless --engine claude is passed; this requirement is not surfaced in the Prerequisites section, only in the CLI reference. — cli.md:147-152
3. Silent Copilot fallback. If engine: is removed from workflow frontmatter, the runtime defaults to Copilot, not whatever engine was previously selected — a trap for Claude users who edit frontmatter by hand. — quick-start.mdx:116, how-they-work.mdx:26
4. No dedicated Claude smoke-test workflow. Copilot has an ARM64 smoke variant and Codex has smoke-codex.md; no equivalent smoke-claude.md was found in this scan, suggesting a testing-parity gap. — sample files: smoke-copilot-arm.md, smoke-codex.md vs none for Claude

Minor Confusion

1. Copilot-first ordering throughout docs ("Workflows support GitHub Copilot (default), Claude by Anthropic, Codex...") with no why-Claude-vs-Copilot guidance. — how-they-work.mdx:26
2. "Keyless alternatives" for Claude auth are mentioned but not documented inline — reader must follow an external link. — quick-start.mdx:147
3. Per-engine web-search default behavior is only spelled out for Codex (disabled by default); Claude/Gemini/Copilot behavior is left ambiguous. — tools.md:67
4. custom engine has zero standalone workflow examples despite being a valid schema option. — engine scan: custom: 0
5. No documented way to validate ANTHROPIC_API_KEY (or any engine secret) before running a workflow; misconfiguration is only discovered at runtime. — quick-start.mdx:122

Engine and Tool Matrix

Engine	Setup	Examples (this scan)	Auth	Score
Copilot	Default; gh aw init auto-creates Copilot skill+agent artifacts unless overridden — cli.md:147-152	35 workflows; has ARM64 smoke variant	COPILOT_GITHUB_TOKEN PAT or org copilot-requests: write — quick-start.mdx:133-140	9/10
Claude	Must explicitly pass --engine claude / set engine: claude, else silent Copilot default — quick-start.mdx:116	43 workflows (leads count in this scan); no dedicated smoke-test file found	ANTHROPIC_API_KEY only; CLAUDE_CODE_OAUTH_TOKEN explicitly unsupported/ignored — quick-start.mdx:147-148	7/10
Codex	Same explicit-engine requirement as Claude	8 workflows (under-represented); has smoke-codex.md	OPENAI_API_KEY or CODEX_API_KEY alias (precedence undocumented) — quick-start.mdx:150-156	7/10
Custom	Documented in schema; no wizard/init flow highlighted	0 standalone examples	No dedicated auth section	4/10

Tool classification: 11 tools scanned, nearly all engine-agnostic (github, bash, web-fetch, playwright, cache-memory, repo-memory, qmd, agentic-workflows, cli-proxy). The one ambiguous case is web-search, whose default-off behavior is documented only for Codex — tools.md:55-67. Parity observation: a claude-code-user-docs-review.md workflow exists targeting Claude users specifically, with no Copilot/Codex equivalent review workflow.

Auth Gaps

Engine	Secret	Notes
Copilot	COPILOT_GITHUB_TOKEN (or org copilot-requests: write)	Two paths shown but trade-offs between them are not explained — quick-start.mdx:133-140
Claude	ANTHROPIC_API_KEY	CLAUDE_CODE_OAUTH_TOKEN explicitly rejected; keyless alternatives referenced but not shown inline — quick-start.mdx:141-149
Codex	OPENAI_API_KEY (or CODEX_API_KEY)	Alias precedence only mentioned in passing — quick-start.mdx:150-156
Gemini	GEMINI_API_KEY	— quick-start.mdx:157-162

GitHub Enterprise auth setup lives only in cli.md:80-122, not linked from quick-start. No documented step verifies any engine API key before first workflow run.

Recommended Actions

Priority 1

• Elevate the CLAUDE_CODE_OAUTH_TOKEN unsupported-caveat and its keyless-alternative workaround into the quick-start Claude auth tab itself (quick-start.mdx:141-149), not just a trailing note.
• Surface --engine claude in the Prerequisites step, not only in cli.md:147-152, so Claude users do not get Copilot artifacts by accident.

Priority 2

• Add a smoke-claude.md test workflow to close the smoke-coverage gap versus Copilot/Codex.
• Document the "keyless alternatives" for Claude inline in quick-start instead of only linking out.

Priority 3

• Clarify per-engine web-search default behavior for Claude/Gemini/Copilot, not just Codex (tools.md:55-67).
• Add at least one standalone custom engine example workflow.

Trend note: Consistent with 33 prior daily reviews — score stable at 7.5/10, 0 critical blockers, same 3 core gaps (OAuth/PAT-free path, init-default-Copilot, silent-default-fallback) unresolved since the first tracked run.

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

• expires on Aug 2, 2026, 4:50 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-02T12:50:15.343Z.

Closed by Workflow