Claude Code User Documentation Review - 2026-02-21

[github-actions[bot]]

Executive Summary

I reviewed the gh-aw documentation as a developer who uses Claude Code as their primary AI assistant and does not have GitHub Copilot access. Overall, the documentation is solid — Claude Code users can successfully adopt gh-aw, but they will encounter several friction points caused by Copilot-centric language and gaps in engine-specific guidance. No critical blockers exist, but six major obstacles and seven minor confusion points need attention.

Key Finding: Claude Code users can get started with gh-aw, particularly via the Quick Start guide which clearly lists Anthropic Claude as a first-class option. However, several areas of the documentation implicitly assume Copilot access, and the primary "agentic authoring" workflow is entirely unavailable to non-Copilot users.

---

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?

Short answer: Yes. The Quick Start (docs/src/content/docs/setup/quick-start.mdx) is well-written for non-Copilot users. Prerequisites explicitly list Anthropic Claude as one of three AI account options (line 29), and gh aw add-wizard guides users through engine selection interactively (line 64-68).

The Engines reference (docs/src/content/docs/reference/engines.md) has a clearly labeled section ## Using Claude by Anthropic (Claude Code) with concise, accurate setup instructions. Authentication (docs/src/content/docs/reference/auth.mdx) documents ANTHROPIC_API_KEY correctly.

Specific Issues Found:

• Issue 1: docs/src/content/docs/setup/creating-workflows.mdx:21 — The "GitHub Web Interface" section opens with "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." There is no alternative path shown for Claude Code users wanting to create workflows from the GitHub web UI. A user without Copilot reads this and hits a dead end with no guidance on how to proceed.

• Issue 2: docs/src/content/docs/reference/custom-agent-for-aw.mdx — This entire guide is titled "Copilot Agent Files support for Agentic Workflows" and exclusively covers the /agent agentic-workflows Copilot Chat command. For Claude Code users, this guide provides zero actionable guidance. There is no equivalent "Claude Code users: here's how to get AI assistance for authoring workflows" section.

• Issue 3: docs/src/content/docs/setup/creating-workflows.mdx:96 — Step 3 says "If not using Copilot, also adjust the engine: field in your workflow's frontmatter." This implies that AI-assisted workflow generation defaults to creating Copilot-engine workflows. Claude users must remember to change the default engine after creation.

Recommended Fixes:

• Add a "Without Copilot" note or tab to the GitHub Web Interface section directing users to the terminal-based approach
• Add a "Using Claude Code for Workflow Authoring" guide equivalent to custom-agent-for-aw.mdx
• Make the creating-workflows workflow creation prompt engine-aware by including engine: claude in generated workflow frontmatter when the user specifies Claude

---

Question 2: Inaccessible Features for Non-Copilot Users

What features or steps don't work without Copilot?

Features That Require Copilot:

• GitHub Web Interface workflow creation — The creating-workflows.mdx web UI method requires Copilot Chat access. No alternative path is shown.
• /agent agentic-workflows Copilot Chat command — The custom-agent-for-aw.mdx workflow authoring agent is exclusively available in Copilot Chat and VSCode Agent Mode with Copilot.
• GH_AW_AGENT_TOKEN and assign-to-agent safe output — These are used to programmatically assign issues/PRs to the GitHub Copilot coding agent. Claude users will never need this, but the auth page could be clearer that this is Copilot-only.

Features That Work Without Copilot (Engine-Agnostic):

• All core workflow execution features
• All GitHub tools (github:, toolsets)
• bash:, edit:, playwright: tools
• All safe outputs (create-issue, create-pull-request, add-comment, etc.)
• cache-memory:, repo-memory:, agentic-workflows: built-in MCP tools
• All CLI commands (compile, run, status, logs, audit, trial, etc.)
• gh aw add-wizard with engine selection
• gh aw secrets bootstrap --engine claude

Missing Documentation:

• No explicit "engine compatibility matrix" showing which features work with which engines. When a user sees "Some engines require third-party MCP servers for web search" (tools.md:51), they don't know if Claude is one that needs the MCP server or has native search.

---

Question 3: Documentation Gaps and Assumptions

Where does the documentation assume Copilot usage?

Copilot-Centric Language Found In:

• File: docs/src/content/docs/setup/cli.md:120 — gh aw init description: "Configures .gitattributes, Copilot instructions, prompt files..." Claude users will wonder why init creates "Copilot instructions" files. The description needs to clarify these are general agent configuration files, not Copilot-specific.

• File: docs/src/content/docs/introduction/architecture.mdx:248 — Mermaid diagram labels the agent container as "Copilot CLI + MCP client". While the surrounding text correctly says "Copilot, Claude, Codex," a Claude Code user reading this diagram sees only Copilot as the agent running in the container. Suggest renaming to "AI Agent + MCP client".

• File: docs/src/content/docs/introduction/architecture.mdx:177 — Mermaid diagram under "Agent Workflow Firewall" shows COPILOT["Copilot CLI"] as the sole agent process inside the firewall container. Codex and Claude are absent from this diagram.

• File: docs/src/content/docs/guides/web-search.md:14-32 — Web search guide uses engine: copilot exclusively in its example. For Claude users (where web search is "engine-dependent" per tools.md), this is either an incomplete example or incorrectly implies web search requires Copilot. No clarification on whether Claude has native web search.

• File: docs/src/content/docs/troubleshooting/common-issues.md — Troubleshooting section contains Copilot-specific sections ("Copilot CLI Not Found", "Copilot License or Inference Access Issues") but zero Claude-specific troubleshooting entries (e.g., "ANTHROPIC_API_KEY not recognized", "Claude rate limiting", "Claude model selection").

• File: docs/src/content/docs/troubleshooting/common-issues.md:422 — Debugging suggestion says "use Copilot Chat (/agent agentic-workflows debug)" which is unavailable to Claude Code users.

Missing Alternative Instructions:

• No guide for creating workflows using Claude Code (equivalent to the Copilot Chat /agent agentic-workflows workflow)
• No Claude-specific troubleshooting section
• No explicit note on whether Claude supports native web-search: or requires an MCP server

---

Severity-Categorized Findings

🚫 Critical Blockers (Score: 0)

No critical blockers found. A Claude Code user can successfully install the extension, set up ANTHROPIC_API_KEY, create a workflow with engine: claude, and run it. The core path works.

---

⚠️ Major Obstacles (Score: 6 found)

Obstacle 1: Web-Based Workflow Creation Copilot-Gated

Impact: Claude Code users cannot use the most prominent workflow creation method shown in docs.

Current State: creating-workflows.mdx:21 states "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." The section ends there — no alternative for non-Copilot users.

Why It's Problematic: A developer without Copilot who reads the "Creating Agentic Workflows" guide sees the first and easiest creation method (web UI) gated behind Copilot, then must scroll to section 2 to find a path that works for them.

Suggested Fix: Add a callout after the Copilot section: "Without Copilot: Use the terminal approach below with Claude Code or another coding agent." Or restructure to lead with the engine-agnostic terminal approach.

Affected Files: docs/src/content/docs/setup/creating-workflows.mdx

Obstacle 2: gh aw init Describes "Copilot Instructions" Without Clarification

Impact: Confuses Claude Code users into thinking init creates Copilot-specific files they don't need.

Current State: CLI docs (cli.md:120): "Initialize repository for agentic workflows. Configures .gitattributes, Copilot instructions, prompt files, and logs .gitignore."

Why It's Problematic: A Claude Code user wondering "should I run gh aw init?" sees "Copilot instructions" in the description and may skip this step or be confused about what's being installed. The actual init is engine-agnostic and valuable for all users.

Suggested Fix: Change to: "Configures .gitattributes, agent configuration files (including Copilot agent instructions), prompt files, and .gitignore." Or simply: "Sets up repository configuration files for agentic workflow development."

Affected Files: docs/src/content/docs/setup/cli.md:120

Obstacle 3: Architecture Diagrams Show Only Copilot CLI

Impact: Creates false impression that the firewall and execution architecture only works with Copilot.

Current State: architecture.mdx:248 labels the agent container "Copilot CLI + MCP client". architecture.mdx:177 shows COPILOT["Copilot CLI"] as the only agent inside the firewall diagram.

Why It's Problematic: Architecture documentation is often used to understand "how things work under the hood." Claude Code users reading these diagrams see only Copilot. When they run a Claude-engine workflow, they may doubt whether the firewall and isolation apply to their engine.

Suggested Fix: Change labels to "AI Agent (Copilot/Claude/Codex) + MCP client" in the container diagram and AGENT["AI Agent CLI"] in the firewall diagram.

Affected Files: docs/src/content/docs/introduction/architecture.mdx

Obstacle 4: No Claude-Equivalent of the Agentic Authoring Guide

Impact: Claude Code users lack AI-assisted workflow creation guidance.

Current State: custom-agent-for-aw.mdx provides a complete guide for using the /agent agentic-workflows Copilot Chat command to create, update, debug, and upgrade workflows. This is entirely inaccessible to Claude Code users.

Why It's Problematic: This is the featured "AI-assisted authoring" guide. Claude Code users are directed to it in the creating-workflows guide but find nothing applicable to their toolchain.

Suggested Fix: Add a section or companion guide: "Using Claude Code for Workflow Authoring" showing how to use Claude Code's slash commands and context to accomplish the same tasks (create, update, debug workflows) using Claude Code CLI.

Affected Files: docs/src/content/docs/reference/custom-agent-for-aw.mdx, docs/src/content/docs/guides/agentic-authoring.mdx

Obstacle 5: Web Search Engine Dependency Undocumented for Claude

Impact: Claude users don't know if they need a third-party MCP server for web search.

Current State: tools.md:48-51 lists web-search: and notes: "Some engines require third-party Model Context Protocol (MCP) servers for web search." The web-search.md guide shows only a Copilot-engine example.

Why It's Problematic: Claude Code has native web search capability. If a Claude-engine workflow uses tools: web-search:, it may or may not work natively. The documentation doesn't tell Claude users whether they need the Tavily MCP server or if Claude's built-in search works.

Suggested Fix: Add an engine compatibility table to tools.md or web-search.md:

Engine	Native web-search	Requires MCP
Copilot	✅	No
Claude	✅	No
Codex	❓	Possibly

Affected Files: docs/src/content/docs/reference/tools.md, docs/src/content/docs/guides/web-search.md

Obstacle 6: Broken Link Syntax in ANTHROPIC_API_KEY Auth Doc

Impact: The "See also" reference in Claude auth instructions is a broken link, not a clickable link.

Current State: auth.mdx:113: See also (/gh-aw/reference/engines/#using-claude-by-anthropic-claude-code) for additional configuration needed when using Claude with GitHub MCP.

Why It's Problematic: This is not valid markdown link syntax. It renders as literal text instead of a clickable link, and the same broken pattern appears for the Codex entry on line 131. Claude users following auth setup won't be able to click through to the additional GitHub MCP configuration.

Suggested Fix: Change to: See also [AI Engines: Claude](/gh-aw/reference/engines/#using-claude-by-anthropic-claude-code) for additional configuration needed when using Claude with GitHub MCP.

Affected Files: docs/src/content/docs/reference/auth.mdx:113,131

---

💡 Minor Confusion Points (Score: 7 found)

• Issue 1: docs/src/content/docs/reference/engines.md:87-88 — Extended engine config example shows model: gpt-5 # defaults to claude-sonnet-4. This comment is contradictory: it shows gpt-5 but says the default is claude-sonnet-4. Should clarify which is the actual default per-engine.
• Issue 2: docs/src/content/docs/troubleshooting/common-issues.md:422 — Suggests "use Copilot Chat (/agent agentic-workflows debug)" for debugging. Claude Code users should be told to use Claude Code CLI with the workflow context instead.
• Issue 3: docs/src/content/docs/setup/creating-workflows.mdx:96 — "If not using Copilot, also adjust the engine: field" implies Copilot is the default and Claude users must correct the default. While accurate, this framing positions Claude as the non-default "other" rather than a peer choice.
• Issue 4: docs/src/content/docs/reference/copilot-custom-agents.md — Title "Importing Copilot Agent Files" but the document notes these work with all engines. Renaming to "Agent Files" and clarifying engine behavior differences would help Claude users.
• Issue 5: No "Quick comparison of engines" guide. A Claude Code user wondering "is Claude a fully-supported engine or just an afterthought?" has to scan multiple documents to piece together feature parity.
• Issue 6: docs/src/content/docs/reference/faq.md:333 — FAQ for creating workflows says: "AI-assisted authoring using /agent agentic-workflows create in GitHub Copilot Chat" without mentioning Claude Code as an AI-assisted authoring option.
• Issue 7: The gh aw init tip in creating-workflows.mdx:103 references running init to "configure your repository to make the agent more effective" without explaining which agent or why. Claude Code users may not realize this improves Claude Code's ability to author workflows.

---

Engine Comparison Analysis

Available Engines

Based on my review, gh-aw supports these engines:

• engine: copilot — Comprehensive documentation, video guides, troubleshooting section, default engine
• engine: claude — Good setup docs, 34 example workflows, clear auth instructions
• engine: codex — Basic setup docs, 11 example workflows, limited troubleshooting
• engine: custom — Mentioned in FAQ, minimal docs, no complete guide

Documentation Quality by Engine

Engine	Setup Docs	Examples	Auth Docs	Overall Score
Copilot	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
Claude	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
Codex	⭐⭐⭐	⭐⭐	⭐⭐⭐	⭐⭐⭐
Custom	⭐⭐	⭐	N/A	⭐⭐

Rating Scale: ⭐⭐⭐⭐⭐ (Excellent) to ⭐ (Poor/Missing)

---

Tool Availability Analysis

Tools Review

Engine-Agnostic Tools:

• github: (all toolsets) — works with all engines
• bash: — works with all engines
• edit: — works with all engines
• playwright: — works with all engines
• cache-memory: — works with all engines
• repo-memory: — works with all engines
• agentic-workflows: — works with all engines
• Custom mcp-servers: — works with all engines

Engine-Specific Tools:

• web-search: — engine-dependent; tools.md notes some engines require MCP servers, but doesn't specify which
• assign-to-agent safe output — Copilot coding agent only (clearly documented in auth.mdx)

Unclear/Undocumented:

• Whether web-search: works natively with Claude or requires the Tavily MCP server
• Whether engine: codex needs GH_AW_GITHUB_TOKEN for GitHub MCP (documented) but whether engine: claude also needs it (not explicitly stated)

---

Authentication Requirements

Current Documentation

Quick Start guide covers authentication for:

• ✅ Copilot (detailed instructions, video guide, troubleshooting)
• ✅ Claude (adequate instructions, link to API key creation)
• ✅ Codex (adequate instructions)
• ❌ Custom (not documented)

Missing for Claude Users

• No link to Anthropic console to create API keys (the URL `(platform.claude.com/redacted) points to documentation rather than the API key creation page directly)
• No note about Claude API key tiers or usage limits
• No guidance on which Claude model is used by default

Secret Names

• Copilot: COPILOT_GITHUB_TOKEN (fully documented with video)
• Claude: ANTHROPIC_API_KEY (documented, broken "see also" link)
• Codex: OPENAI_API_KEY (documented, broken "see also" link)
• Optional: GH_AW_GITHUB_TOKEN, GH_AW_GITHUB_MCP_SERVER_TOKEN, GH_AW_PROJECT_GITHUB_TOKEN, GH_AW_AGENT_TOKEN

---

Example Workflow Analysis

Workflow Count by Engine

Engine: copilot - 80 workflows found  (50.6%)
Engine: claude  - 34 workflows found  (21.5%)
Engine: codex   - 11 workflows found  ( 7.0%)
Engine: (none/default copilot) - 21   (13.3%)
Other/mixed     - ~12 workflows        ( 7.6%)
Total: 158 workflows

Quality of Examples

Copilot Examples:
80 real-world example workflows demonstrate a wide variety of use cases. These serve as excellent templates.

Claude Examples:
34 examples exist, providing solid reference material for Claude users. Coverage is sufficient for understanding how to use Claude engine for typical tasks. A notable gap: there are no Claude-specific examples demonstrating Claude-unique capabilities (long context, advanced reasoning on large codebases).

---

Recommended Actions

Priority 1: Critical Documentation Fixes

1. Fix broken link syntax in auth.mdx — Lines 113 and 131 contain broken markdown link syntax. Claude and Codex users following auth instructions can't click through to additional MCP configuration. File: docs/src/content/docs/reference/auth.mdx

2. Fix contradictory model default comment in engines.md — Line 88 shows model: gpt-5 # defaults to claude-sonnet-4. This contradicts itself. Clarify the actual default per engine. File: docs/src/content/docs/reference/engines.md:87-88

3. Clarify web-search: engine support — Add a note to tools.md and web-search.md specifying which engines have native web search vs. requiring an MCP server. File: docs/src/content/docs/reference/tools.md, docs/src/content/docs/guides/web-search.md

Priority 2: Major Improvements

1. Update gh aw init CLI description — Remove "Copilot instructions" language or clarify it means "general agent instructions including Copilot format." File: docs/src/content/docs/setup/cli.md:120

2. Update architecture diagrams — Replace "Copilot CLI" labels with engine-agnostic labels in the AWF and MCP Gateway diagrams. File: docs/src/content/docs/introduction/architecture.mdx:177,248

3. Add non-Copilot alternative to web-based workflow creation — The creating-workflows.mdx Copilot web UI section should include a callout directing Claude users to the terminal approach. File: docs/src/content/docs/setup/creating-workflows.mdx

4. Add Claude-specific troubleshooting — Add a section covering common Claude engine issues (invalid API key, rate limiting, model selection) parallel to the existing Copilot troubleshooting sections. File: docs/src/content/docs/troubleshooting/common-issues.md

Priority 3: Nice-to-Have Enhancements

1. Create "Using Claude Code for Workflow Authoring" guide — A companion to custom-agent-for-aw.mdx showing how to use Claude Code CLI to create and maintain gh-aw workflows.

2. Add engine quick-comparison section — A "Which engine should I use?" guide comparing Copilot, Claude, and Codex with honest trade-offs, costs, and unique strengths.

3. Update FAQ — The AI-assisted authoring FAQ answer only mentions Copilot Chat. Add Claude Code as an AI-assisted authoring option.

---

Positive Findings

What Works Well

• ✅ Quick Start prerequisites clearly lists Claude as a first-class option alongside Copilot
• ✅ gh aw add-wizard interactively selects engine and sets up appropriate secrets — excellent UX for non-Copilot users
• ✅ docs/src/content/docs/reference/engines.md has a well-structured, dedicated Claude section
• ✅ docs/src/content/docs/reference/auth.mdx clearly documents ANTHROPIC_API_KEY with setup steps
• ✅ 34 Claude engine example workflows provide solid reference material
• ✅ gh aw secrets bootstrap --engine claude works for Claude users
• ✅ All core tools (github, bash, edit, playwright, MCP servers) are engine-agnostic
• ✅ how-they-work.mdx correctly states all three engines upfront without Copilot bias
• ✅ FAQ covers all engines fairly (costs, data processing, model switching)
• ✅ secrets bootstrap auto-detects engines from workflow files — smart, engine-agnostic behavior

---

Conclusion

Can Claude Code Users Successfully Adopt gh-aw?

Answer: Yes, with minor friction.

Reasoning: The core documentation path (Quick Start → Engines → Auth → Compile → Run) is complete and accurate for Claude Code users. The Quick Start explicitly lists Claude as a supported engine, authentication instructions are clear, and there are 34 real-world Claude workflow examples. A motivated developer with Claude API access can get gh-aw running in under 30 minutes following the Quick Start guide.

The friction comes from Copilot-centric assumptions in peripheral documentation: the primary AI-assisted authoring workflow is Copilot-only, several architecture diagrams show only Copilot, and the CLI init description mentions "Copilot instructions" without clarification. These create doubt and confusion but don't block adoption.

Overall Assessment Score: 7/10

Breakdown:

• Clarity for non-Copilot users: 7/10
• Claude engine documentation: 8/10
• Alternative approaches provided: 6/10
• Engine parity in examples/docs: 7/10

Next Steps

1. Fix the two broken link syntax issues in auth.mdx (quick win, high impact)
2. Update architecture diagrams to remove Copilot CLI branding (medium effort, removes confusion)
3. Add Claude-specific troubleshooting entries (medium effort, helps unblocking Claude users)
4. Clarify gh aw init description (trivial fix)
5. Consider creating a "Using Claude Code for Workflow Authoring" guide as a companion to the Copilot authoring guide (larger effort, high value for Claude Code users)

---

Appendix: Files Reviewed

Complete List of Documentation Files Analyzed

• README.md
• docs/src/content/docs/setup/quick-start.mdx
• docs/src/content/docs/setup/creating-workflows.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/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/custom-agent-for-aw.mdx
• docs/src/content/docs/setup/cli.md
• docs/src/content/docs/guides/web-search.md
• docs/src/content/docs/troubleshooting/common-issues.md
• .github/workflows/*.md (158 workflow files analyzed by engine)

---

Report Generated: 22265611606
Workflow: claude-code-user-docs-review
Engine Used: claude (eating our own dog food! 🐕)

AI generated by Claude Code User Documentation Review

• expires on Feb 28, 2026, 10:36 PM UTC