How to use the Agent Orchestrator 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 request matches them. Agent Orchestrator is a skill whose job is to look at the other skills you have.

Its description says it scans skills automatically, matches them by capabilities, coordinates multi-skill workflows and manages a registry. In practice the skill reads skill folders and produces plans. It does not run the other skills or start agents, and any delegation, messaging or publishing requires your explicit permission.

• Scan local skill folders and record metadata such as name, description, location, triggers and capability tags.
• Score skills against a request and list the ranked candidates.
• Propose an execution plan, such as a sequential pipeline or parallel run, for two or more matched skills.

How to install the Agent Orchestrator skill

Download the ZIP for agent-orchestrator from this page. You can install it in one of two ways.

Option A: unzip it into your personal skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder if you want it only for that project.

Option B: in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.

Requirements before you run the scripts

The scripts need Python 3.10 or newer and PyYAML, which is listed in scripts/requirements.txt. The source recommends installing it in a reviewed virtual environment.

You must also set the AGENT_ORCHESTRATOR_DATA_DIR environment variable to an absolute path of a private directory outside the skill installation. The registry, hashes and project assignments are stored there, so do not point it at a shared directory or a tree containing symbolic links.

• Python 3.10 or newer
• PyYAML (scripts/requirements.txt)
• AGENT_ORCHESTRATOR_DATA_DIR set to a private absolute path outside the skill folder

How to trigger the skill with natural requests

Ask for what you want in plain language and name the purpose clearly. The skill's own guidance says it applies when you request a local inventory of skills, or a coordination plan for a task that has several capabilities. Ask for a comparison of candidates when you want one explicitly.

The skill is designed to scan only in the scope you ask for. It does not intercept every request, and it does not start a scan on its own.

• "Make an inventory of the skills installed on my machine."
• "Which of my skills could scrape prices and send an alert?"
• "Compare the candidate skills for this task, but do not run them."

Run the scan, matcher and orchestrator

Run the scan first, because the matcher does not start one automatically. Commands below assume the parent folder of agent-orchestrator is your current directory; otherwise use the absolute path to the script.

Read the matcher result by count. With zero matches, no candidate passed the heuristic threshold, which does not prove that no relevant skill exists. With one match, inspect its scope, files, dependencies and authorization before choosing it. With two or more, propose a plan only if the task calls for coordination.

Use --project to give skills assigned to a project a +20 boost, and --force on the scanner to ignore the hash cache.

• Scan skills: scan_registry.py runs a fast scan using a SHA-256 hash cache; --status shows a detailed status table; --force re-scans everything.
• Match a request: match_skills.py with your query, optionally --project <name>.
• Plan a workflow: orchestrate.py with --skills and --query, when two or more skills matched.

How scores and workflow patterns work

The matcher adds points for a skill name appearing in the query (+15), an exact trigger keyword (+10), a matching capability category (+5), word overlap with the description (+1) and a project boost (+20). Skills scoring below 5 points are ignored. These scores are local heuristics, not proof of safety, compatibility or authorization.

When several skills match, the orchestrator labels a pattern: a sequential pipeline where one skill's output feeds the next; parallel execution where skills work on different aspects; or primary plus support, used when one skill scores at least twice the others.

• Pipeline: output of one skill feeds the next.
• Parallel: skills handle different parts of the request independently.
• Primary plus support: one main skill with others supplying data.

Safety notes: scripts, data and network

This skill runs Python scripts on your machine. It does not use the network, according to its listing. Its risk level in the source is marked critical, so read the scripts before running them and install dependencies in a virtual environment you have reviewed.

The scanner searches only a limited depth (SKILL.md in .claude/skills/*/, top-level folders and subfolders up to depth 3), so the inventory is partial. A failed read, invalid JSON or missing registry does not mean no skill exists. Ambiguous names should stop selection, and the source says messages and publishing need explicit scope.

• Keep AGENT_ORCHESTRATOR_DATA_DIR private and outside the installation.
• Do not use it on shared or multi-user machines.
• Re-check scope before any delegation, messaging or publishing step.