Skip to content
GitHub Agentic Workflows

Workflow Structure

Workflow File Format

Section titled “Workflow File Format”

Each workflow consists of:

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

The markdown content is where you write natural language instructions for the AI agent.

Create a markdown file in .github/workflows/ with the following structure:

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


permissions:
  issues: write


tools:
  github:
    allowed: [add_issue_comment]
---


# Workflow Description


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

This guide explains how agentic workflows are organized and structured within your repository.

File Organization

Section titled “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/
  ├── weekly-research.md # Agentic Workflow
  └── weekly-research.lock.yml # Compiled GitHub Actions Workflow

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

Terminal window
gh aw compile

Best Practices

Section titled “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
Section titled “Related Documentation”