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.
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, andversion. - Correct syntax -
OWNER/REPOslugs,--tagpinning (not the Action's@tagform), 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 helplists exactly the commands your binary supports.- Recent builds also print a
Since:line inpoof <command> --help, so the binary itself reports when each command was introduced.
Requirements
- Node.js 22.20 or later - required by the
skillsCLI 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
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
| Scope | Location |
|---|---|
| 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.
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/REPOis 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
--tagpinning 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 withnpx skills listthat the skill is installed for that agent. npx skillsfails 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 --listprints 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
- Installation - get poof itself
- Usage - poof command basics
- Shell Configuration - PATH and shell integration
- GitHub Action - poof in CI pipelines
- Features - what poof can do