Skills and tools¶

Owners: skillset (read at 1e02b44), pi-devbox (baked skills, at 47b4506), pi-toolkit (global instructions, at 7c05901), cli_utils (at f00eb01) and myconfigs (at ada2b09)

Skills¶

A skill is a directory with a SKILL.md file: a short description, followed by a procedure. At session start pi lists only each skill's name and description. The agent reads the full file when a task matches the description. A large library of skills therefore costs little context until one is needed.

Skills are how procedures that took effort to learn get reused: how to run the first-boot round, how to handle a leaked credential, how to drive a browser, how to write a Mermaid diagram that renders without cut-off text.

Where skills come from¶

pi reads skills from ~/.agents/skills/. Two sources feed that directory:

Skills baked into the image. The image carries a few skills that every container needs, even one with nothing else mounted. They are linked in at every start. Some are written in pi-devbox itself, such as pi-devbox-environment (how this container differs from a normal machine) and pi-devbox-firstboot. Others are copies of a skill owned by another repository, such as the pi-extensions skill and mempalace, kept as a fallback.
The skillset repository, checked out on the host and mounted into the container. It holds the general library, such as browser automation, presentations, Mermaid diagrams, debugging, CI release watching and the OpenStack and Proxmox command-line tools. Its skills are linked into the same directory, so they are kept in sync with a git pull.

When both sources have a skill, the repository that owns it wins. A copy that is only a fallback never overrides a live original, and an original is never overridden by a downstream copy that may lag behind. The image records which commit each copied skill came from.

The global instructions¶

pi also loads one global instructions file, ~/.pi/agent/AGENTS.md, into every session. It comes from pi-toolkit, and the image build appends a short block of its own.

It holds the rules that must apply even when no skill description matches the task, such as:

which skills to read at session start;
when to delegate with task instead of fork;
the rules for a shared palace;
take a second measurement by a different route before recording anything as fact.

A rule placed only in a skill fails when no task matches that skill's description. One such rule was broken five times in a single session by an agent that had the skill available. Rules of that kind move to this file. Depth stays in the skills, and the file points to them.

Command-line helpers: cli_utils¶

cli_utils is a collection of shell tools for bash and zsh, on Linux and macOS. When a checkout is mounted into the container, the image puts its commands on the path at every start. They include:

Command	What it does
`pi-devbox-sanity`	runs pi-devbox's post-recreate sanity check without having to remember where the script lives (`devbox-sanity` does the same for opencode-devbox)
`pi-session-repair`	repairs a pi session file that older pi versions could no longer load
`git-status-all`, `git-pull-all`	status and update across many repositories at once
fzf tools	interactive fuzzy browsers for files, shell history, processes, directory bookmarks, git, docker and SSH hosts, sourced into interactive shells

Dotfiles: myconfigs¶

myconfigs backs up, restores and provisions configuration on the macOS and Linux machines that run the fleet: shell, terminal, editor, git and cloud tool settings, among others. It runs on the host, not in the container. The container sees only the host directories that its compose file mounts, such as the shared shell aliases directory.

Sources¶

skillset README.md
pi-devbox README.md ("Agent skills"), rootfs/usr/local/share/pi-devbox/skills/VENDORED.md, rootfs/usr/local/share/pi-devbox/pi-global-AGENTS.append.md
pi-toolkit pi-global-AGENTS.md
cli_utils README.md and bin/
myconfigs README.md