🔍 Claude Code User Documentation Review - 2026-03-11

[github-actions[bot]]

Executive Summary

As a developer who uses Claude Code exclusively (no GitHub Copilot subscription), I reviewed the gh-aw documentation to assess whether I could successfully understand and adopt this tool. The documentation is genuinely good for Claude Code users — there are zero critical blockers and the core quick start, authentication, and engines docs explicitly support non-Copilot workflows. The main issues are cosmetic: architecture diagrams that label the AI agent container as "Copilot CLI" (instead of a generic "AI Engine"), one section of the creating-workflows guide that's Copilot-gated, and a few omissions in fringe documentation pages.

Key Finding: Claude Code users can successfully adopt gh-aw with only minor friction. The score is stable at 7/10 for the 14th consecutive day — indicating these remaining issues are known but not yet prioritized.

Trend note: Compared to yesterday's run (2026-03-10, score 7/10), no score change. The same persistent issues remain. Architecture diagram Copilot-centric framing and the creating-workflows Web Interface section are the two most visible recurring gaps.

---

Persona Context

I reviewed this documentation as a developer who:

• ✅ Uses GitHub for version control
• ✅ Uses Claude Code as primary AI assistant
• ❌ Does NOT use GitHub Copilot
• ❌ Does NOT use Copilot CLI
• ❌ Does NOT have Copilot subscription

---

Question 1: Onboarding Experience

Can a Claude Code user understand and get started with gh-aw?

Yes. The Quick Start guide (docs/src/content/docs/setup/quick-start.mdx) opens with:

AI Account - GitHub Copilot, Anthropic Claude or [OpenAI Codex]((openai.com/redacted)

This immediately signals that Claude is a valid first-class option. The gh aw add-wizard command (Step 2) walks users through engine selection interactively, covering Copilot, Claude, and Codex — and the corresponding secret setup.

The how-they-work.mdx intro says: "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex." This is close, but now outdated — Gemini is a 4th supported engine (documented in engines.md and auth.mdx but missing from this introductory framing).

Specific Issues Found:

• Issue 1: docs/src/content/docs/introduction/how-they-work.mdx line 26 — still lists only 3 engines: "Copilot (default), Claude by Anthropic, and Codex." Gemini has been added as a 4th engine but isn't reflected here.
• Issue 2: docs/src/content/docs/setup/creating-workflows.mdx line 21 — the "GitHub Web Interface" authoring section opens with: "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." No equivalent guidance is given for Claude Code users who want to use this web-based approach. The next section ("VSCode/Claude/Codex/Copilot") does include Claude, but the web interface section leaves Claude users without a path.

Recommended Fixes:

• Update how-they-work.mdx to mention Gemini alongside the other three engines, or use generic language ("multiple AI engines")
• In creating-workflows.mdx, add a note after the Copilot-gated section explaining that Claude Code users can use the same prompt directly in Claude Code CLI to create workflows

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Only one safe output is Copilot-exclusive by design: assign-to-agent (documented at docs/src/content/docs/reference/assign-to-copilot.mdx). This feature programmatically assigns the Copilot coding agent to GitHub issues/PRs — it's inherently Copilot-specific and correctly documented as such. This is not a documentation gap; it's expected.

Features That Require Copilot:

• assign-to-agent safe output with name: copilot — assigns Copilot coding agent to issues/PRs. Explicitly documented. No alternative needed for the use case (assigning Copilot to issues is intrinsically Copilot-only).

Features That Work Without Copilot (engine-agnostic):

• All CLI commands: init, compile, run, list, status, logs, audit, health, validate, trial
• All tools: github, edit, bash, web-fetch, playwright, cache-memory, repo-memory, agentic-workflows
• All safe outputs except assign-to-agent
• Custom MCP servers
• Secrets management (gh aw secrets set, gh aw secrets bootstrap)
• The --engine claude flag on gh aw new

Missing Documentation:

• The creating-workflows.mdx Web Interface section lacks a Claude Code equivalent path. A simple addition like: "For Claude Code users, use the same prompt in your Claude Code CLI session" would resolve this.

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• docs/src/content/docs/introduction/architecture.mdx — The AWF (Agent Workflow Firewall) Mermaid diagram (around line 175) shows COPILOT["Copilot CLI"] in the "AI Agent Process" subgraph. The MCP Gateway diagram (around line 248) shows AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"]. These imply Copilot is the only agent that runs in the sandbox, which is confusing since Claude and Codex also run there.
• docs/src/content/docs/introduction/architecture.mdx line 222 — The network configuration example shows engine: copilot as the only illustration, even though the network: config is engine-agnostic.
• docs/src/content/docs/reference/copilot-custom-agents.md — Title is "Importing Copilot Agent Files"; all examples show engine: copilot. The note that "other engines (Claude, Codex) inject the markdown body as a prompt" is buried. Could be confusing for Claude users who wonder if they can use agent files.

Potential URL Issue:

• docs/src/content/docs/reference/auth.mdx line 104 — ANTHROPIC_API_KEY setup says _"Create an API key at (platform.claude.com/redacted) Anthropic API keys are created at console.anthropic.com, not platform.claude.com. This has been flagged in previous runs and remains unresolved.

Missing Alternative Instructions:

• No equivalent "create workflow from web interface" guide for Claude Code users

---

Severity-Categorized Findings

🚫 Critical Blockers — None found (Score: 0 blockers)

There are zero critical blockers for Claude Code users. All essential documentation exists, authentication is fully documented, and the core workflow (install → select Claude engine → set ANTHROPIC_API_KEY → compile → run) is clearly supported throughout the docs.

⚠️ Major Obstacles (2 found)

Obstacle 1: Architecture Diagrams Show "Copilot CLI" as the Agent

Impact: Significant confusion for first-time Claude users reading the architecture docs

Current State: The AWF Mermaid diagram in architecture.mdx labels the AI agent subprocess as COPILOT["Copilot CLI"]. The MCP Gateway diagram shows AGENT["Agent container\nCopilot CLI + MCP client\n172.30.0.20"]. A Claude user reading the security architecture page would see these diagrams and reasonably wonder whether the security sandbox is designed for Copilot only.

Why It's Problematic: Architecture documentation is often read by users evaluating adoption viability. Seeing only "Copilot CLI" in the security diagrams may cause them to abandon evaluation prematurely.

Suggested Fix: Rename diagram nodes to AGENT["AI Engine\n(Copilot CLI / Claude Code / Codex)"] or simply AGENT["Coding Agent"] to make the diagrams engine-agnostic. The network config example could show engine: claude as an alternative.

Affected Files: docs/src/content/docs/introduction/architecture.mdx (lines ~175, ~248, ~222)

Obstacle 2: Web Interface Workflow Creation Is Copilot-Only

Impact: Claude Code users are excluded from the "GitHub Web Interface" authoring path

Current State: creating-workflows.mdx line 21: "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." There is no equivalent guidance for Claude Code users who prefer web-based or chat-based authoring from github.com. The section immediately following ("VSCode/Claude/Codex/Copilot") covers Claude, but the web creation pathway is Copilot-exclusive.

Why It's Problematic: This creates a two-tier experience impression: Copilot users get a web interface authoring path; Claude users do not. Even if the underlying limitation is real (Claude Code doesn't natively integrate into github.com), a note explaining this would prevent confusion.

Suggested Fix: After the Copilot web interface block, add a callout: "Claude Code users: Use the same prompt in your Claude Code CLI session or any markdown editor to create the workflow file manually." The manual editing section below already covers this — just add a bridging note.

Affected Files: docs/src/content/docs/setup/creating-workflows.mdx (line ~21)

💡 Minor Confusion Points (7 found)

• Issue 1: how-they-work.mdx line 26 — Gemini omitted from engine list. Says "Copilot (default), Claude by Anthropic, and Codex" but Gemini is now a 4th engine in engines.md and auth.mdx.
• Issue 2: auth.mdx line 104 — ANTHROPIC_API_KEY setup URL ((platform.claude.com/redacted) may be incorrect. Anthropic API keys are created at console.anthropic.com`. (Flagged in multiple previous runs — 14+ days unresolved.)
• Issue 3: copilot-custom-agents.md — Page title "Importing Copilot Agent Files" and all examples use engine: copilot. The explanation that Claude/Codex inject the body as a prompt is present but non-obvious. Consider renaming to "Agent Files" or adding a Claude-specific note.
• Issue 4: architecture.mdx line ~222 — Network config example only shows engine: copilot. Since the network: field is engine-agnostic, showing a Claude example alongside (or instead) would reinforce that point.
• Issue 5: engines.md "Copilot Custom Configuration" section header — reads as Copilot-exclusive but the underlying agent: field is the Copilot-specific concept. Adding "Claude/Codex equivalent: use imports: for shared agent instructions" would help.
• Issue 6: No "engine comparison" guide — there's no page summarizing trade-offs or capabilities by engine (cost, speed, supported tools, model quality). Claude users coming from Copilot would benefit from understanding the practical differences.
• Issue 7: Default engine is Copilot, meaning engine: can be omitted for Copilot users. Claude users must always specify engine: claude in their frontmatter. This is documented in engines.md but could be more prominently flagged in the Quick Start.

---

Engine Comparison Analysis

Available Engines (from docs/src/content/docs/reference/engines.md)

Engine	engine: value	Required Secret	Notes
GitHub Copilot CLI (default)	copilot (or omit)	COPILOT_GITHUB_TOKEN	Requires Copilot subscription
Claude by Anthropic	claude	ANTHROPIC_API_KEY	Uses Anthropic API
OpenAI Codex	codex	OPENAI_API_KEY	Uses OpenAI API
Google Gemini CLI	gemini	GEMINI_API_KEY	Added recently

Documentation Quality by Engine

Engine	Setup Docs	Examples in Repo	Auth Docs	Overall
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐ (79 workflows)	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐⭐	⭐⭐⭐⭐ (34 workflows)	⭐⭐⭐⭐	⭐⭐⭐⭐
Codex	⭐⭐⭐⭐	⭐⭐⭐ (10 workflows)	⭐⭐⭐⭐	⭐⭐⭐
Gemini	⭐⭐⭐	⭐ (0 workflows)	⭐⭐⭐⭐	⭐⭐

Rating Scale: ⭐⭐⭐⭐⭐ Excellent → ⭐ Poor/Missing

Claude has strong documentation and real-world examples. The 34 Claude workflows in .github/workflows/ represent 20.5% of all workflow files — a healthy proportion. Copilot's dominance (79 workflows, 47.6%) reflects its default status, not a documentation choice.

---

Tool Availability Analysis

Engine-Agnostic Tools (work with any engine):

• github: — GitHub API operations via MCP
• edit: — File editing in workspace
• bash: — Shell command execution
• web-fetch: — Web content fetching
• web-search: — Web search (engine-dependent behavior but not restricted)
• playwright: — Browser automation
• cache-memory: — Persistent memory across runs
• repo-memory: — Repository-specific memory
• agentic-workflows: — Workflow introspection
• Custom mcp-servers: — Any MCP integration

Engine-Specific Safe Outputs:

• assign-to-agent — Only supports name: copilot as the agent (by design — it assigns Copilot coding agent to GitHub issues)

Unclear/Undocumented:

• web-search: — Docs note "Some engines require third-party MCP servers for web search" but don't specify which engines or what to configure. Claude Code users may be unsure if their chosen engine supports web search natively.

---

Authentication Requirements

Current Documentation Status

Engine	Auth Documented	Secret Name	Setup URL	Status
Copilot	✅ Full	COPILOT_GITHUB_TOKEN	Fine-grained PAT creation link	Complete
Claude	✅ Good	ANTHROPIC_API_KEY	platform.claude.com/docs (⚠️ may be wrong URL)	Good with one caveat
Codex	✅ Good	OPENAI_API_KEY	platform.openai.com/api-keys	Complete
Gemini	✅ Good	GEMINI_API_KEY	aistudio.google.com/api-keys	Complete

Missing for Claude Users

1. API key URL — auth.mdx links to (platform.claude.com/redacted) for creating the ANTHROPIC_API_KEY. Anthropic API keys are created at https://console.anthropic.com/`, not platform.claude.com. This misdirection could stall a new user trying to get started.

2. CLAUDE_CODE_OAUTH_TOKEN clarity — The FAQ does address this proactively (Q: "Can I use CLAUDE_CODE_OAUTH_TOKEN with the Claude engine?" A: No, only ANTHROPIC_API_KEY). This is excellent proactive documentation for Claude Code users.

Secret Names Summary

• Copilot: COPILOT_GITHUB_TOKEN (documented, creation link provided)
• Claude: ANTHROPIC_API_KEY (documented, URL may be wrong)
• Codex: OPENAI_API_KEY (documented)
• Gemini: GEMINI_API_KEY (documented)

---

Example Workflow Analysis

Workflow Count by Engine (.github/workflows/*.md)

Engine: copilot     — 79 workflows (47.6%)
Engine: claude      — 34 workflows (20.5%)
Engine: codex       — 10 workflows (6.0%)
Engine: gemini      —  0 workflows (0.0%)
No engine specified — 43 workflows (25.9%) [defaults to Copilot]
Total               — 166 workflow files

Quality Assessment

Claude Examples (34 workflows):
The Claude workflow examples are high quality and diverse. This workflow itself (claude-code-user-docs-review.md) uses engine: claude and demonstrates real-world use. Other Claude workflows include audit-workflows.md, blog-auditor.md, cli-version-checker.md, and daily-issues-report.md. These 34 examples give Claude users concrete, real-world templates to learn from.

Copilot Examples (79 workflows):
As the default engine, Copilot has the most examples. Many are in workflows that don't specify an engine (the 43 unspecified ones default to Copilot). This isn't a documentation problem — it reflects historical default behavior and organic growth.

Gemini (0 workflows):
No real-world Gemini workflow examples exist yet. Documentation covers the engine but there are no .github/workflows/*.md files using it. This limits learning by example for early Gemini adopters.

---

Recommended Actions

Priority 1: High-Value Quick Fixes

1. Fix ANTHROPIC_API_KEY setup URL — Change (platform.claude.com/redacted) to https://console.anthropic.com/` in auth.mdx line 104. (14+ days unresolved)

2. Add Gemini to how-they-work.mdx engine list — Line 26 currently says "Copilot (default), Claude by Anthropic, and Codex." Add Gemini to match engines.md. A generic "and others" phrasing would future-proof against the next engine addition.

3. Add Claude Code authoring note to creating-workflows.mdx — After the Copilot-gated web interface block (line ~21), add: "Claude Code users can use the same creation prompt in Claude Code CLI or any coding agent."

Priority 2: Architecture Diagram Updates

4. Generalize architecture diagram agent labels — In architecture.mdx, rename COPILOT["Copilot CLI"] to AGENT["Coding Agent\n(Copilot CLI / Claude Code / Codex)"] in the AWF and MCP Gateway diagrams. The security model applies to all engines — the diagram should reflect this.

5. Add Claude network config example — In architecture.mdx line ~222, add a engine: claude example alongside the existing engine: copilot one to demonstrate engine-agnostic network configuration.

Priority 3: Nice-to-Have Enhancements

6. Engine comparison guide — A simple table or short guide comparing Copilot vs Claude vs Codex in terms of cost model, latency, capabilities, and model defaults would help users choose. Could live in engines.md or as a new guide page.

7. Web search per-engine clarification — tools.md mentions "some engines require third-party MCP servers for web search." Specify which engines support native web search vs which need an MCP server.

8. Add a Gemini workflow example — Add one real-world .github/workflows/*.md using engine: gemini to give early adopters a starting point.

---

Positive Findings

What Works Well for Claude Code Users

• ✅ Quick Start prerequisites explicitly list Anthropic Claude as a first-class AI account option (alongside Copilot and Codex)
• ✅ gh aw add-wizard interactively guides through engine selection — Claude is an option, and the correct ANTHROPIC_API_KEY secret is prompted for
• ✅ Authentication docs (auth.mdx) fully document all 4 engines with equal depth; FAQ addresses CLAUDE_CODE_OAUTH_TOKEN limitation proactively
• ✅ Engines reference (engines.md) has a clear table and now shows version pinning examples for all 4 engines including Gemini
• ✅ All tools are engine-agnostic — github:, playwright:, bash:, cache-memory:, web-fetch: all work identically with Claude
• ✅ 34 real-world Claude engine workflows in the repo (20.5% of total) — strong by-example learning material
• ✅ All CLI commands work identically regardless of engine (compile, run, validate, audit, logs, etc.)
• ✅ gh aw new --engine claude generates correct frontmatter with engine: claude — great CLI UX for Claude users
• ✅ creating-workflows.mdx "VSCode/Claude/Codex/Copilot" section explicitly names Claude in the heading and body
• ✅ This workflow itself (claude-code-user-docs-review.md) runs on engine: claude — the project eats its own dog food

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes

The documentation is genuinely multi-engine. Claude Code users can install the extension, run gh aw add-wizard, select Claude, set their ANTHROPIC_API_KEY, and be running their first workflow within 10 minutes — exactly as described in the Quick Start. There are no missing steps, no Copilot-only installation requirements, and no features that block Claude users from the core value proposition.

The remaining issues are presentation and polish: architecture diagrams that default to "Copilot CLI" branding, a web interface authoring section that's Copilot-only, and a few pages that don't mention the full engine roster. These create minor friction and a slight "Copilot-first" impression, but none prevent successful adoption.

Overall Assessment Score: 7/10

Breakdown:

• Clarity for non-Copilot users: 7/10
• Claude engine documentation: 8/10
• Alternative approaches provided: 8/10
• Engine parity (documentation depth): 6/10

Score trend: Stable at 7/10 for ~14 consecutive days. The same set of architectural diagram issues and minor omissions persist. These appear to be known low-priority gaps rather than overlooked problems.

Next Steps

The Priority 1 fixes (ANTHROPIC_API_KEY URL correction, Gemini mention in how-they-work.mdx, Claude authoring note in creating-workflows.mdx) are small changes that would meaningfully improve the Claude Code user experience. The architecture diagram generalization (Priority 2) would improve the professional impression of the docs for non-Copilot evaluators. None of these require API changes or major restructuring.

---

Appendix: Files Reviewed

Complete List of Documentation Files Analyzed

• README.md
• docs/src/content/docs/setup/quick-start.mdx
• docs/src/content/docs/introduction/how-they-work.mdx
• docs/src/content/docs/introduction/architecture.mdx
• docs/src/content/docs/reference/tools.md
• docs/src/content/docs/setup/cli.md
• docs/src/content/docs/reference/engines.md
• docs/src/content/docs/reference/auth.mdx
• docs/src/content/docs/reference/faq.md
• docs/src/content/docs/reference/copilot-custom-agents.md
• docs/src/content/docs/reference/assign-to-copilot.mdx
• docs/src/content/docs/reference/github-tools.md
• docs/src/content/docs/setup/creating-workflows.mdx
• .github/workflows/claude-code-user-docs-review.md (this workflow)
• .github/workflows/*.md (engine grep analysis across all 166 workflow files)

---

Report Generated: 22977531455
Workflow: claude-code-user-docs-review
Engine Used: claude (eating our own dog food!)
Previous Run: 2026-03-10 (score: 7/10, no change)

AI generated by Claude Code User Documentation Review · history

• expires on Mar 12, 2026, 10:37 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-03-12T22:37:10.711Z.

Closed by Workflow