Workflow Structure

Each workflow has two parts: YAML frontmatter wrapped in --- for configuration, and a markdown body for the agent instructions. See Frontmatter and Markdown for details.

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.

A workflow file may optionally include one or more inline sub-agent definitions after the main markdown body. See Inline Sub-Agents for details.

File Organization

Agentic workflows live in .github/workflows as Markdown files (*.md) and compile to GitHub Actions workflow files (*.lock.yml). Run gh aw compile to generate the lock file.

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

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 kebab-case names such as issue-responder.md or weekly-summary.md, avoid spaces and special characters, and commit both the source .md files and generated .lock.yml files.

Related Documentation

See also Editing Workflows for recompilation guidance, Frontmatter for configuration, Markdown for the body format, Imports for shared content, CLI Commands for workflow management, and MCPs for Model Context Protocol configuration.