Agent skill file
PK-Herdr ships a reusable agent skill file at SKILL.md.
Install that file into any coding agent that supports reusable skills or custom instructions. The skill teaches the agent how to control PK-Herdr from inside a PK-Herdr pane.
PK-Herdr also serves a separate guide at herdr.pkking.computer/agent-guide.md for a different job: an agent helping a human learn, set up, or troubleshoot PK-Herdr. The skill is for an agent operating PK-Herdr; 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 pk-herdr CLI when HERDR_ENV=1 is set. That means the agent is running inside a PK-Herdr-managed pane and can safely talk to the local PK-Herdr 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 not a separate app or service. It is a markdown instruction file for agents.
Install it
Section titled “Install it”Install the skill with npx skills:
npx skills add kingkillery/pk-herdr --skill herdr -gThe -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/kingkillery/pk-herdr/blob/master/SKILL.mdFor agents with a skill system, install that file as a skill named herdr. For agents without a skill system, paste the file into the agent’s project or user instructions.
After installation, start the agent inside PK-Herdr:
pk-herdrclaudeOr use any other coding agent in a PK-Herdr pane. The important part is that the agent process runs inside PK-Herdr, so HERDR_ENV=1 is available.
Safety rule
Section titled “Safety rule”The skill starts with one guardrail: if HERDR_ENV=1 is not set, the agent should stop and say it is not running inside a PK-Herdr-managed pane.
This prevents an agent outside PK-Herdr 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: