Skip to main content
Version: Next

Agent Skill

poof ships an official agent skill: a portable instruction file that teaches AI coding agents how to install and manage pre-built software with poof. Once installed, you can ask your agent things like "install BurntSushi/ripgrep with poof" instead of running the commands yourself.

The skill follows the Agent Skills specification and lives in the poof repository at skills/poof/SKILL.md. It is installed with the skills CLI (npx skills), which supports pi, Claude Code, and many other coding agents.

tip

The agent skill is for interactive AI assistants. For CI pipelines, use the GitHub Action instead.

What the skill does​

When loaded, the skill gives your agent:

  • The full poof workflow - detect poof and its version (poof -V), bootstrap it if missing, install a tool, verify the result, then manage versions and PATH.
  • Complete command coverage - install, download, list, which, what, use, update, unlink, uninstall, enable, check, completions, init, clean, info, and version.
  • Correct syntax - OWNER/REPO slugs, --tag pinning (not the Action's @tag form), supported shell names, and confirmation flags.
  • Safety rules - see Safety model below.
  • Version awareness - see Version compatibility below.

Version compatibility​

Commands were introduced over time, so a command available in the latest poof may not exist in an older installation. The skill bundles a command-introduction table, verified against poof's release tags, and compares it with the short version from poof -V before using a command. If your poof is too old, the agent reports the minimum version and offers to update poof instead of running a command that cannot work. For example, poof what arrived in 0.6.0, so it is unavailable on 0.5.x.

Two checks work on every version:

  • poof help lists exactly the commands your binary supports.
  • Recent builds also print a Since: line in poof <command> --help, so the binary itself reports when each command was introduced.

Requirements​

  • Node.js 22.20 or later - required by the skills CLI used to install/manage the agent skill. This is separate from poof’s npm package, which supports Node.js 18 or later.
  • A coding agent supported by the skills CLI - for example pi or Claude Code.
  • poof - install it first (see Installation), or let the skill guide the bootstrap. poof itself runs on Linux and macOS; see Supported Platforms.

Install the skill​

From your project directory (project-scoped install):

npx skills add pirafrank/poof

The CLI lists the skills found in the repository and asks which ones to install and for which agents. Useful variants:

# Preview without installing anything
npx skills add pirafrank/poof --list

# Install the poof skill globally (available in all projects)
npx skills add pirafrank/poof --skill poof -g

# Non-interactive install for a specific agent
npx skills add pirafrank/poof --skill poof -a claude-code -y

# Pin to a release tag or commit that includes the skill
npx skills add pirafrank/poof@<tag-or-commit> --skill poof
note

npx skills add pirafrank/poof fetches the repository's default branch. The skill is only present in tags and commits that include it - older release tags predate the skill.

Where the skill is installed​

ScopeLocation
Project (default).agents/skills/poof/ in your project, with links for each selected agent (e.g. .claude/skills/)
Global (-g)~/.agents/skills/poof/, with links for each selected agent

pi reads both .agents/skills/ and ~/.agents/skills/ natively, so a skills CLI install works with pi without extra configuration. Use --copy instead of the default symlinks if your filesystem does not support them.

Project installs are recorded in skills-lock.json; commit it to share the same skill setup with your team.

tip

Review before you install: read the skill source or run npx skills add pirafrank/poof --list first. A skill is a set of instructions your agent will follow - treat it like any other code you run.

Use it​

Ask your agent in natural language, for example:

  • "Install BurntSushi/ripgrep with poof."
  • "Install sharkdp/fd pinned to v8.7.0."
  • "Switch the default ripgrep to 13.0.0."
  • "Update everything installed with poof."
  • "Add poof's bin directory to my zsh PATH."

In pi you can also force-load the skill explicitly:

/skill:poof install BurntSushi/ripgrep

Agentic workflow examples​

The skill is useful when the agent needs to inspect the environment, make a change, and report what happened. For example, ask:

Check whether poof is available and list the versions of sharkdp/fd that I have installed.
Don't install or update anything.

The agent should check command -v poof first. If poof is available, it can run poof -V and poof list sharkdp/fd; otherwise, it should report that poof is missing. In either case, it reports the result without installing or changing anything.

For an install request, name the exact repository and whether a version should be pinned:

Install BurntSushi/ripgrep with poof, pinned to 14.1.0. After I approve, verify which
binary poof provides and report the installed version.

The agent checks the installed poof version and command support, confirms the repository, asks before downloading/installing, then verifies with poof list, poof what, or poof which. It should not run the installed binary unless asked. Other useful requests include:

Which installed tool provides `fd`, and where does it resolve?
Show me the poof init command for this shell, but don't edit my startup files.
Update all tools managed by poof, but ask me before making changes.

To keep an install within the skill's user-space workflow, make that constraint explicit:

Use the poof skill to install BurntSushi/ripgrep in my user space. Confirm the repository and ask
before downloading; then report the installed version and binary path. Don't run the binary.

Using poof through the skill is safer than having an agent fetch, unpack, and install a binary on its own: poof keeps managed tools in user space and checks release assets and archives before installing them. The skill adds repository confirmation and approval before downloads, then guides the agent to verify the installed version and binary path. These checks reduce risk; downloaded software is still untrusted code, so decide separately whether to run it.

These examples illustrate the skill's approval rules: inspection can proceed directly, while downloads, updates, and persistent shell changes require approval first.

After installing or updating the skill, reload your agent (in pi: /reload) so it picks up the new instructions.

Safety model​

The skill encodes poof's user-space philosophy as explicit agent rules:

  • User-space only - never sudo, never system directories or system package managers.
  • Approval gates - the agent must ask before bootstrapping poof, installing or downloading anything, updating, uninstalling, cleaning the cache, or running poof enable (which edits a shell startup file). Read-only inspection (list, which, what, info, check, version) needs no approval.
  • Canonical sources only - bootstrap uses the official install.sh, downloaded and reviewed before running; no mirrors or proxy URLs.
  • Repository confirmation - the exact OWNER/REPO is confirmed with you before installing, to avoid typosquatting.
  • Untrusted assets - release binaries are treated as untrusted code; running an installed binary stays your decision.
  • Reproducibility - prefer --tag pinning when it matters.

Manage the skill​

npx skills list # show installed skills
npx skills check # check for available updates
npx skills update poof # update the poof skill
npx skills remove poof # remove the poof skill

Updates are fetched from the poof repository, so the skill stays in sync with the command documentation shipped in the repo.

Troubleshooting​

  • Agent doesn't see the skill - reload or restart the agent (in pi: /reload), then confirm with npx skills list that the skill is installed for that agent.
  • npx skills fails to run - check your Node.js version (node --version); the CLI requires 22.20 or later.
  • Verify what the repository offers - npx skills add pirafrank/poof --list prints the skill name and description without installing anything.
  • A command is unavailable - your poof may predate it; see Version compatibility. Update poof, then retry.
  • Questions or bugs - open an issue at pirafrank/poof.

See also​