How to use Herdr skills and herdr --skill

By

Learn how to install the Herdr agent skill, use herdr --skill, and let coding agents safely inspect, split, run, and wait in panes.

~~~

You can control Herdr from its command line. This becomes especially useful when a coding agent runs inside Herdr.

An agent running inside Herdr can inspect the current workspace, create a new pane, start a helper agent, wait for a test, and read the result.

Before doing that, the agent needs to know the exact commands and their safety rules. The Herdr skill contains those instructions.

If Herdr itself is new to you, start with my deep dive into Herdr.

What is the Herdr skill?

The Herdr skill is a Markdown instruction file for coding agents.

It does not install Herdr. It teaches an agent how to control the Herdr session it is already running inside.

A skill teaches the agent how to use Herdr. A Herdr plugin is executable code that adds workflows, actions, events, or panes.

With the skill loaded, an agent knows how to:

The skill also explains the important distinction between a pane and an agent.

A pane can contain a shell, a development server, a test runner, or a coding agent. Pane commands work with the terminal itself. Agent commands work with a recognized coding agent and its lifecycle states, so an automation does not have to treat every pane like an agent.

If Herdr is installed, run:

herdr --skill

Herdr prints the skill bundled with your installed binary.

This is a good way to inspect the instructions before giving them to an agent. It also means the command reference matches the Herdr release you are running.

You can save the output if your agent accepts a local instruction file:

herdr --skill > HERDR-SKILL.md

Read the file before committing it to a project. It is long because it includes command syntax, coordination recipes, and safety rules. In most cases I would install the reusable skill instead of copying this generated file into every repository.

Install the skill globally

Herdr publishes the skill in its GitHub repository.

Install it globally with:

npx skills add herdrdev/herdr --skill herdr -g

The -g option makes the skill available to supported agents in every project.

Omit it if you only want the skill in the current project:

npx skills add herdrdev/herdr --skill herdr

If your agent does not support reusable skills, open the Herdr skill file on GitHub and add its contents to the project or user instructions that the agent reads.

Start the agent inside Herdr

The agent must run inside a Herdr-managed pane. Installing the skill does not put it there.

Start Herdr:

herdr

Then start your coding agent in one of its panes:

codex

Or use Claude Code, Cursor Agent CLI, OpenCode, or another supported agent.

Herdr adds HERDR_ENV=1 to managed panes. The skill tells the agent to check that variable before it controls anything:

test "$HERDR_ENV" = 1

If the check fails, the agent should stop.

Without this check, an agent in a normal terminal could accidentally control a separate Herdr session that belongs to you.

Try a small task first

Do not begin by asking the agent to create ten panes.

Give it one small, visible task:

Use the Herdr skill. Inspect the current workspace, split a pane to the right without changing my focus, run the test command in that pane, wait for it to finish, and summarize the result.

The agent should first inspect the live state.

Typical commands include:

herdr workspace list
herdr pane current --current
herdr pane list --workspace "$HERDR_WORKSPACE_ID"

It should then create a pane while preserving the current directory:

herdr pane split \
  --current \
  --direction right \
  --cwd "$PWD" \
  --no-focus

Herdr returns a pane ID. The agent must read that ID from the JSON response instead of guessing it.

It can use the returned ID to run and inspect a command:

herdr pane run w1:p2 "npm test"
herdr pane wait-output w1:p2 \
  --match "tests passed" \
  --timeout 120000
herdr pane read w1:p2 \
  --source recent-unwrapped \
  --lines 120

w1:p2 is only an example. IDs are created by the live session.

Let one agent start another

The skill also covers agent coordination.

Suppose the current agent needs a review. It can split a pane, read the new pane ID, and start a named agent:

herdr agent start reviewer \
  --kind codex \
  --pane w1:p2

It can then send a prompt and wait:

herdr agent prompt reviewer \
  "Review the current diff and report only actionable findings." \
  --wait \
  --timeout 120000

The coordinator can keep using the name reviewer even if the terminal position changes.

Herdr knows whether a recognized agent is working, blocked, done, idle, or unknown. This lets the coordinator wait for lifecycle state instead of repeatedly scanning text output.

For example:

herdr agent wait reviewer \
  --until blocked \
  --timeout 120000

Use this when you specifically expect an approval or question. For a normal prompt, herdr agent prompt ... --wait is enough.

The skill is not the human guide

Herdr provides two different documents:

Use the skill when you want the agent to control panes.

Use the guide when you want the agent to explain setup, concepts, configuration, or troubleshooting to you.

Common problems

The agent says it is not inside Herdr

Check:

printf '%s\n' "$HERDR_ENV"

It should print 1.

If it does not, start Herdr first and launch the agent from a managed pane. Installing the skill does not move an already-running agent into Herdr.

The agent starts Herdr instead of controlling it

The skill says not to run bare herdr for command discovery because that opens or attaches the TUI.

Use:

herdr --help
herdr pane
herdr agent

These show the current command groups without changing the workspace.

The agent targets the wrong pane

Ask it to use --current, an explicit pane ID, or a unique agent name.

Commands that rely on whichever pane the UI happens to focus are convenient for a person and unreliable in automation.

The commands in an old skill no longer match

Run:

herdr --skill

This gives you the copy that ships with the installed binary. Reinstall the reusable skill when you want to update the copy managed by your agent’s skill system.

My recommendation

Install the skill globally if you regularly run agents inside Herdr.

Start with a small request. Ask the agent to inspect the workspace, create one pane, run one command, and read the result. Then let it coordinate a reviewer or a test runner.

The agent can address every pane by a stable ID and wait for state changes without taking over your screen.

The full command reference is in the official Herdr agent skill documentation.

Tagged: AI · All topics

Want me to talk about your product? You can sponsor this site.

~~~

Related posts about ai: