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]

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

Lock File Header

Each compiled lock file begins with a machine-readable metadata line followed by a human-readable manifest of its external dependencies:

# gh-aw-metadata: {"schema_version":"v3","frontmatter_hash":"...","strict":true,"agent_id":"copilot"}
#    ___  ...ASCII logo...
# This file was automatically generated by gh-aw. DO NOT EDIT.
# ...
# Secrets used:
#   - COPILOT_GITHUB_TOKEN
#   - GITHUB_TOKEN
#
# Custom actions used:
#   - actions/checkout@de0fac2e... # v6.0.2
#   - actions/upload-artifact@bbbca2... # v4

The gh-aw-metadata line is always first, enabling reliable machine parsing. The Secrets used and Custom actions used sections list all secrets.* references and external uses: dependencies (excluding local ./ refs) found in the compiled workflow, sorted and deduplicated.

Editing Workflows

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 and how to recompile workflows.

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