Create or update a GitHub Agentic Workflow in .github/workflows using gh aw, including frontmatter, markdown instructions, optional MCP servers, compilation, and debugging. Use this whenever the user wants new repository automation, wants to turn a repeated GitHub process into an agentic workflow, needs to add external MCP tools to a workflow, or needs help validating and fixing a workflow before commit.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Create or update a GitHub Agentic Workflow in .github/workflows using gh aw, including frontmatter, markdown instructions, optional MCP servers, compilation, and debugging. Use this whenever the user wants new repository automation, wants to turn a repeated GitHub process into an agentic workflow, needs to add external MCP tools to a workflow, or needs help validating and fixing a workflow before commit.
argument-hint
Describe the workflow goal, trigger, outputs, engine, and any MCP or safe-output requirements.
Create Workflow
Use this skill to author GitHub Agentic Workflows as markdown source files and carry them through compilation and validation.
GitHub Agentic Workflows are stored as .github/workflows/<name>.md and compiled into .github/workflows/<name>.lock.yml. The markdown body is the runtime instruction set. The frontmatter controls triggers, permissions, tools, MCP servers, network access, and safe outputs.
Read the authoring reference before drafting the workflow when the request includes MCP setup, unfamiliar triggers, safe outputs, or troubleshooting.
gh aw is a GitHub CLI extension, so invoke it through gh, not as a standalone gh-aw binary.
Run commands from the repository root.
Use gh aw --help for the top-level command list.
Use gh aw <command> --help for command-specific flags.
gh aw new <workflow-name> --engine copilot scaffolds a new markdown workflow.
gh aw compile <workflow-name> accepts either a workflow id like my-workflow or a filename like my-workflow.md; with no argument it compiles every markdown workflow under .github/workflows/.
gh aw validate <workflow-name> --strict validates without emitting lock files and runs the full validation stack.
gh aw trial ./path/to/workflow.md --host-repo . is the local-file path for exercising a workflow_dispatch workflow against the current repository.
gh aw list is a quick readiness check; if it reports no .github/workflows directory found, the repository has not been set up for workflow authoring yet.
When to use
The user wants to create a new GitHub Agentic Workflow.
The user wants to automate repository work such as triage, reporting, validation, issue handling, scheduled analysis, or orchestrated agent tasks.
The user wants to convert a repeated GitHub process into a workflow file in .github/workflows/.
The user needs to add or update MCP servers for a workflow.
The user needs help compiling, validating, or debugging a workflow after editing it.
Do not use this skill for generic GitHub Actions YAML authoring that is not based on GitHub Agentic Workflows markdown files.
Core workflow
Follow this order.
Confirm repository readiness.
Gather the workflow contract.
Author the markdown workflow file.
Add MCP servers or safe outputs if required.
Compile and validate.
Debug any failures.
Hand back the finished workflow with the exact files changed.
1. Confirm repository readiness
Check whether the repository has already been initialized for GitHub Agentic Workflows.
If the repo is not initialized, instruct the user to initialize it with gh aw init or by following the repository setup prompt from install.md.
gh aw init is interactive by default and sets up the dispatcher agent, .gitattributes, and Copilot MCP wiring unless --no-mcp is passed.
Use gh aw list or inspect .github/workflows/ as a quick readiness check before assuming the repo is already set up.
Initialization is required for the full authoring experience because it installs the dispatcher agent and MCP configuration used during workflow authoring.
If the user only wants a draft file and is not ready to initialize, you may still create the markdown workflow, but state that compilation and execution may not work until initialization and secrets are configured.
2. Gather the workflow contract
Before writing the file, extract or ask for the minimum set of requirements:
workflow purpose
trigger model
expected outputs or side effects
target engine if not defaulting to Copilot
required GitHub toolsets
required external services or MCP servers
whether the workflow must write back to GitHub
any security or network constraints
If the user is vague, ask focused questions that close authoring gaps quickly. Prioritize these decision points:
What event should trigger the workflow: issue, pull request, schedule, manual dispatch, discussion, or command?
Should it only analyze and report, or should it create or update GitHub artifacts?
Does it need external tools beyond built-in GitHub tooling?
Is this a new workflow or a change to an existing one?
3. Author the markdown workflow file
Create the workflow in .github/workflows/<workflow-name>.md using kebab-case names.
Keep the file split into two layers:
frontmatter for configuration
markdown body for the runtime instructions
When writing the markdown body:
use clear action verbs such as analyze, label, summarize, create, update, or dispatch
include headings so the agent can follow the task structure reliably
use numbered steps for multi-stage procedures
include explicit decision rules when classification or branching matters
include a result template when the output should be structured
give concrete repository context and constraints instead of generic advice
Treat the workflow body like instructions for a new teammate. Be specific enough that the agent can act consistently without guessing.
4. Add MCP servers or safe outputs if required
Safe outputs
If the workflow needs to create issues, comments, PR updates, labels, or other write operations, use safe-outputs. Do not model direct writes as unrestricted agent behavior.
Keep write scope minimal and configure only the output types the workflow actually needs.
MCP servers
If the workflow needs external systems or custom tools, configure them under mcp-servers: in frontmatter.
Prefer the smallest viable configuration:
limit allowed tools instead of exposing everything unless the workflow truly needs broad access
pass credentials through env or headers using secrets
prefer read-only MCP integrations
keep network access explicit
Use the correct server form for the transport:
command plus args for stdio servers
container with optional args, entrypointArgs, and env for containerized servers
url with optional headers for HTTP servers
registry when using a server from the MCP registry
If the user only needs small deterministic helper tools, consider whether mcp-scripts is a better fit than a full external MCP server.
5. Compile and validate
After editing frontmatter or imports, recompile the workflow.
Use this validation loop:
Run gh aw compile <workflow-name> or gh aw compile.
For a newly authored or security-sensitive workflow, prefer gh aw validate <workflow-name> --strict before or after compile. gh aw validate is the no-emit validation command and runs the full lint and security stack.
If you are iterating on frontmatter frequently, use gh aw compile --watch <workflow-name>.
If errors are unclear, rerun the failing command with --verbose.
Confirm the .lock.yml file was regenerated after compile.
Commit both the .md and .lock.yml files.
Important rule:
markdown body only changes do not require recompilation
frontmatter changes do require recompilation
6. Debug failures
Use the shortest path that matches the failure mode.
Compilation failures
check YAML indentation, colons, arrays, and field names
verify required fields like on: are present
run gh aw compile --verbose
use gh aw validate --strict to isolate schema, lint, and security issues without rewriting lock files
use gh aw compile --purge if stale lock files are causing confusion
MCP failures
inspect the workflow MCP configuration with gh aw mcp inspect <workflow-name>
use gh aw mcp list-tools <server> <workflow-name> to confirm the server exposes the tools the workflow expects
verify allowed tools match what the workflow expects
verify secrets-backed env vars or headers are present
verify container images, commands, and network access
if a tool is missing, narrow whether the server failed to connect or the tool was never exposed
Runtime failures
inspect logs with gh aw logs <workflow-name>
audit a failing run with gh aw audit <run-id>
verify the workflow was compiled and both source and lock files were pushed
verify repository secrets for the chosen engine and any MCP server credentials
Common authoring mistakes
workflow exists but was not compiled after frontmatter changes
output requires safe-outputs but the workflow only describes direct writes
permissions are broader than needed or too narrow for the configured tools
MCP configuration is present but the workflow instructions never tell the agent when to use those tools
network domains needed by external services are missing
7. Quality bar
Before finishing, check all of these:
workflow filename is descriptive and kebab-case
frontmatter is minimal but complete
markdown body is specific, structured, and action-oriented
write actions go through safe-outputs
MCP configuration is scoped and secrets-aware
.lock.yml exists and matches the current frontmatter
the user can tell which edits require recompilation in the future
Response contract
When you create or update a workflow for the user:
state which workflow file you changed
summarize the trigger, main behavior, and configured tools
state whether you recompiled and which validation commands you ran
call out any remaining prerequisites such as missing secrets or required initialization
Example request shapes
Create a scheduled workflow that posts a weekly repository health issue.
Create an issue triage workflow that uses GitHub tools and asks clarifying questions.
Add a Notion MCP server to this workflow and restrict it to search tools.
Fix why this workflow compiles but fails at runtime.
Turn this manual release checklist into an agentic workflow with safe outputs.
