Agent skill file
Herdsman ships a reusable agent skill file at skills/herdsman/SKILL.md.
Install that file into any coding agent that supports reusable skills or custom instructions. The skill teaches the agent how to control Herdsman from inside a Herdsman pane.
Herdsman also serves a separate guide at remziduzagac.github.io/herdsman/agent-guide.md for a different job: an agent helping a human learn, set up, or troubleshoot Herdsman. The skill is for an agent operating Herdsman; the guide is for an agent teaching a human.
What the skill does
Section titled “What the skill does”The skill tells an agent to use the herdsman CLI when HERDSMAN_ENV=1 is set. That means the agent is running inside a Herdsman-managed pane and can safely talk to the local Herdsman socket.
With the skill installed, an agent can:
- inspect workspaces, tabs, panes, and neighboring agents
- split panes and run commands without stealing focus
- read pane output and recent logs
- wait for servers, tests, or another agent to finish
- start helper agents in sibling panes
The skill is a Markdown instruction file for agents. If Herdsman is already installed, run herdsman --skill to print the release-matched copy bundled with that binary.
Install it
Section titled “Install it”Installing the Claude Code, Codex, or OpenCode integration also installs the skill for that agent, as skills/herdsman/SKILL.md in its config directory: ~/.claude or CLAUDE_CONFIG_DIR, ~/.codex or CODEX_HOME, and ~/.config/opencode. herdsman update rewrites those copies to match the new binary, herdsman integration status shows whether each one is current, and uninstalling the integration removes it. Herdsman leaves alone a skill it did not write, such as a link into a dotfiles checkout or another skill with the same folder name.
Install the skill with npx skills:
npx skills add remziduzagac/herdsman --skill herdsman -gIf you installed the skill while it lived at the repository root, rerun this add command once instead of using skills update. The add command replaces the oversized copy and records the new location.
The -g flag installs it globally for supported agents. Omit -g to install it into the current project.
Use the repository copy as the manual fallback and source of truth:
https://github.com/remziduzagac/herdsman/blob/main/skills/herdsman/SKILL.mdFor agents with a skill system, install that file as a skill named herdsman. For agents without a skill system, paste the file into the agent’s project or user instructions.
After installation, start the agent inside Herdsman:
herdsmanclaudeOr use any other coding agent in a Herdsman pane so HERDSMAN_ENV=1 is available to the agent process.
Safety rule
Section titled “Safety rule”The skill starts with one guardrail: if HERDSMAN_ENV=1 is not set, the agent should stop and say it is not running inside a Herdsman-managed pane.
This prevents an agent outside Herdsman from trying to control a session it does not own.
Agent-facing reference
Section titled “Agent-facing reference”The full command guide lives in the skill file itself. It covers pane IDs, pane split, pane run, pane read, pane wait-output, agent wait, workspace and tab commands, and coordination recipes.
Read the source file here: