From a6d04e8a2df6e1e4aa44fbd64882eb8e2f01e41b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Jul 2026 18:11:06 +0000
Subject: [PATCH 1/4] Initial plan


From 6031faf23035306955dc0ded9716b5e0728f2b58 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Jul 2026 18:19:04 +0000
Subject: [PATCH 2/4] docs: document Claude Code workaround for
 agentic-workflows create

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/src/content/docs/engines/claude.md       | 19 +++++++++++++++++++
 docs/src/content/docs/reference/faq.md        | 13 ++++++++++++-
 .../content/docs/setup/creating-workflows.mdx |  3 +++
 3 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/docs/src/content/docs/engines/claude.md b/docs/src/content/docs/engines/claude.md
index 4bb94fe6f66..7ee2568fd23 100644
--- a/docs/src/content/docs/engines/claude.md
+++ b/docs/src/content/docs/engines/claude.md
@@ -36,6 +36,25 @@ Analyze the repository and create a concise daily status report covering:
 - Upcoming work items
 ```
 
+## Guided workflow authoring with Claude Code
+
+Claude Code users can use `create.md` to author agentic workflows with interactive guidance — no Copilot subscription required.
+
+In your terminal, start Claude Code in your repository and run:
+
+```text wrap
+Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md
+
+The purpose of the workflow is <describe your automation goal here>.
+```
+
+The agent fetches `create.md`, installs the `gh aw` CLI if needed, guides you through trigger selection, tools, safe outputs, and permissions, then generates `.github/workflows/<name>.md` and compiles it to a `.lock.yml`.
+
+After the files are committed, set `engine: claude` in your workflow's frontmatter (if not already set) and add your `ANTHROPIC_API_KEY` as a repository secret.
+
+> [!NOTE]
+> The `agentic-workflows create` Copilot Chat skill (enabled by `gh aw init`) requires a GitHub Copilot subscription. For Claude Code-only setups, the `create.md` prompt above is the equivalent guided flow.
+
 ## When to choose gh-aw vs. anthropics/claude-code-action
 
 Choose gh-aw when the workflow should be defined in Markdown, run behind gh-aw sandboxing, switch engines without rewriting the workflow, or use safe outputs for validated GitHub writes. Choose [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action) when the main goal is native Claude-driven PR assistance around comment and mention workflows.
diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md
index fce964c5a5b..2b07676ffb8 100644
--- a/docs/src/content/docs/reference/faq.md
+++ b/docs/src/content/docs/reference/faq.md
@@ -586,7 +586,18 @@ One workflow is simpler to maintain; multiple workflows give better separation o
 
 ### Should I create agentic workflows by hand editing or using AI?
 
-Both work. AI-assisted authoring via `agentic-workflows create` in Copilot Chat gives interactive guidance and best practices; manual editing gives full control for advanced customization. See [Creating Workflows](/gh-aw/setup/creating-workflows/) or [Frontmatter Reference](/gh-aw/reference/frontmatter/).
+Both work. AI-assisted authoring gives interactive guidance and best practices; manual editing gives full control for advanced customization.
+
+- **GitHub Copilot users**: after running `gh aw init`, use `agentic-workflows create` in Copilot Chat on github.com or the GitHub mobile app.
+- **Claude Code and other CLI agent users**: use the `create.md` prompt directly — no Copilot subscription required:
+
+  ```text wrap
+  Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md
+
+  The purpose of the workflow is <your goal here>.
+  ```
+
+See [Creating Workflows](/gh-aw/setup/creating-workflows/) or [Frontmatter Reference](/gh-aw/reference/frontmatter/).
 
 ### Can the agent use an existing branch specified at runtime (e.g., from a Jira issue)?
 
diff --git a/docs/src/content/docs/setup/creating-workflows.mdx b/docs/src/content/docs/setup/creating-workflows.mdx
index 6a9dec0f9ce..c2451146317 100644
--- a/docs/src/content/docs/setup/creating-workflows.mdx
+++ b/docs/src/content/docs/setup/creating-workflows.mdx
@@ -132,6 +132,9 @@ Once initialized, you and your team can create and edit workflows by opening a C
 agentic-workflows Create a new workflow that...
 ```
 
+> [!NOTE]
+> The `agentic-workflows` Copilot Chat skill requires a GitHub Copilot subscription. If you use Claude Code or another CLI coding agent without Copilot access, use the `create.md` approach in the [VSCode/Claude/Codex/Copilot](#vscodeclaudecodexcopilot) section above — it provides the same guided authoring experience. The `.gitattributes` and VS Code settings configured by `gh aw init` are still useful regardless of engine.
+
 ## Manual Editing
 
 If you prefer to create workflows manually, you can

From 9141f303fe5d946858901e3db5bf4676005baa40 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Jul 2026 18:32:15 +0000
Subject: [PATCH 3/4] docs: add gh aw init --engine claude to Claude Code
 guided-authoring docs

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/src/content/docs/engines/claude.md          | 16 +++++++++++++---
 docs/src/content/docs/reference/faq.md           |  2 +-
 .../content/docs/setup/creating-workflows.mdx    |  2 +-
 3 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/docs/src/content/docs/engines/claude.md b/docs/src/content/docs/engines/claude.md
index 7ee2568fd23..86220807349 100644
--- a/docs/src/content/docs/engines/claude.md
+++ b/docs/src/content/docs/engines/claude.md
@@ -38,9 +38,19 @@ Analyze the repository and create a concise daily status report covering:
 
 ## Guided workflow authoring with Claude Code
 
-Claude Code users can use `create.md` to author agentic workflows with interactive guidance — no Copilot subscription required.
+Claude Code users can initialize the repository and author agentic workflows with interactive guidance — no Copilot subscription required.
 
-In your terminal, start Claude Code in your repository and run:
+### Initialize for Claude
+
+Run `gh aw init --engine claude` to configure the repository. The `--engine claude` flag skips Copilot-specific files (MCP server configuration, Copilot dispatcher skill) and only writes the files useful for any engine: `.gitattributes`, VS Code settings, and the custom agent file.
+
+```bash
+gh aw init --engine claude
+```
+
+### Create a workflow
+
+Start Claude Code in your repository and run:
 
 ```text wrap
 Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md
@@ -53,7 +63,7 @@ The agent fetches `create.md`, installs the `gh aw` CLI if needed, guides you th
 After the files are committed, set `engine: claude` in your workflow's frontmatter (if not already set) and add your `ANTHROPIC_API_KEY` as a repository secret.
 
 > [!NOTE]
-> The `agentic-workflows create` Copilot Chat skill (enabled by `gh aw init`) requires a GitHub Copilot subscription. For Claude Code-only setups, the `create.md` prompt above is the equivalent guided flow.
+> The `agentic-workflows create` Copilot Chat skill (enabled by `gh aw init` without `--engine`) requires a GitHub Copilot subscription. For Claude Code-only setups, `gh aw init --engine claude` plus the `create.md` prompt above is the equivalent guided flow.
 
 ## When to choose gh-aw vs. anthropics/claude-code-action
 
diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md
index 2b07676ffb8..b792c4a2fa4 100644
--- a/docs/src/content/docs/reference/faq.md
+++ b/docs/src/content/docs/reference/faq.md
@@ -589,7 +589,7 @@ One workflow is simpler to maintain; multiple workflows give better separation o
 Both work. AI-assisted authoring gives interactive guidance and best practices; manual editing gives full control for advanced customization.
 
 - **GitHub Copilot users**: after running `gh aw init`, use `agentic-workflows create` in Copilot Chat on github.com or the GitHub mobile app.
-- **Claude Code and other CLI agent users**: use the `create.md` prompt directly — no Copilot subscription required:
+- **Claude Code and other CLI agent users**: run `gh aw init --engine claude` to initialize (skips Copilot-specific files), then use the `create.md` prompt directly — no Copilot subscription required:
 
   ```text wrap
   Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md
diff --git a/docs/src/content/docs/setup/creating-workflows.mdx b/docs/src/content/docs/setup/creating-workflows.mdx
index c2451146317..9633bb76a3e 100644
--- a/docs/src/content/docs/setup/creating-workflows.mdx
+++ b/docs/src/content/docs/setup/creating-workflows.mdx
@@ -133,7 +133,7 @@ agentic-workflows Create a new workflow that...
 ```
 
 > [!NOTE]
-> The `agentic-workflows` Copilot Chat skill requires a GitHub Copilot subscription. If you use Claude Code or another CLI coding agent without Copilot access, use the `create.md` approach in the [VSCode/Claude/Codex/Copilot](#vscodeclaudecodexcopilot) section above — it provides the same guided authoring experience. The `.gitattributes` and VS Code settings configured by `gh aw init` are still useful regardless of engine.
+> The `agentic-workflows` Copilot Chat skill requires a GitHub Copilot subscription. If you use Claude Code or another CLI coding agent without Copilot access, run `gh aw init --engine claude` instead — it skips the Copilot-specific MCP and skill files while still writing `.gitattributes`, VS Code settings, and the custom agent file. Then use the `create.md` approach in the [VSCode/Claude/Codex/Copilot](#vscodeclaudecodexcopilot) section above for guided workflow authoring.
 
 ## Manual Editing
 

From a7e668fea7ddf2217d9983bf76d67e904060ebc7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Jul 2026 18:42:06 +0000
Subject: [PATCH 4/4] docs: add gh aw init --engine to codex, gemini, and
 copilot engine pages

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/src/content/docs/engines/codex.md   | 8 ++++++++
 docs/src/content/docs/engines/copilot.md | 8 ++++++++
 docs/src/content/docs/engines/gemini.md  | 8 ++++++++
 3 files changed, 24 insertions(+)

diff --git a/docs/src/content/docs/engines/codex.md b/docs/src/content/docs/engines/codex.md
index 30e732df9d8..a15fe9080c0 100644
--- a/docs/src/content/docs/engines/codex.md
+++ b/docs/src/content/docs/engines/codex.md
@@ -9,6 +9,14 @@ OpenAI Codex is OpenAI's coding-focused agent runtime for repository work. gh-aw
 
 Set `engine: codex` and provide `OPENAI_API_KEY`. `CODEX_API_KEY` is also accepted and takes precedence when both are present. See [OpenAI authentication](/gh-aw/reference/auth/#openai_api_key) for the supported configuration.
 
+### Initialize the repository
+
+Run `gh aw init --engine codex` to configure the repository. The `--engine codex` flag skips Copilot-specific files (MCP server configuration, Copilot dispatcher skill) and writes only the files useful for any engine: `.gitattributes`, VS Code settings, and the custom agent file.
+
+```bash
+gh aw init --engine codex
+```
+
 ```aw wrap title=".github/workflows/daily-status.md"
 ---
 on:
diff --git a/docs/src/content/docs/engines/copilot.md b/docs/src/content/docs/engines/copilot.md
index 08ec6ccc7c8..21624c6ada6 100644
--- a/docs/src/content/docs/engines/copilot.md
+++ b/docs/src/content/docs/engines/copilot.md
@@ -9,6 +9,14 @@ GitHub Copilot is the default gh-aw engine and runs GitHub Copilot agents inside
 
 Set `engine: copilot` or omit `engine:` because Copilot is the default. For organization-billed usage, grant `copilot-requests: write`; otherwise provide a `COPILOT_GITHUB_TOKEN` secret. See [Copilot authentication](/gh-aw/reference/auth/#copilot_github_token) for both paths.
 
+### Initialize the repository
+
+Run `gh aw init` to configure the repository. Copilot is the default engine, so no `--engine` flag is required. This sets up the full Copilot integration: dispatcher skill, MCP server configuration, `.gitattributes`, VS Code settings, and the custom agent file.
+
+```bash
+gh aw init
+```
+
 ```aw wrap title=".github/workflows/daily-status.md"
 ---
 on:
diff --git a/docs/src/content/docs/engines/gemini.md b/docs/src/content/docs/engines/gemini.md
index b0e707aed9f..2ef4340b275 100644
--- a/docs/src/content/docs/engines/gemini.md
+++ b/docs/src/content/docs/engines/gemini.md
@@ -9,6 +9,14 @@ Google Gemini is Google's model family for coding and repository analysis. gh-aw
 
 Set `engine: gemini` and provide `GEMINI_API_KEY`, or configure keyless authentication with Google Workload Identity Federation. See [Gemini authentication](/gh-aw/reference/auth/#gemini_api_key) for the available setup paths.
 
+### Initialize the repository
+
+Run `gh aw init --engine gemini` to configure the repository. The `--engine gemini` flag skips Copilot-specific files (MCP server configuration, Copilot dispatcher skill) and writes only the files useful for any engine: `.gitattributes`, VS Code settings, and the custom agent file.
+
+```bash
+gh aw init --engine gemini
+```
+
 ```aw wrap title=".github/workflows/daily-status.md"
 ---
 on:
