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

[github-actions[bot]]

Executive Summary

Claude Code users can adopt gh-aw, but the path is second-class: gh aw init only auto-scaffolds the agent file and MCP wiring for Copilot (cli.md:135-140), Claude setup gets a one-line pointer instead of a walkthrough (cli.md:139), and the documented CLAUDE_CODE_OAUTH_TOKEN gap (cli.md:240) has now been flagged unresolved for 37 consecutive daily runs since 2026-08-22. Example coverage confirms the skew: 58 Claude workflow declarations vs. 111 for Copilot, 9 vs. 13 smoke-test variants.

Severity Findings

Critical / Major / Minor findings (click to expand)

Critical Blockers: None currently. The OAuth secret issue was downgraded from Critical to Major on 2026-09-08 once prose documentation of the limitation was added.

Major Obstacles:

1. CLAUDE_CODE_OAUTH_TOKEN silently ignored — a Claude Code user's local claude login credential cannot be reused in Actions; the run instead fails with a generic Claude CLI auth error that never names the real cause (cli.md:240). Unresolved 21 consecutive runs at Major severity (37 total since first flagged 2026-08-22). Not cross-referenced from quick-start.mdx Claude tab (~145-153) or how-they-work.mdx:33.
2. gh aw init scaffolding parity gap — Copilot gets an automated custom-agent file (.github/agents/agentic-workflows.md) and MCP wiring (.github/mcp.json, copilot-setup-steps.yml); Claude/Codex users are told only to "author an agent file in your own agent's format" with no worked example (cli.md:135-140).
3. Example/smoke-test parity gap — Claude has 58 workflow declarations vs. Copilot's 111 (~1.9x) and 9 vs. 13 smoke-test variants, so Claude users have fewer reference implementations to copy from.
4. Non-Copilot init guidance is a pointer, not a procedure — MCP wiring for Claude requires registering gh aw mcp-server in "your own MCP host configuration," deferring to a separate reference page instead of a concrete Claude Code example (cli.md:140).

Minor Confusion:

1. Web-search and tool-timeout defaults are documented only for Copilot/Claude/Codex, leaving Gemini/Pi undefined (tools.md:126-128, tools.md:235).
2. Pi is offered as an engine choice (quick-start.mdx:125) but omitted from the "AI Account" prerequisite list a few lines earlier (quick-start.mdx:72).
3. Pi's auth section lists three possible credential types with no stated selection rule; the actual rule (model: provider prefix) only appears later and isn't cross-linked (how-they-work.mdx:36 vs. quick-start.mdx:173).
4. No doc clarifies that the Actions ANTHROPIC_API_KEY used by the CI agent is unrelated to a user's local Claude Code CLI session — a natural point of confusion for exactly this persona (cli.md:240, how-they-work.mdx:33).

Engine & Tool Matrix

Engine	Setup	Examples	Auth	Score
Copilot	Automated: gh aw init scaffolds agent file + MCP wiring (cli.md:115,135-140)	111 declarations, 13 smoke variants	copilot-requests: write perm or COPILOT_GITHUB_TOKEN (how-they-work.mdx:32)	5/5
Claude	Manual: pointer only, no worked example (cli.md:139)	58 declarations, 9 smoke variants	ANTHROPIC_API_KEY or WIF; OAuth token unsupported/silently ignored (cli.md:240)	3/5
Codex	Manual: same pointer as Claude (cli.md:139)	75 declarations, 5 smoke variants	CODEX_API_KEY (precedence) or OPENAI_API_KEY (how-they-work.mdx:34)	3/5
Custom	Manual: per-MCP-server registration in own host config (cli.md:140)	1 declaration (nested only in shared/genaiscript.md), 0 smoke variants	Per-server secrets, e.g. SLACK_BOT_TOKEN (tools.md:266-274)	2/5

Engine-agnostic tools (13, including edit, github, bash, playwright, cache-memory) work identically across engines. Two tools have engine-conditional behavior: web-search (explicit rules only for Copilot/Claude/Codex, tools.md:126-128) and tools.timeout defaults (only Claude=60s and Codex=120s stated, tools.md:235). One tool has an engine-specific hard requirement: Pi needs tools.github.mode: gh-proxy and tools.cli-proxy: true (quick-start.mdx:175).

Counting methodology note: engine declarations use two YAML forms (inline engine: claude and nested engine:\n id: claude); counting only the inline form inverts the ranking (Claude 38 > Copilot 22) versus the true combined totals (Copilot 111 > Codex 75 > Claude 58) — both forms must be summed.

Auth Gaps

• Claude: CLAUDE_CODE_OAUTH_TOKEN is explicitly unsupported and silently ignored — the failure message never mentions the token, so a Claude Code user has no signal pointing at the real cause (cli.md:240). This caveat lives only inside secrets set help text, not in quick-start.mdx or the Claude engine page it links to.
• Codex: CODEX_API_KEY takes precedence over OPENAI_API_KEY if both are set — documented (how-they-work.mdx:34) but not repeated at the point of secret creation in quick-start.mdx:157-161.
• Pi: credential is selected implicitly via the model: field's provider prefix; this selection rule is stated only in quick-start.mdx:173, not in the engine overview (how-they-work.mdx:36) where a reader would first look.
• Custom/MCP servers: secrets are per-server and scattered across tools.md (Linear LINEAR_API_KEY:43, Jira ATLASSIAN_*:76,89-90, Slack SLACK_BOT_TOKEN:266-274) with no consolidated auth-gap summary page.

Recommended Actions

Priority 1

• Add an explicit callout in quick-start.mdx's Claude tab (and cli.md:240) that claude login OAuth tokens are not supported, before a user hits the misleading generic auth error.
• Extend gh aw init's automated scaffolding (or provide an explicit worked example) for Claude Code agent files and MCP wiring, matching what Copilot already gets (cli.md:135-140).

Priority 2

• Add 3-5 more Claude-engine example workflows and smoke-test variants to close the coverage gap with Copilot (currently 58 vs. 111, 9 vs. 13 smoke variants).
• Cross-link Pi's credential-selection rule (model: prefix) from how-they-work.mdx:36 into the engine overview table.

Priority 3

• Fill in web-search and tools.timeout default documentation for Gemini and Pi (tools.md:126-128,235).
• Add Pi to the "AI Account" prerequisite list in quick-start.mdx:72 since it's already an offered engine choice at line 125.

References:

• §36423821814 (this run)

Generated by 📝 Claude Code User Documentation Review · claude · agent · 232.1 AIC · ⌖ 7.47 AIC · ⊞ 6.4K · ◷

• expires on Sep 29, 2026, 4:55 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 #64277.