Orchestrate a fleet of AI coding agents through herdr — the terminal workspace manager (workspaces → tabs → panes) running on this machine. Spawn agents, dispatch work, watch lifecycle state (idle/working/blocked), unblock approval prompts, fan out and converge multi-agent work, and manage agent integrations.
Triggered when the user mentions herdr, the fleet, "spawn an agent", "what are my agents doing", panes/workspaces/worktrees, herdr integrations, or wants an agent to drive other coding agents (claude/codex/cursor/opencode/etc.) running in herdr.
Also triggered when an intent arrives over a chat channel (Mattermost, Discord, Slack, etc.) and the right response is to spin up a parallel herd of codex (or mixed) workers to achieve the goal — understand the intent first, then fan out concurrent workers, converge results, and report back on the same channel.
herdr is a local CLI + headless server talking over a Unix-domain socket.
You orchestrate the fleet through the herdr CLI (which wraps the socket
API) or by speaking JSON to the socket directly. It is the host machine's
shared substrate for running more than one coding agent at a time, in
isolated worktrees, under a single visible window.
This skill teaches an agent how to:
| # | Workflow | When to use it |
|---|---|---|
| 1 | Discover the fleet | "what's running?", "where is agent X?" |
| 2 | Know thyself (CRITICAL) | Before any send/run/close — avoid corrupting your own pane |
| 3 | Spawn an agent | Bring a new claude/codex/cursor/etc. online |
| 4 | Dispatch work | Send a prompt to an agent and submit it |
| 5 | Monitor & wait | Block until an agent reaches a target state |
| 6 | Unblock a stuck agent | Resolve approval/permission prompts |
| 7 | Fan-out → converge | Classic multi-agent parallel pattern |
| 8 | Notify the human | Local desktop notifications |
| 9 | Channel-driven intent → herd | Intent arrives on a chat channel, spin up a parallel herd |
| 10 | Compound the run | Review before reporting, write a run report, promote recurring lessons into this skill |
See skill/SKILL.md for the full reference and
skill/reference.md for verbatim CLI/socket docs.
# from a fresh agent environment
curl -sSL https://raw.githubusercontent.com/machine-machine/hermes-skill-herdr/main/scripts/install.sh | bashThis will clone the repo and symlink the skill into the right location
for both Claude (~/.claude/skills/herdr/) and Hermes (~/.hermes/skills/herdr/).
git clone https://github.com/machine-machine/hermes-skill-herdr.git
cd hermes-skill-herdr
# Pick the target agent platform:
ln -s "$(pwd)/skill" ~/.hermes/skills/herdr
# or
ln -s "$(pwd)/skill" ~/.claude/skills/herdrcd hermes-skill-herdr && git pullThe symlink stays valid, the skill is reloaded on next session.
hermes-skill-herdr/
├── README.md ← you are here
├── CHANGELOG.md ← version history (semver)
├── LICENSE ← MIT
├── CONTRIBUTING.md ← how to propose changes
├── skill/
│ ├── SKILL.md ← the skill itself (loaded by the agent)
│ └── reference.md ← verbatim CLI & socket reference
└── scripts/
├── install.sh ← one-line installer (see Install section)
└── lint.sh ← sanity checks on SKILL.md frontmatter & cross-refs
This skill follows Semantic Versioning.
- MAJOR — breaking change to the workflow or command examples that an agent would follow
- MINOR — new workflow, new section, new command pattern added
- PATCH — typo fix, clarification, reference link fix, metadata update
The current version is declared in the version field of the YAML
frontmatter at the top of skill/SKILL.md and mirrored in
CHANGELOG.md.
Originally copied from a local Claude skills directory and adapted:
- Source:
~/.claude/skills/herdr/SKILL.md(v0.6.9 of herdr / protocol 13) - Section 9 (channel-driven herd) added by Hermes Agent session on 2026-06-11
See CHANGELOG.md for the full history.
MIT — see LICENSE.