Workflow Structure

Each workflow consists of:

1. YAML Frontmatter: Configuration options wrapped in ---. See Frontmatter for details.
2. Markdown: Natural language instructions for the AI. See Markdown.

For example:

---
on:
  issues:
    types: [opened]

permissions:
  issues: write

tools:
  github:
    toolsets: [issues]
---

# Workflow Description

Read the issue #${{ github.event.issue.number }}. Add a comment to the issue listing useful resources and links.

File Organization

Agentic workflows are stored in the .github/workflows folder as Markdown files (*.md) and they are compiled to GitHub Actions Workflows files (*.lock.yml)

.github/
└── workflows/
  ├── ci-doctor.md # Agentic Workflow
  └── ci-doctor.lock.yml # Compiled GitHub Actions Workflow

When you run the compile command you generate the lock file.

gh aw compile

Editing Workflows

Tip

The markdown body is loaded at runtime and can be edited directly on GitHub.com without recompilation. Only frontmatter changes require recompilation.

See Editing Workflows for complete guidance on when recompilation is needed.

Best Practices

• Use descriptive names: issue-responder.md, pr-reviewer.md
• Follow kebab-case convention: weekly-summary.md
• Avoid spaces and special characters
• Commit source files: Always commit .md files
• Commit generated files: Also commit .lock.yml files for transparency

Related Documentation

• Editing Workflows - When to recompile vs edit directly
• Frontmatter - Configuration options for workflows
• Markdown - The main markdown content of workflows
• Imports - Modularizing workflows with includes
• CLI Commands - CLI commands for workflow management
• MCPs - Model Context Protocol configuration