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

[github-actions[bot]]

Executive Summary

A Claude Code user (no Copilot, no Copilot CLI) can onboard today — ANTHROPIC_API_KEY is documented at docs/src/content/docs/setup/quick-start.md:147-151, and the CLAUDE_CODE_OAUTH_TOKEN silent-ignore gap that blocked 29 consecutive daily runs since 2026-08-22 is still documented (quick-start.md:153, cli.md:240). The remaining friction is structural, not a hard stop: gh aw init still only auto-scaffolds a custom-agent file/MCP wiring for Copilot, Claude has ~1.9x fewer example workflows than Copilot, and Claude's WIF setup is link-only versus inline detail for other engines.

Severity Findings

Critical Blockers (0)

None. Core auth path for Claude (ANTHROPIC_API_KEY) is documented and functional end-to-end.

Major Obstacles

1. gh aw init artifact parity gap — only the Copilot engine path auto-creates the Agentic Workflows custom agent file (cli.md:115); Claude/Codex users get no equivalent scaffolding or pointer to do it manually (cli.md:139-140).
2. Example/smoke-test parity gap — 56 Claude vs. 108 Copilot workflow declarations (~1.93x) across .github/workflows/*.md; newer engines (aider, goose, opencode, kiro, cursor, crush, etc.) each have a dedicated smoke-<engine>.md, but Claude's own smoke coverage is comparatively thin, making it harder to find a worked Claude example to copy.
3. Claude setup requires a documentation hop — quick-start.md:155 links out to a separate "Using Claude Code with GitHub Agentic Workflows" guide for complete setup and defers WIF entirely to a reference-doc link (quick-start.md:151), whereas Codex's setup (quick-start.md:159-163) is fully inline with no second hop.

Minor Confusion

1. tools.md:128 disables web-search by default for Codex/Claude/Copilot but never states whether Gemini/Pi differ — a Claude user can't tell if the restriction is engine-specific or universal.
2. Prerequisites list (quick-start.md:72-77) lists "AI Account" as a generic step without noting Copilot uniquely needs no separate account creation — reads as if every engine needs an external signup.
3. Linear/Jira tool docs (tools.md:43,63) don't state whether the read-only/cli-proxy caveats apply uniformly across engines or only some.

Engine & Tool Matrix

	Copilot	Claude	Codex	Custom
Setup	Org billing or COPILOT_GITHUB_TOKEN PAT, inline (quick-start.md:135-143)	ANTHROPIC_API_KEY inline, WIF link-only, extra guide hop (quick-start.md:147-155)	OPENAI_API_KEY/CODEX_API_KEY, fully inline, no second hop (quick-start.md:159-163)	No dedicated quick-start section found in scanned docs
gh aw init scaffolding	Auto-creates custom agent + MCP wiring (cli.md:115)	None documented (cli.md:139-140)	None documented	None documented
Examples	108 workflows	56 workflows (~52% of Copilot)	75 workflows	Not present in counts_by_engine this run — effectively 0 standalone examples
Auth clarity	Clear, 2 paths, inline	Clear key path; WIF deferred to link	Clear, includes precedence note (CODEX_API_KEY > OPENAI_API_KEY)	Not documented in the 6 core docs scanned
Score	5/5	3/5	4/5	1/5

Universal tools (edit, github, bash, web-fetch, playwright, cache-memory, repo-memory, agentic-workflows, cli-proxy — 9 of 14 classified) work identically across all engines per tools.md, so the gap is onboarding/scaffolding, not runtime capability.

Auth Gaps

• Resolved this run (2nd+ consecutive): CLAUDE_CODE_OAUTH_TOKEN is explicitly called out as unsupported/silently-ignored in both quick-start.md:153 and cli.md:240.
• Still open: Anthropic WIF is reference-linked only (quick-start.md:151), with no inline example the way the Gemini/Codex sections provide; a Claude user evaluating "key vs. WIF" has to leave quick-start to decide.
• Still open: no auth guidance anywhere in the 6 scanned docs for the "Custom" engine class.

Recommended Actions

Priority 1 — Add a gh aw init --engine claude|codex scaffolding path (or explicit manual-steps callout) at cli.md:139-140 so non-Copilot users aren't silently left without the custom-agent/MCP wiring Copilot users get for free.

Priority 2 — Inline a minimal Anthropic WIF example directly in quick-start.md (near line 151) instead of a bare link, mirroring the Codex section's self-contained style.

Priority 3 — Backfill Claude-specific smoke/example workflows toward parity with Copilot (currently ~52%), and add one line to tools.md:128 clarifying whether web-search defaults differ for Gemini/Pi.

---

Note on this run: .claude/agents/doc-reader.md and .claude/agents/engine-example-counter.md again lacked the required name: frontmatter field and failed to register as custom agent types (17th consecutive day this has recurred). An Edit attempt to add name: doc-reader / name: engine-example-counter was denied by permissions again. Findings above were gathered via two parallel general-purpose fallback agents carrying the original instructions inline — filed separately via missing_tool.

References:

• §36863630325 (this run)
• §36716911073 (2026-09-30)
• §36570047037 (2026-09-29, OAuth gap first marked resolved)

Generated by 📝 Claude Code User Documentation Review · claude · agent · 113.4 AIC · ⌖ 4.22 AIC · ⊞ 5.2K · ◷

• expires on Oct 2, 2026, 4:51 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 #65018.