Markdown

The markdown body is the most important part of your agentic workflow, containing natural language instructions for the AI agent. The markdown follows the frontmatter and is loaded at runtime, allowing you to edit instructions directly on GitHub.com without recompilation. For example:

---
...frontmatter...
---

# Issue Triage

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

Writing Effective Instructions

Write instructions as if explaining the task to a new team member. Be specific, provide context about your project and constraints, and structure instructions with headings to guide the agent’s workflow.

# Good: Specific and actionable
Analyze issue #${{ github.event.issue.number }} and add appropriate labels from the repository's label list. Focus on categorizing the issue type (bug, feature, documentation) and priority level (high, medium, low).

# Project Context
This repository follows semantic versioning and GitHub Flow. When reviewing pull requests, ensure all tests pass, documentation is updated for API changes, and breaking changes are clearly marked.

# Weekly Research Report

## Research Areas
Focus on competitor analysis, emerging AI development trends, and community feedback for ${{ github.repository }}.

## Output Format
Create a structured report with executive summary, key findings by area, and recommended actions.

Use action-oriented language with clear verbs (analyze, create, update, triage) and specify expected outcomes. Help agents make consistent decisions by providing criteria and examples:

# Issue Labeling Criteria
Apply labels: `bug` (incorrect behavior with repro steps), `enhancement` (new features), `question` (help requests), `documentation` (docs/examples). Priority: `high-priority` (security/critical bugs), `medium-priority` (features/non-critical bugs), `low-priority` (nice-to-have improvements).

Anticipate unusual situations and error conditions. If a workflow fails, document the failure in an issue with error messages and context, tag it with ‘workflow-failure’, and exit gracefully without partial changes.

Content Organization

Use numbered lists for multi-step processes, conditional statements for decision-making, and templates for consistent output:

# Code Review Process
1. Check CI checks are passing and PR has appropriate title/description
2. Scan for code quality issues and verify error handling/logging
3. Create constructive comments and summarize assessment

# Issue Triage Logic
If error messages/stack traces: label 'bug', check for similar issues, request info if needed
If feature request: label 'enhancement', assess scope and complexity
Otherwise: label 'question'/'discussion', provide resources

# Status Report Template
## Summary: [week's activities]
## Key Metrics: PRs merged, issues resolved, new contributors
## Highlights: [achievements, decisions]
## Next Week: [planned priorities]

Common Pitfalls

Avoid over-complexity (keep instructions focused), assuming knowledge (explain project conventions), inconsistent formatting, missing error handling, and vague success criteria. Before deploying, read instructions aloud to check clarity, review examples for accuracy, and consider edge cases.

Templating

Agentic markdown supports GitHub Actions expression substitutions and conditional templating for content. See Templating and Substitutions for details.

Editing and Iteration

See Editing Workflows for complete guidance on when recompilation is needed versus when you can edit directly.

Markdown Scanning

The markdown body of workflows (excluding frontmatter) is automatically scanned for malicious content when added via gh aw add, during trial mode, and at compile time for imported files. The scanner rejects workflows containing: Unicode abuse (zero-width characters, bidirectional overrides), hidden content (suspicious HTML comments, CSS-hidden elements), obfuscated links (data URIs, javascript: URLs, IP-based URLs, URL shorteners), dangerous HTML tags (<script>, <iframe>, <object>, <form>, event handlers), embedded executable content (SVG scripts, executable MIME data URIs), and social engineering patterns (prompt injection, base64-encoded commands, pipe-to-shell patterns). These checks cannot be overridden.

Editing Workflows - When to recompile vs edit directly
Workflow Structure - Overall workflow file organization
Frontmatter - YAML configuration options
Security Guide - Comprehensive security guidance