create-workflow

Create a markdown file in .github/workflows with YAML frontmatter defining triggers, permissions, and tools, plus a markdown body with the agent instructions. Then run gh aw compile to generate the lock file and commit both files.

Configure the server under mcp-servers in the workflow frontmatter using command/args for stdio, container for containerized servers, url with headers for HTTP, or registry for registry-backed servers. Keep the allowed tools list tight and pass credentials through secrets-backed env or headers.

Recompile with gh aw compile only after frontmatter changes. Markdown body edits take effect on the next run without recompilation, but the .lock.yml must be regenerated and committed whenever frontmatter changes.

Compilation failures usually come from YAML indentation errors, missing required fields like on:, or invalid field names. Run gh aw compile --verbose or gh aw validate --strict to isolate schema, lint, and security issues.

Workflows should not perform arbitrary GitHub writes directly. Use safe-outputs in the frontmatter to declare which write operations are permitted, such as creating issues, comments, or labels, and keep the scope minimal.