Guide · Agent skill
How to use the Workflow Runner agent skill (workflow-runner)
Updated · written with AI from the project's own documentation and checked against our catalogue data
Workflow Runner is an agent skill that lets an AI assistant run a multi-step YAML workflow itself, playing each expert role in order instead of calling a separate orchestration service. It is aimed at people who use Claude Code, Cursor or OpenClaw and already have agency-agents-zh role files. After this guide you will know what the skill does, how to install it, how to trigger it with a plain request, and where its output is saved.
Workflow RunnerjnMetaCode/superpowers-zh · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it so that SKILL.md sits in ~/.claude/skills/workflow-runner/ or .claude/skills/workflow-runner/ in your project.
- 2Install agency-agents-zh. Clone the repository from GitHub with git clone --depth 1, or run npm install agency-agents-zh, so the role files are available.
- 3Prepare a workflow file. Place a .yaml workflow file in your project, or plan to describe the task and let the agent generate one.
- 4Make a natural request. Ask the agent to run your YAML file or to have several roles work together on a task.
- 5Answer any input prompts. If a required input is missing, the agent asks for it before running any step.
- 6Review the execution plan. The agent shows the layered plan, so you can check the step order and which steps run in parallel.
- 7Collect the results. Open the dated .ao-output folder to read each step file, summary.md and metadata.json.
What is an agent skill and what does workflow-runner do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when a task matches the skill's description. The workflow-runner skill is triggered when you give the agent a .yaml workflow file or ask several expert roles to work together on a task.
Once triggered, the agent reads the workflow, locates the role definition files, and works through the steps in dependency order. Each step's output is passed to later steps that reference it. The current AI session does all the work, so no separate API key is needed.
- Reads the YAML workflow fields such as steps, inputs, role, task, output and depends_on
- Looks up each role's .md definition file from the agency-agents-zh directory
- Plays each role in turn, labelling every step with the role name
- Saves results as files in a dated output folder
Install the workflow-runner skill
Download the ZIP file from this directory page and unzip it. The skill is delivered as a folder containing SKILL.md. Place that folder in one of two locations: your user skills folder, or a project-specific folder.
You can also upload the skill through the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the skill there.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload the skill
~/.claude/skills/workflow-runner/SKILL.mdInstall the agency-agents-zh role files
The skill will not run without the role definitions. It looks for a directory named by the workflow's agents_dir field, which is agency-agents-zh in the example workflow. Install it with either of the two methods below, and the skill will find it in the current folder, a parent folder, a folder next to the YAML file, or node_modules.
If none of these locations contains the role directory, the skill stops and asks you to install it first.
git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
npm install agency-agents-zhHow do you trigger the skill with a natural request?
You do not need a special command. Describe what you want in plain language, or point the agent at a workflow file. The skill is meant to trigger on a .yaml file or on a request for multi-role collaboration.
If you do not have a YAML file, the skill can generate one from your description, show it to you for confirmation, and then run it. This is the shortcut mode.
- Run workflows/story-creation.yaml
- Use a product manager and an architect to review this PRD
- Use a narrator and a psychologist to write a short story about a lighthouse keeper
- Ask it to build a workflow for reviewing a spec, then confirm the generated YAML before it runs
运行 workflows/story-creation.yamlHow the skill runs a workflow
The skill follows five stages in a fixed order. First it parses the workflow and locates the role directory. Next it collects required inputs, asking you for any missing ones rather than guessing. It then builds an execution plan by grouping steps into layers based on depends_on, and shows that plan before running. Steps within one layer are independent of each other.
For a layer with one step, the agent plays that role in the main session. For a layer with several steps, it starts a sub-agent per step, giving each the full text of the role file. Results are written to disk at the end.
- Config fields llm, concurrency, timeout and retry are ignored, because the skill uses the current session's model
- If a step fails, its dependent downstream steps are skipped while independent steps continue
- Output layout: .ao-output/{workflow name}-{date}/ with steps/, summary.md and metadata.json
.ao-output/{工作流名称}-{YYYY-MM-DD}/
├── steps/
├── summary.md
└── metadata.jsonSafety notes and limits
The skill does not run scripts and does not use the network, according to its listing. It does read and write files and runs shell test commands to find the role directory, and it may launch sub-agents for parallel layers.
Because every role runs inside one model session, the roles can blend together rather than give truly independent opinions. If a workflow depends on a specific model, timeout or retry setting, this skill will not honour it.
- Reads and writes files in your working area
- Uses shell test commands to locate directories
- Launches sub-agents for parallel steps
What people use it for
- Have a product manager and an architect critique a product requirements document in one run
- Write a story by combining a narrator and a psychologist role across several steps
- Run a multi-step review workflow stored as a YAML file in your project
- Generate a quick workflow from a plain description and check it before running
Frequently asked questions
Is workflow-runner free to use?
The skill is listed under the MIT licence. It does not need an API key, because it uses the LLM already running in your current session. Check the licence text on the source page for the full terms.
Do I need an API key to use workflow-runner?
No. The skill states that it works without API key configuration, and that it uses the current session's LLM as the execution engine. The YAML fields for llm settings are ignored in this mode.
What do I need before installing the skill?
You need agency-agents-zh role files, installed from GitHub with git clone or from npm, or present in a nearby node_modules folder. You also need an agent such as Claude Code, Cursor or OpenClaw that can read and write files, run shell test commands and launch sub-agents.
Why does the skill say it cannot find the role directory?
The skill checks the current folder, the parent folder, the folder beside your YAML file and node_modules for the directory named in agents_dir. If none exists, it stops. Install agency-agents-zh with git clone or npm install, then run it again.
Can I use workflow-runner with a specific model or set timeouts?
No. The skill explicitly ignores the llm, concurrency, timeout and retry fields in the YAML file, because it runs on the current session's model. Those settings only apply to the separate CLI mode.
How is this different from running agency-orchestrator as a service?
Workflow Runner runs the steps inside your existing AI session rather than through a separate orchestration service. The trade-off is that all roles share one model session, so their views may blend together instead of being fully independent.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Workflow Runner suits you if you already use agency-agents-zh role files and want team-style, multi-step reviews inside Claude Code, Cursor or OpenClaw without setting up another service. It is also a good fit for Chinese-speaking users, since the skill is written in Chinese. If you need truly independent expert opinions, or your workflow depends on specific model, timeout or retry settings, pick a dedicated orchestration tool instead.
Download the skill