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

[github-actions[bot]]

Executive Summary

Good news: the CLAUDE_CODE_OAUTH_TOKEN gap flagged in every one of the last 21 consecutive daily runs (since 2026-08-22) is now resolved — it's explicitly documented as unsupported in four places, with clear guidance to use ANTHROPIC_API_KEY or WIF instead. No critical blockers remain for a Claude Code user this run. Two Major obstacles persist: gh aw init still doesn't scaffold a custom agent/MCP file for Claude the way it does for Copilot, and Claude's example-workflow coverage (58, 3 smoke variants) still trails Copilot's (113, 13 smoke variants) by ~1.95x.

Severity Findings

Critical Blockers: None found this run.

Major Obstacles

1. No scaffolding template for Claude custom agents. gh aw init --engine claude skips the custom agent file + MCP wiring that Copilot gets automatically; docs only say "author an agent file in your own agent's format" with no worked example. (cli.md:131-144, cli.md:139-140)
2. Example/smoke-test parity gap persists. Claude has 58 engine declarations across example workflows vs Copilot's 113 (~1.95x); smoke-test variants are 3 (smoke-claude, smoke-claude-on-copilot, smoke-github-claude) vs Copilot's 13 (sdk, aoai-entra, aoai-apikey, mai, arm, auto, sub-agents, small, etc). A Claude Code user has far fewer worked configuration examples to learn from. (.github/workflows/smoke-claude*.md vs .github/workflows/smoke-copilot*.md)

Minor Confusion

1. quick-start.mdx:72 lists AI Account prerequisites (Copilot/Claude/Codex/Gemini) but omits Pi, even though Pi is offered as a selectable engine later in the same doc (quick-start.mdx:28,125,171-175).
2. tools.md:126-128 documents per-engine web-search disable behavior for Copilot/Claude/Codex but leaves Gemini/Pi unspecified.
3. cli-proxy/gh-proxy mode (tools.md:199-229) reads as engine-agnostic config but is actually required specifically for Pi (quick-start.mdx:175) and optional elsewhere — the framing doesn't make that distinction clear.

Engine & Tool Matrix

Engine	Setup (gh aw init)	Examples (smoke variants)	Auth	Score
Copilot	Auto-scaffolds custom agent + MCP wiring (cli.md:115,131-144)	113 (13 smoke)	copilot-requests: write or COPILOT_GITHUB_TOKEN PAT	9/10
Claude	Manual — no template provided (cli.md:139-140)	58 (3 smoke)	ANTHROPIC_API_KEY or WIF; CLAUDE_CODE_OAUTH_TOKEN explicitly unsupported (now documented in 4 places)	6/10
Codex	Manual, same gap as Claude	75 (5 smoke)	CODEX_API_KEY (precedence) or OPENAI_API_KEY	7/10
Custom	Manual; no standalone example, only nested in shared/genaiscript.md	1 (0 smoke)	Custom MCP / engine.env, no dedicated secrets doc	3/10

Tool classification (from doc-reader): 12 engine-agnostic tool categories, 4 Copilot-only, 2 Claude-only, 2 Codex-only, 1 Gemini-only, 2 Pi-only, 2 with shared-but-engine-varying behavior. Ambiguous entries: tools.md:126-128 (web-search per-engine gaps for Gemini/Pi) and the cli-proxy/Pi coupling above.

Nested YAML form (engine:\n id: X) dominates real-world usage for Copilot (91/113) and Codex (70/75); Claude is closer to even (38 inline / 20 nested) — a scan that only checks the inline scalar form would badly undercount Copilot and Codex.

Auth Gaps

• Resolved this run: CLAUDE_CODE_OAUTH_TOKEN unsupported-token gap — now explicitly flagged at cli.md:240, auth.mdx:218-220, auth.mdx:428, and engines/claude.md:22, each pointing to ANTHROPIC_API_KEY/WIF as the fix.
• Still open: no worked example of a Claude Code custom agent file equivalent to Copilot's auto-generated .github/agents/agentic-workflows.md (cli.md:139-140 table shows a plain ❌ with no linked template).
• Setup steps are otherwise clearly ordered per engine in quick-start.mdx:133-175 (Copilot 133-143, Claude 145-153, Codex 155-161, Gemini 163-169, Pi 171-175).
• Minor: Pi missing from the AI Account prerequisites bullet (quick-start.mdx:72) despite being fully supported.

Recommended Actions

Priority 1: Add a worked template/example for authoring a Claude Code custom agent + MCP registration in cli.md (~line 140), mirroring what Copilot receives automatically from gh aw init.

Priority 2: Close the example/smoke-test gap — add Claude-side smoke-test variants analogous to Copilot's provider/config permutations (currently 3 vs 13), so Claude Code users have comparable worked references.

Priority 3: Add Pi to the AI Account prerequisites bullet at quick-start.mdx:72 for consistency with its selectable status elsewhere in the same document.

---

Automated daily review. Run §36570047037.

Generated by 📝 Claude Code User Documentation Review · claude · agent · 276.9 AIC · ⌖ 4.74 AIC · ⊞ 4.9K · ◷

• expires on Sep 30, 2026, 4:54 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 #64487.