Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
184 changes: 184 additions & 0 deletions create.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
# Creating Agentic Workflows and Other Actions

This prompt guides you, a coding agent, to create, debug, update or do other actions related to **GitHub Agentic Workflows (gh-aw)** in a repository.

## Step 1: Install GitHub Agentic Workflows CLI Extension

Run the installation script from the main branch of the gh-aw repository:

```bash
curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash
```

**What this does**: Downloads and installs the gh-aw binary to `~/.local/share/gh/extensions/gh-aw/`

**Verify installation**:

```bash
gh aw version
```


If already installed, you can update to the latest version by running

```bash
gh extension upgrade gh-aw
```

Comment on lines +22 to +27

Copilot AI Feb 3, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The standalone installer (curl ... | bash) installs a binary into the extensions directory but does not create a git-based extension checkout, so gh extension upgrade gh-aw will generally not work afterwards. Recommend either (a) using gh extension install github/gh-aw as the primary install path and keeping the curl installer as a fallback, or (b) for standalone installs, instruct users to re-run the installer to update (optionally pinned to a version).

Suggested change
If already installed, you can update to the latest version by running
```bash
gh extension upgrade gh-aw
```
If already installed, you can update to the latest version as follows:
- If you installed via `gh extension install github/gh-aw`, run:
```bash
gh extension upgrade gh-aw
  • If you installed via the standalone script above, re-run the same install command:

    curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash

Copilot uses AI. Check for mistakes.
You should see version information displayed. If you encounter an error, check that:

- GitHub CLI (`gh`) is installed and authenticated
- The installation script completed without errors
- `~/.local/share/gh/extensions` is in your PATH

Copilot AI Feb 3, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

gh does not require ~/.local/share/gh/extensions to be in PATH to run gh aw ...; it discovers extensions from its extensions directory. This bullet is misleading—either remove it or clarify that adding to PATH is only needed if you want to run the gh-aw binary directly (not via gh aw).

Suggested change
- `~/.local/share/gh/extensions` is in your PATH
- `~/.local/share/gh/extensions` is in your PATH only if you want to run the `gh-aw` binary directly (not required for using `gh aw ...`, which `gh` discovers automatically)

Copilot uses AI. Check for mistakes.

## Step 2: Create the Workflow or do Other Actions

Follow the instructions in the appropriate prompt based on the user's request.

### Create New Workflow

**Load when**: User wants to create a new workflow from scratch, add automation, or design a workflow that doesn't exist yet

**Prompt file**: `https://github.com/github/gh-aw/blob/main/.github/aw/create-agentic-workflow.md`

Comment on lines +40 to +43

Copilot AI Feb 3, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The prompt link uses a github.com/.../blob/... URL, which returns HTML. For an agent that needs to “fetch and read” the prompt content, use a raw URL (raw.githubusercontent.com) or add ?plain=1 to ensure the fetched content is the markdown source, not the GitHub page wrapper.

This issue also appears in the following locations of the same file:

  • line 52
  • line 64
  • line 76
  • line 88

Copilot uses AI. Check for mistakes.
**Use cases**:

- "Create a workflow that triages issues"
- "I need a workflow to label pull requests"
- "Design a weekly research automation"

### Update Existing Workflow

**Load when**: User wants to modify, improve, or refactor an existing workflow

**Prompt file**: `https://github.com/github/gh-aw/blob/main/.github/aw/update-agentic-workflow.md`

**Use cases**:

- "Add web-fetch tool to the issue-classifier workflow"
- "Update the PR reviewer to use discussions instead of issues"
- "Improve the prompt for the weekly-research workflow"

### Debug Workflow

**Load when**: User needs to investigate, audit, debug, or understand a workflow, troubleshoot issues, analyze logs, or fix errors

**Prompt file**: `https://github.com/github/gh-aw/blob/main/.github/aw/debug-agentic-workflow.md`

**Use cases**:

- "Why is this workflow failing?"
- "Analyze the logs for workflow X"
- "Investigate missing tool calls in run #12345"

### Upgrade Agentic Workflows

**Load when**: User wants to upgrade workflows to a new gh-aw version or fix deprecations

**Prompt file**: `https://github.com/github/gh-aw/blob/main/.github/aw/upgrade-agentic-workflows.md`

**Use cases**:

- "Upgrade all workflows to the latest version"
- "Fix deprecated fields in workflows"
- "Apply breaking changes from the new release"

### Create Shared Agentic Workflow

**Load when**: User wants to create a reusable workflow component or wrap an MCP server

**Prompt file**: `https://github.com/github/gh-aw/blob/main/.github/aw/create-shared-agentic-workflow.md`

**Use cases**:

- "Create a shared component for Notion integration"
- "Wrap the Slack MCP server as a reusable component"
- "Design a shared workflow for database queries"

If you need to clarify requirements or discuss options, and you are working in an interactive agent chat system, do so interactively with the user. If running non-interactively, make reasonable assumptions based on the repository context.

## Step 3: Review Changes

Check what files were changed or created:

```bash
git status
```

If creating workflows, the actual workflow files you created will be under `.github/workflows/`. There should be at least one workflow file and one lock file.

- `.github/workflows/<workflow-name>.md`
- `.github/workflows/<workflow-name>.lock.yml`

Comment on lines +108 to +112

Copilot AI Feb 3, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This implies every workflow change results in both a .md and a .lock.yml, but shared workflow components (and some edit-only changes to the markdown body) may not produce or require a lock file. Consider qualifying this to “for compiled workflows with frontmatter changes” and note that shared components typically don’t have .lock.yml outputs.

Copilot uses AI. Check for mistakes.
In general you do not need to run `gh aw init` as part of your workflow creation. However if you did you may also see:

- `.gitattributes`
- `.github/aw/github-agentic-workflows.md`
- `.github/agents/agentic-workflows.agent.md`
- `.vscode/settings.json`
- `.vscode/mcp.json`
- And several other configuration files

Unless instructed otherwise do NOT commit the changes to ANY files except the gitattributes file and workflow files.

- `.gitattributes`
- `.github/workflows/<workflow-name>.md`
- `.github/workflows/<workflow-name>.lock.yml`

Comment on lines +113 to +127

Copilot AI Feb 3, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section says to not commit any init-generated files (like .github/aw/..., .github/agents/..., .vscode/...). That conflicts with gh aw init being an explicit repo setup mechanism and may leave the repo in a partially-initialized state. Consider rewording to: either don’t run gh aw init (and ensure it didn’t create extra files), or if you did run it intentionally, commit the generated initialization files (or revert them) based on the repo’s desired setup.

Copilot uses AI. Check for mistakes.
## Step 4: Commit and Push Changes

Commit the changes, e.g.

```bash
git add .gitattributes .github/workflows/<workflow-name>.md .github/workflows/<workflow-name>.lock.yml
git commit -m "Initialize repository for GitHub Agentic Workflows"

Copilot AI Feb 3, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example commit message "Initialize repository for GitHub Agentic Workflows" doesn’t match the described change here (adding/editing specific workflow files). Suggest using a workflow-specific message (and reserving “initialize repository” for when gh aw init is actually performed).

Suggested change
git commit -m "Initialize repository for GitHub Agentic Workflows"
git commit -m "Add <workflow-name> GitHub Agentic Workflow"

Copilot uses AI. Check for mistakes.
git push
```

If there is branch protection on the default branch, create a pull request instead and report the link to the pull request.

## Troubleshooting

See the separate guides on troubleshooting common issues.

## Instructions

When a user interacts with you:

1. **Identify the task type** from the user's request
2. **Fetch and read the appropriate prompt**
3. **Follow the loaded prompt's instructions** exactly
4. **If uncertain**, ask clarifying questions to determine the right prompt

## Quick Reference

```bash
# Create a new workflow
gh aw new <workflow-name>

# Compile workflows
gh aw compile [workflow-name]

# Debug workflow runs
gh aw logs [workflow-name]
gh aw audit <run-id>

# Upgrade workflows
gh aw fix --write
gh aw compile --validate
```

## Key Features of gh-aw

- **Natural Language Workflows**: Write workflows in markdown with YAML frontmatter
- **AI Engine Support**: Copilot, Claude, Codex, or custom engines
- **MCP Server Integration**: Connect to Model Context Protocol servers for tools
- **Safe Outputs**: Structured communication between AI and GitHub API
- **Strict Mode**: Security-first validation and sandboxing
- **Shared Components**: Reusable workflow building blocks
- **Repo Memory**: Persistent git-backed storage for agents

## Important Notes

- Workflows must be compiled to `.lock.yml` files before running in GitHub Actions
- Follow security best practices: minimal permissions, explicit network access, no template injection