How to use the GitHub Agentic Workflows Router agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent can load when a task matches the skill's description. This skill's description is: route gh-aw workflow design, create, debug and upgrade requests to the right prompts.

When you ask the agent to design, create, update, debug or upgrade a GitHub Agentic Workflow in a repository, the skill tells it to identify the task type, load the matching prompt or skill file, and follow it directly. If the correct prompt is unclear, the agent is instructed to ask you a clarifying question rather than guess.

• Design a workflow from scratch through an interview: designer.md
• Create a new workflow: create-agentic-workflow.md
• Update an existing workflow: update-agentic-workflow.md
• Debug, audit or investigate a workflow: debug-agentic-workflow.md
• Upgrade workflows and fix deprecations: upgrade-agentic-workflows.md

Install the skill by downloading the ZIP

Download the skill as a ZIP file from the page where you found it. Then unzip it into one of these locations, depending on whether you want the skill available everywhere or only in one project:

Personal use across projects: unzip into ~/.claude/skills/

One project only: unzip into the project's .claude/skills/ folder

The skill is a single file, SKILL.md, so after unzipping you should see the skill folder containing that file in the location you chose.

• Claude apps: open Settings, go to Capabilities, then Skills, and upload the skill there instead of unzipping it.

Trigger the skill with natural requests

You do not need a special command. Describe the task in plain language and mention GitHub Agentic Workflows or gh-aw in the repository you are working in. The skill is meant for requests to design, create, update, debug or upgrade these workflows.

If your request could match more than one task type, expect the agent to ask which one you mean. Naming the workflow file and the outcome you want makes routing more reliable.

• "Design an agentic workflow that triages new issues in this repository."
• "Create a new gh-aw workflow that summarises merged pull requests each week."
• "Debug why my agentic workflow in .github/workflows is failing."
• "Upgrade my gh-aw workflows and fix any deprecation warnings."
• "Update the trigger on my existing agentic workflow."

What the skill needs to work

The skill does not contain the gh-aw guidance itself. It loads those files from the github/gh-aw repository, which are not stored locally, so the agent needs access to that repository. Without it, the skill cannot load the instruction files it routes to.

You can also add an optional repository overlay. If a file called .github/aw/instructions.md exists in your repository, the agent loads it after the matched prompt. Where the overlay conflicts with upstream defaults, the overlay wins, which lets your team set its own rules.

For OTEL or telemetry tasks, the skill also refers to skills/otel-queries/SKILL.md, which the agent should read after loading the matching workflow prompt.

• Access to the github/gh-aw repository to load the referenced instruction files
• Optional: .github/aw/instructions.md in your repository for local overrides
• For OTEL, OTLP, traces or telemetry tasks: skills/otel-queries/SKILL.md

Safety notes: scripts and network access

According to the skill's listing, it does not run scripts, but it does use the network, because it fetches instruction files from github/gh-aw. Expect the agent to need network access for every routed task.

The skill is specific to GitHub Agentic Workflows. It is not a general-purpose tool and will not help with unrelated automation. Review the instruction files it loads if your team has specific policies about external guidance.

• Runs scripts: no
• Uses network: yes

Tips for better results

Keep requests specific. The skill asks for clarification when it cannot tell which prompt applies, so giving the workflow name and goal up front saves a round trip.

Add a .github/aw/instructions.md file if your team has its own conventions. Because repository overlays take precedence, they are the right place for team-specific rules.

Use the skill when you need the agent to follow the official gh-aw guidance for a given task type, rather than writing workflow YAML from memory.

• Name the workflow file and the outcome you want
• Put team conventions in .github/aw/instructions.md
• Expect the agent to ask a question when the request is ambiguous