[claude-code-user-docs-review] Claude Code User Documentation Review - 2026-09-22

[github-actions[bot]]

Executive Summary

A Claude Code user (no GitHub Copilot) can fully complete gh-aw setup end-to-end — no critical blockers found, consistent with the last 14 runs. The main friction is auth-related: CLAUDE_CODE_OAUTH_TOKEN (the credential from claude login, which many Claude Code users already have) is silently ignored rather than rejected with a clear error, and quick-start's Claude section doesn't warn about it up front. A secondary, steady theme is an example/smoke-test parity gap — Claude has roughly half as many workflow examples as Copilot.

Severity Findings (Critical → Major → Minor)

Critical Blockers: none this run.

Major Obstacles:

1. CLAUDE_CODE_OAUTH_TOKEN is explicitly unsupported and silently ignored, producing an opaque Claude-CLI auth failure that never mentions the token — docs/src/content/docs/setup/cli.md:240. This gotcha is not mentioned in quick-start.mdx's Claude setup steps (quick-start.mdx:130-139), so a Claude Code CLI user who reuses their existing OAuth session hits a confusing dead end.
2. Anthropic Workload Identity Federation (WIF) — the recommended alternative to a long-lived API key — has no inline setup steps in any of the 6 reviewed docs; it's a bare hyperlink to /gh-aw/reference/auth/#anthropic-workload-identity-federation-wif — docs/src/content/docs/introduction/how-they-work.mdx:33.
3. Example/smoke-test parity gap persists: Claude engine declared in 56 workflow files vs. Copilot's 107 (~1.9x), out of 299 total .github/workflows/*.md files (Codex 75, Pi 31, custom 0). Claude Code users have roughly half the worked examples to learn from.
4. gh aw init auto-scaffolds a custom agent file (.github/agents/agentic-workflows.md) and MCP wiring only for --engine copilot; Claude/Codex users get neither and must author the equivalent by hand — docs/src/content/docs/setup/cli.md:115-140.

Minor Confusion:

1. The quick-start prerequisites list ("AI Account: GitHub Copilot, Anthropic Claude, OpenAI Codex, or Google Gemini") omits Pi even though Pi is offered later as a selectable built-in engine — quick-start.mdx:72.
2. No guidance on Claude model selection (Sonnet vs. Opus) or cost tradeoffs, unlike Pi's inline model: example — quick-start.mdx:159.
3. tools.md documents Codex's web-search-disabled-by-default behavior explicitly but leaves Claude's default web-search behavior unstated — docs/src/content/docs/reference/tools.md:126-235.

Engine & Tool Matrix

Engine	Setup	Examples	Auth	Score
Copilot	gh aw init auto-creates custom agent + MCP wiring (cli.md:115)	107	copilot-requests: write (org billing) or COPILOT_GITHUB_TOKEN PAT	9/10
Claude	Manual: create ANTHROPIC_API_KEY, gh secret set, no auto agent-file scaffold; deep-dive deferred to a separate page	56	ANTHROPIC_API_KEY or Anthropic WIF (link-only); CLAUDE_CODE_OAUTH_TOKEN silently rejected	6/10
Codex	Manual, same shape as Claude	75	OPENAI_API_KEY or CODEX_API_KEY	7/10
Custom (MCP)	mcp-servers: mechanism (process/container/HTTP/registry) — engine-agnostic	0 dedicated examples	inherits host engine's credential	5/10 (undocumented as its own path)

Engine-agnostic tools show good parity across engines: edit, github, bash, web-fetch, playwright, cache-memory/repo-memory, cli-proxy, and mcp-servers all work identically regardless of engine (tools.md:20-302). The only Copilot-exclusive artifacts are the auto-generated custom-agent file and MCP wiring (cli.md:139-140) — a documented, if manual, workaround exists for other engines ("author an agent file in your own agent's format").

Long-tail engine counts from .github/workflows/*.md (299 files, 283 declare an engine): Pi 31, Goose 3, Aider 3, OpenCode 2, others (Gemini, Kiro, Cursor, Crush, pydantic-ai, deepseek-harness) 1 each.

Auth Gaps

• Claude: ANTHROPIC_API_KEY is the documented path (quick-start.mdx:135); WIF is mentioned only as a link (how-they-work.mdx:33); CLAUDE_CODE_OAUTH_TOKEN is a known dead-end (cli.md:240) not flagged in quick-start.
• Codex: OPENAI_API_KEY/CODEX_API_KEY — documented similarly, no equivalent OAuth-token trap found.
• Copilot: two paths (org billing copilot-requests: write, or PAT via COPILOT_GITHUB_TOKEN) both documented inline in quick-start with concrete commands.
• Gemini: GEMINI_API_KEY or Google WIF — same link-only WIF treatment as Claude.
• Nothing in the 6 reviewed docs explains GITHUB_TOKEN scoping for the workflow's own GitHub operations beyond the generic gh auth login --scopes repo,workflow prerequisite (quick-start.mdx:76).

Recommended Actions

Priority 1 — Add an explicit callout in quick-start.mdx's Claude section (near line 135) warning that CLAUDE_CODE_OAUTH_TOKEN / claude login sessions are not supported and will fail silently; point directly at ANTHROPIC_API_KEY or WIF as the only supported paths.

Priority 2 — Inline a minimal Anthropic WIF walkthrough (or a short "why you might want this" + copyable steps) instead of a bare link, matching the depth already given to Copilot's two auth paths.

Priority 3 — Grow the Claude example set (currently 56 vs. Copilot's 107) — even a handful of additional smoke-test workflows would narrow the parity gap and give Claude Code users more copy-paste starting points.

---

Meta-note: this run's .claude/agents/doc-reader.md, .claude/agents/engine-example-counter.md, and .claude/skills/reporting.md are still missing the required name: frontmatter field and failed to register as usable agent/skill types (only claude, Explore, general-purpose, Plan, statusline-setup agents and no reporting skill were available this session). This is now confirmed across 8+ consecutive daily runs; Edit permission to fix the frontmatter was denied again this run. Findings above were gathered via a general-purpose fallback agent carrying the doc-reader instructions inline, plus direct grep for engine counts, and formatted by hand per reporting.md's rules. Filed separately via missing_tool.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• api.anthropic.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "api.anthropic.com"

See Network Configuration for more information.

Generated by 📝 Claude Code User Documentation Review · claude · agent · 217.9 AIC · ⌖ 5.31 AIC · ⊞ 6.5K · ◷

• expires on Sep 23, 2026, 4:47 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 #62956.