Skip to content
GitHub Agentic Workflows

Include Directives

Include directives allow you to modularize and reuse workflow components across multiple workflows.

Basic Include Syntax

Section titled “Basic Include Syntax”
@include relative/path/to/file.md

Includes files relative to the current markdown file’s location.

Optional Include Syntax

Section titled “Optional Include Syntax”
@include? relative/path/to/file.md

Includes files optionally - if the file doesn’t exist, no error occurs and a friendly informational comment is added to the workflow. The optional file will be watched for changes in gh aw compile --watch mode, so creating the file later will automatically include it.

Section-Specific Includes

Section titled “Section-Specific Includes”
@include filename.md#Section

Includes only a specific section from a markdown file using the section header.

Frontmatter Merging

Section titled “Frontmatter Merging”
  • Only tools: frontmatter is allowed in included files, other entries give a warning.
  • Tool merging: allowed: tools are merged across all included files

Example Tool Merging

Section titled “Example Tool Merging”
# Base workflow
---
tools:
  github:
    allowed: [get_issue]
---


@include shared/extra-tools.md  # Adds more GitHub tools
shared/extra-tools.md
---
tools:
  github:
    allowed: [add_issue_comment, update_issue]
  edit:
---

Result: Final workflow has github.allowed: [get_issue, add_issue_comment, update_issue] and Claude Edit tool.

Include Path Resolution

Section titled “Include Path Resolution”
  • Relative paths: Resolved relative to the including file
  • Nested includes: Included files can include other files
  • Circular protection: System prevents infinite include loops
Section titled “Related Documentation”