[claude-code-user-docs-review] 🔍 Claude Code User Documentation Review - 2026-04-11 #25812
Closed
Replies: 1 comment
-
|
This discussion has been marked as outdated by Claude Code User Documentation Review. A newer discussion is available at Discussion #25904. |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
-
This is a daily automated review of the gh-aw documentation from the perspective of a Claude Code user who does not use GitHub Copilot.
Executive Summary
The gh-aw documentation is reasonably accessible to Claude Code users. There are no critical blockers preventing adoption — the Quick Start guide names Claude as a supported engine, the authentication reference covers
ANTHROPIC_API_KEYclearly, and 53 of 187 workflow examples useengine: claude. The core setup path (install CLI →gh aw add-wizard→ select Claude engine → set secret → run) works end-to-end without Copilot.However, 7 persistent documentation issues remain unfixed across 3–11 consecutive review days, creating friction for Claude users. The most visible gap is the
creating-workflows.mdxauthoring guide, which gates the GitHub web interface path exclusively behind Copilot with no alternative path for Claude users. A minor positive today: the repository's first Gemini workflow (smoke-gemini.md) was added.Key Finding: Claude Code users can successfully adopt gh-aw. Score: 7.5/10 (up 0.5 from yesterday's 7.0 due to the new Gemini workflow signal).
Persona Context
Review conducted as a developer who:
Question 1: Onboarding Experience
Can a Claude Code user understand and get started with gh-aw?
Yes — with some friction. The Quick Start guide (
docs/src/content/docs/setup/quick-start.mdx) includes Claude explicitly in prerequisites and in the interactiveadd-wizardstep:The
add-wizardsetup step (Step 2) explains all three engine secrets:COPILOT_GITHUB_TOKEN,ANTHROPIC_API_KEY, orOPENAI_API_KEY. The guide is balanced at the top level.Specific Issues Found:
quick-start.mdx:29— Prerequisites list only three engines: Copilot, Anthropic Claude, and OpenAI Codex. Gemini is absent, even though the engines reference page documents it fully as a 4th engine.how-they-work.mdx:26— States "Workflows support GitHub Copilot (default), Claude by Anthropic, and Codex." Gemini is absent here too (persistent, day 5).creating-workflows.mdx:21–24— 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 alternative path exists for Claude Code users in this section.Recommended Fixes:
quick-start.mdxprerequisites line (simple one-liner addition).how-they-work.mdx:26to include "Gemini" in the engine list.creating-workflows.mdxunder the GitHub Web Interface section, directing Claude Code users to the CLI path instead.Question 2: Inaccessible Features for Non-Copilot Users
What features or steps don't work without Copilot?
Features That Require Copilot (intentional, but should be labeled more clearly):
gh aw initdispatcher agent registers a custom agent in Copilot Chat ongithub.comand the GitHub mobile app. This is documented as a requirement for the web authoring experience, with no Claude Code equivalent path described. (creating-workflows.mdx:104–125)/agent agentic-workflowsCopilot Chat command — Copilot-specific feature for in-browser workflow creation.engine.agentcustom agent files — Copilot-only feature per the engine comparison table. Well-documented.max-continuationsautopilot mode — Copilot-only feature. Well-documented.assign-to-agentsafe output — Assigns GitHub Copilot coding agent to issues/PRs. This is a GitHub product feature, not just a CLI feature.Features That Work Without Copilot (engine-agnostic):
gh awCLI commands (compile,run,logs,audit,status, etc.)create-issue,add-comment,create-pull-request, etc.)edit,bash,github,web-fetch,playwright,cache-memory,repo-memory,qmdadd-wizardinteractive setupMissing Documentation:
add-wizardwhich is interactive, but a walkthrough specifically for Claude users would reduce uncertainty.creating-workflows.mdxsection ongh aw initshould note that the dispatcher agent is only relevant for Copilot Chat users; CLI users don't need it.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:181— AWF network diagram labels the agent container specifically as "Copilot CLI" in the Mermaid diagram node. A Claude Code user reading this would wonder if the security firewall only applies to Copilot:Should read:
AGENT["AI Agent CLI\n(Copilot/Claude/Codex/Gemini)"](persistent, day 8).docs/src/content/docs/setup/creating-workflows.mdx:21— "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." No equivalent path documented for Claude Code users (persistent, day 3).docs/src/content/docs/setup/creating-workflows.mdx:104— "Runninggh aw initis required to enable the authoring experience in the GitHub code agent." — Followed immediately by "using the Copilot coding agent." Claude Code users could be confused about whethergh aw initis required for them at all (it's optional for CLI users).docs/src/content/docs/setup/cli.md—secrets bootstrap --enginedocuments only(copilot, claude, codex). Gemini is absent (persistent, day 4).Missing Alternative Instructions:
creating-workflows.mdx— pointing togh aw new --engine claudeand the CLI authoring path.creating-workflows.mdxthatgh aw initis useful but not required for CLI users who aren't using the Copilot Chat web authoring feature.Severity-Categorized Findings
🚫 Critical Blockers (Score: 0/10 — None Found)
No critical blockers exist. A Claude Code user can complete the full adoption path without Copilot.
Obstacle 1: GitHub Web Interface Authoring Is Copilot-Only (Persistent — Day 3)
Impact: Claude Code users who prefer browser-based workflow creation have no documented path.
Current State:
creating-workflows.mdx:21reads: "If you have access to GitHub Copilot, you can create and edit Agentic Workflows directly from the Web Interface." The entire web authoring section (50+ lines) describes Copilot-only functionality with no alternative.Why It's Problematic: A Claude Code user reading this section sees only Copilot being referenced and has to scroll down to find that there is a CLI path available.
Suggested Fix: Add an info note or tab at the top of the GitHub Web Interface section: "This path requires GitHub Copilot. Claude Code and Codex users: use the CLI path instead."
Affected Files:
docs/src/content/docs/setup/creating-workflows.mdxlines 20–60.Obstacle 2: Architecture Diagram Labels Agent as "Copilot CLI" (Persistent — Day 8)
Impact: Creates a misleading impression that the AWF security model is Copilot-specific.
Current State:
architecture.mdx:181— Mermaid diagram node:This appears inside the "AI Agent Process" subgraph of the AWF network diagram. The label is specific to Copilot even though the security architecture applies equally to all engines.
Why It's Problematic: A Claude Code user studying the security architecture diagram would see "Copilot CLI" where they should see a generic agent — potentially leading them to believe the firewall/isolation model doesn't apply to their Claude-based workflows.
Suggested Fix: Rename the diagram node to
AGENT["AI Agent CLI\n(Copilot/Claude/Codex/Gemini)"].Affected Files:
docs/src/content/docs/introduction/architecture.mdxline 181.Obstacle 3: Gemini Consistently Absent From Multiple Key Docs (Persistent — Day 4–11)
Impact: Users trying to evaluate or adopt the Gemini engine face a fragmented experience.
Current State: Gemini is fully documented in
engines.mdandauth.mdx, but is missing from:quick-start.mdx:29— Prerequisites listhow-they-work.mdx:26— Engine listcli.md—secrets bootstrap --engineoptions(copilot, claude, codex)— nogeminiWhy It's Problematic: A Gemini user reading the Quick Start would not see their engine listed, potentially concluding it's not supported. The first Gemini workflow (
smoke-gemini.md) was added today, making this gap more visible.Suggested Fix: Add Gemini to all three locations. In
cli.md, update the--engineoption description to(copilot, claude, codex, gemini).Affected Files:
quick-start.mdx,how-they-work.mdx,cli.md.💡 Minor Confusion Points (Score: 6/10)
ANTHROPIC_API_KEY setup URL suboptimal —
auth.mdx:109links to(platform.claude.com/redacted) (a docs landing page) rather than directly tohttps://console.anthropic.com/settings/keys` (the API key creation page). Persistent for 11 days. File:docs/src/content/docs/reference/auth.mdx.Claude URL in engines table is stale —
engines.md:17links tohttps://www.anthropic.com/index/claude. The current canonical URL ishttps://www.anthropic.com/claude. Persistent for 11 days. File:docs/src/content/docs/reference/engines.md.how-they-work.mdx:26says Copilot is "default" without noting this just meansengine:can be omitted — Claude users don't need to do anything special beyond addingengine: claude. File:docs/src/content/docs/introduction/how-they-work.mdx.gh aw initdescribed as "required" increating-workflows.mdx:104— but the requirement is only for the Copilot Chat web-authoring experience. CLI users (like Claude Code users) can skip it. The wording is confusing. File:docs/src/content/docs/setup/creating-workflows.mdx.Engine Comparison Analysis
Available Engines
engine:copilotclaudecodexgeminiRating Scale: ⭐⭐⭐⭐⭐ (Excellent) to ⭐ (Poor/Missing)
Notes:
CLAUDE_CODE_OAUTH_TOKENnot being supported — a common gotcha for Claude Code users.smoke-gemini.mdadded today).Tool Availability Analysis
Engine-Agnostic Tools (work with all engines):
edit:— File editingbash:— Shell commandsgithub:— GitHub API operationsweb-fetch:— Fetch web contentplaywright:— Browser automationcache-memory:— Persistent memoryrepo-memory:— Repository memoryagentic-workflows:— Workflow introspectionqmd:— Documentation search (experimental)Engine-Specific Tools:
web-search:— Works natively in Codex; requires third-party MCP server for Copilot/Claude/Geminimax-turns:— Claude onlymax-continuations:— Copilot onlyengine.agent:— Copilot custom agent files onlyUnclear/Undocumented:
tools.md.Authentication Requirements
Current Documentation Coverage
COPILOT_GITHUB_TOKENANTHROPIC_API_KEYOPENAI_API_KEYGEMINI_API_KEYMissing for Claude Users
ANTHROPIC_API_KEYsetup URL (platform.claude.com/docs/en/get-started) is one extra click away from the actual key creation UI. A direct link toconsole.anthropic.com/settings/keyswould match the quality of the Copilot and Gemini setup links.CLAUDE_CODE_OAUTH_TOKENnote is clear and helpful — this is a well-done user experience detail.Example Workflow Analysis
Workflow Count by Engine (Today vs. Previous)
*Previous counts used simpler grep pattern; today's uses extended regex matching both
engine: claude(inline) andengine:\n id: claude(block-style) declarations.Quality of Examples
Claude Examples (53 workflows): Rich and varied. Includes
scout.md(deep research with Tavily/arXiv MCP),audit-workflows.md(workflow introspection),deep-report.md(analytical report generation), andgo-fan.md(code improvement). Claude-specific features likemax-turnsare used in examples.Gemini Examples (1 workflow):
smoke-gemini.mdis a smoke test added today — the first ever Gemini workflow. It demonstrates basic Gemini engine usage with standard tools. More real-world examples needed.Recommended Actions
Priority 1: Critical Documentation Fixes
Fix ANTHROPIC_API_KEY setup URL — Change
auth.mdx:109from(platform.claude.com/redacted) tohttps://console.anthropic.com/settings/keys`. One-line change. Persistent for 11 days. File:docs/src/content/docs/reference/auth.mdx.Rename "Copilot CLI" diagram node — In
architecture.mdx:181, changeCOPILOT["Copilot CLI"]to a generic label. Persistent for 8 days. File:docs/src/content/docs/introduction/architecture.mdx.Add Gemini to Quick Start prerequisites —
quick-start.mdx:29: Add `[Google Gemini]((aistudio.google.com/redacted) to the AI Account prerequisite bullet. Persistent for 11 days.Priority 2: Major Improvements
Add Claude Code alternative to web interface authoring — In
creating-workflows.mdx, add a brief note directing non-Copilot users togh aw new --engine claudeand the CLI path. Would eliminate the most visible Copilot-gate in user-facing docs. Persistent for 3 days.Update
how-they-work.mdx:26to include Gemini — Change "GitHub Copilot (default), Claude by Anthropic, and Codex" to "GitHub Copilot (default), Claude by Anthropic, Codex, and Gemini". Persistent for 5 days.Add
geminitosecrets bootstrap --enginedocs —cli.mdoptions description:(copilot, claude, codex)→(copilot, claude, codex, gemini). Persistent for 4 days.Priority 3: Nice-to-Have Enhancements
gh aw initis optional for CLI users —creating-workflows.mdx:104should note thatgh aw initis required only for Copilot Chat web authoring; CLI users can skip it.engines.md:17:anthropic.com/index/claude→anthropic.com/claude.Positive Findings
What Works Well for Claude Code Users
add-wizardstep cover all engines.auth.mdxhas full setup instructions and importantly calls out thatCLAUDE_CODE_OAUTH_TOKENis not supported — a critical note for Claude Code users.gh aw new --engine claude: Injects the correct engine field into frontmatter templates automatically.secrets bootstrap --engine claude: CLI supports engine-specific secret validation.ANTHROPIC_BASE_URLand custom API routing are well-covered inengines.md.max-turnsis a Claude-only feature, clearly documented with examples.engines.mdhas a clear feature-parity table across all four engines.smoke-gemini.mdsignals growing multi-engine momentum.Conclusion
Can Claude Code Users Successfully Adopt gh-aw?
Answer: Yes — with minor effort.
The core adoption path works without any Copilot dependency. A Claude Code user can run
gh extension install github/gh-aw, executegh aw add-wizard, select Claude as their engine, add theirANTHROPIC_API_KEYsecret, and have their first workflow running within the Quick Start's estimated 10 minutes. The authentication docs, engine comparison table, and 53 Claude workflow examples provide solid coverage.The friction points are primarily around the authoring experience: the GitHub web interface path is Copilot-only, and
gh aw init's description implies it's universally required when it's mainly relevant for Copilot Chat users. These are documentation clarity issues, not adoption blockers.The 7 persistent issues (now at 3–11 days each without resolution) suggest these may need prioritized attention. The most impactful fix would be clarifying the
creating-workflows.mdxauthoring guide for non-Copilot users.Overall Assessment Score: 7.5/10
Appendix: Files Reviewed
Complete List of Documentation Files Analyzed
README.mddocs/src/content/docs/setup/quick-start.mdxdocs/src/content/docs/introduction/how-they-work.mdxdocs/src/content/docs/introduction/architecture.mdxdocs/src/content/docs/reference/tools.mddocs/src/content/docs/setup/cli.mddocs/src/content/docs/reference/engines.mddocs/src/content/docs/reference/auth.mdxdocs/src/content/docs/reference/frontmatter.mddocs/src/content/docs/reference/faq.mddocs/src/content/docs/setup/creating-workflows.mdx.github/workflows/(187 workflow files, engine distribution analyzed)References:
Report Generated: §24283197609 · Workflow:
claude-code-user-docs-review· Engine:claude(eating our own dog food 🐕)Beta Was this translation helpful? Give feedback.
All reactions