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

[github-actions[bot]]

Executive Summary

A Claude Code user with no Copilot can onboard via the API-key path (engines/claude.md:8-41, quick-start.mdx:145-155), but subscription logins are unsupported and several Copilot-first assumptions remain. Key finding: 1 critical blocker (subscription auth), 6 major obstacles, 8 minor items. The CLAUDE_CODE_OAUTH_TOKEN wording still contradicts itself.

Severity Findings

Critical, Major and Minor findings (click to expand)

Critical blockers

• Claude Pro/Max/Team subscription login cannot authenticate. Users must buy an API key or set up WIF (engines/claude.md:6, auth.mdx:221, quick-start.mdx:153, faq.md:523-525). Fix: add a prominent "Using a Claude subscription?" callout in quick-start with the cheapest supported alternative.

Major obstacles

• Wizard ANTHROPIC_API_KEY setup is documented only for the PR path; direct-push is undefined (cli.md:207).
• Quick-start add-wizard shows no --engine claude (quick-start.mdx:105-125; cli.md:199 lists the flag). The sample workflow engine is not stated (unverified).
• No Claude Code wiring for the gh aw dispatcher skill (cli.md:179-181) or the mcp-server (generic JSON only, gh-aw-as-mcp-server.md:94-113).
• WIF needs Anthropic-console federation setup with no in-repo steps (auth.mdx:234-236, quick-start.mdx:151).
• Model routing needs Copilot inference for Claude (model-routing.md:337).
• Omitting engine: claude silently selects Copilot auth (creating-workflows.mdx:74, reference/engines.md:16); gh aw new without --engine writes none (cli.md:250-268).

Minor confusion

• auth.mdx:221 says the OAuth token is "ignored", while quick-start.mdx:153 and cli.md:287 say the CLI errors.
• Dangling reference: auth.mdx:223 promises Claude + GitHub MCP config in the engines page; reference/engines.md:12-29 has none, and github-tools.md:10 says none is needed.
• quick-start.mdx:51 says "only the GitHub CLI", but :70,74 add an AI account and scopes.
• cli.md:179 says the dispatcher skill is "not needed" yet "created for every engine".
• engines/claude.md:12 offers Copilot billing without the subscription prerequisite (auth.mdx:123).
• Examples default to engine: copilot (architecture.mdx:263-264, web-search.md:20); sudo guidance is Copilot-only (self-hosted-runners.md:36).

Engine & Tool Matrix

Examples are top-level .github/workflows/*.md declarations (339 main-engine total; hand-tallied, ±2).

Engine	Setup	Examples	Auth	Score
Copilot	Default, first in every table (reference/engines.md:16)	135	copilot-requests: write or COPILOT_GITHUB_TOKEN (auth.mdx:108-153)	5/5
Claude	Clear page with sample (engines/claude.md:14-41)	63	ANTHROPIC_API_KEY or WIF; OAuth unsupported (auth.mdx:201-291)	3/5
Codex	Quick-start block (quick-start.mdx:159-163)	77	CODEX_API_KEY / OPENAI_API_KEY (auth.mdx:34-37)	4/5
Custom	Not covered by doc-reader	0	Not assessed	n/a

Parity: Copilot:Claude is about 2.1:1 in workflow files. Another 64 declarations (19%) use other engines, mostly pi (38). Claude-specific limits (default dontAsk mode, tool restrictions) live only in reference/engines/claude.md:35,63-80, not on the beginner page.

Tool classification (17 tools, from tools.md): 5 builtin, 2 builtin-auth-conditional (github, agentic-workflows), 2 engine-native (web-fetch, web-search), 2 hosted-MCP with secrets (linear, jira), 2 experimental (drive-memory, qmd), 1 transport option (cli-proxy), 2 config options, 1 custom (mcp-servers). Only github remote mode, linear, jira and custom MCP servers need extra secrets (tools.md:43,69-94, github-tools.md:124,156). Ambiguous: repo-memory auth is unstated (tools.md:166-175), and mcp-servers are startup-critical by default (tools.md:326).

Auth Gaps

• Claude secrets: ANTHROPIC_API_KEY (auth.mdx:205-213) or keyless WIF with id-token: write (auth.mdx:238-258). The Claude page gives no secrets set command, only a link (engines/claude.md:10).
• Subscription OAuth: unsupported, with contradictory wording (see Minor).
• Wizard: key setup only on the PR path (cli.md:207).
• WIF: no step list for the Anthropic federation rule (auth.mdx:234-236).
• Copilot-billed Claude: the prerequisite is stated only in auth.mdx:123.

Recommended Actions

Priority 1

• Add a subscription-user callout and fix the OAuth wording to one statement in auth.mdx:221, quick-start.mdx:153, cli.md:287.
• Show gh aw add-wizard ... --engine claude and gh aw secrets set ANTHROPIC_API_KEY in quick-start.

Priority 2

• Document the wizard direct-push secret path (cli.md:207) and the default-engine fallback warning.
• Add Claude Code skill and MCP host setup (.claude/skills, MCP config snippet).
• Add WIF step list for Anthropic.

Priority 3

• Fix the dangling auth.mdx:223 link.
• Add Claude variants to Copilot-only examples (architecture.mdx:263, web-search.md:20, model-routing.md).
• Promote dontAsk mode notes to engines/claude.md.

References: §40955414354

Generated by 📝 Claude Code User Documentation Review · claude · routed: sonnet55 high · ~51 AIC · ⌖ ~1 AIC · ⊞ 2.7K · ◷

• expires on Oct 30, 2026, 1:18 PM 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 #73063.