# How to use Herdr skills and herdr --skill

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

Author: [Flavio Copes](https://flaviocopes.com/about/) | Published: 2026-08-21 | Topics: [AI](https://flaviocopes.com/tags/ai/) | Canonical: https://flaviocopes.com/herdr-skills/

Herdr can be controlled with its command line.

This is useful for us, but it is even more useful for a coding agent.

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.

The problem is that the agent needs to know the exact commands and the safety rules first.

This is what the Herdr skill provides.

In this guide I’ll show you how to use `herdr --skill`, install the skill in an agent, and check that it is working.

If Herdr itself is new to you, start with my [deep dive into Herdr](https://flaviocopes.com/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.

With the skill loaded, an agent knows how to:

- list workspaces, tabs, panes, and agents
- split a pane without stealing your focus
- run a command in another pane
- read recent terminal output
- wait for a test, server, or agent
- start a helper agent in a sibling pane

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.

That distinction prevents a lot of fragile automation.

## Print the skill with herdr --skill

If Herdr is installed, run:

~~~bash
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:

~~~bash
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:

~~~bash
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:

~~~bash
npx skills add herdrdev/herdr --skill herdr
~~~

If your agent does not support reusable skills, open the [Herdr skill file on GitHub](https://github.com/herdrdev/herdr/blob/master/skills/herdr/SKILL.md) and add its contents to the project or user instructions that the agent reads.

## Start the agent inside Herdr

Installing the skill is only half of the setup.

The agent must run inside a Herdr-managed pane.

Start Herdr:

~~~bash
herdr
~~~

Then start your coding agent in one of its panes:

~~~bash
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:

~~~bash
test "$HERDR_ENV" = 1
~~~

If the check fails, the agent should stop.

This guardrail matters. Without it, an agent running 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:

~~~bash
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:

~~~bash
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:

~~~bash
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:

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

It can then send a prompt and wait:

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

The name `reviewer` is easier to follow than a changing terminal position.

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:

~~~bash
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:

- `herdr --skill` prints instructions for an agent operating Herdr
- [herdr.dev/agent-guide.md](https://herdr.dev/agent-guide.md) helps an agent teach Herdr to a person

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:

~~~bash
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:

~~~bash
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:

~~~bash
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.

Then start with small requests: inspect the workspace, create one pane, run one command, and read the result.

Once that works, let the agent coordinate a reviewer or a test runner.

The interesting part is not that an agent can arrange a terminal for you.

It is that the agent can build the workspace it needs, address every pane by a stable ID, and wait for real state changes without taking over your screen.

The full command reference is in [the official Herdr agent skill documentation](https://herdr.dev/docs/agent-skill/).