Markdown

The markdown body contains the natural-language instructions for the AI agent. It follows the frontmatter and is loaded at runtime, so you can 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, include relevant project context and constraints, and use headings to guide the 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 verbs such as analyze, create, update, and triage, and state the expected outcome. Include clear criteria or examples when you need consistent decisions.

# 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).

Call out unusual situations and failure handling explicitly. For example, if a workflow fails, instruct the agent to file an issue with the error details, apply the workflow-failure label, and exit without partial changes.

Content Organization

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

# 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, assumed knowledge, inconsistent formatting, missing error handling, and vague success criteria. Before deploying, read the instructions aloud, check 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.

Temporary File Paths in Prompts

Use /tmp/gh-aw/agent/ as the root for any temporary files that the agent reads or writes. The contents of that directory are uploaded as a run artifact, so anything outside it is not preserved for inspection.

The compiler emits a warning when the markdown body references /tmp/ or /tmp/gh-aw/ directly:

workflow.md: warning: Prompt references /tmp/ or /tmp/gh-aw/ directly. Use /tmp/gh-aw/agent/ as the root for all temporary files generated by the agent — its contents are uploaded as a run artifact.

Paths under /tmp/gh-aw/agent/ (for example /tmp/gh-aw/agent/result.json or /tmp/gh-aw/agent/logs/out.log) do not trigger the warning. Reserved sibling namespaces such as /tmp/gh-aw/cache-memory/, /tmp/gh-aw/repo-memory/, and /tmp/gh-aw/mcp-logs/ remain valid for their own purposes and are out of scope for this warning.

Inline Sub-Agents

You can define inline sub-agents directly inside a workflow file using a level-2 heading:

## agent: `name`
---
model: claude-haiku-4.5
description: Short description of the agent
---
Agent instructions go here.

See Inline Sub-Agents for the full syntax reference.

Editing Workflows - When to recompile vs edit directly
Workflow Structure - Overall workflow file organization
Frontmatter - YAML configuration options
Inline Sub-Agents - Defining Copilot sub-agents inside a workflow file
Security Guide - Comprehensive security guidance