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 . +``` + +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/.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 . + ``` + +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: