Skip to content
Get packs

Guide · Agent skill

How to use the Pi Agent Builder agent skill (pi-agent)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The pi-agent skill teaches an AI agent how to install, configure and build on Pi, a minimal coding harness that runs in the terminal. This guide is for readers who have not used agent skills before. By the end you will know how to add the skill, ask for Pi work in plain language, and what the skill needs and where its risks are.

Pi Agent BuilderK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it so the skill folder is available locally.
  2. 2Place the folder. Move the unzipped folder into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
  3. 3Install Pi. Make sure Node.js 22.19 or newer and npm are present, then install the @earendil-works/pi-coding-agent package with npm.
  4. 4Ask for a Pi task. Describe what you want in plain language, such as setting up a provider or writing an extension. The agent should load the skill when the request matches it.
  5. 5Check the result before running it. Review any scripts, extensions or commands the agent produces, since they run with the permissions of the Pi process.

What the pi-agent skill makes the agent do

Pi is a minimal terminal coding harness. It is extended through TypeScript extensions, skills, prompt templates, themes, packages, custom models and providers, SDK integrations, RPC mode, JSON event streams and TUI components.

With this skill installed, the agent knows Pi's setup steps, settings, model and provider configuration and environment variables. It can also help build extensions, packages, SDK or RPC integrations and local llama.cpp models. The skill points the agent to a specific reference file for each task rather than asking it to guess from memory.

Install the pi-agent skill

Download the ZIP from this page and unzip it. You have two options. For a personal setup, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. Alternatively, in the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

  • Personal: unzip into ~/.claude/skills/
  • Single project: unzip into the project's .claude/skills/
  • Claude apps: upload the ZIP under Settings → Capabilities → Skills

Install Pi itself so the skill has something to work with

The skill covers Pi, so Pi must be installed for the agent's advice to be useful. The skill's compatibility notes say it requires Node.js 22.19 or newer and npm. Pi's package name is @earendil-works/pi-coding-agent. The skill's own command list installs it globally with the flag shown below, then starts Pi by running pi.

  • Requires Node.js 22.19 or newer and npm
  • Package: @earendil-works/pi-coding-agent
  • Provider API keys or an OAuth login are needed for the models you choose
npm install -g --ignore-scripts @earendil-works/pi-coding-agent pi

Trigger the skill with natural requests

You do not need special syntax. Describe the Pi task in plain language, and the agent should load the skill when the request matches its description. Requests can be about installing Pi, setting providers or models, writing a Pi extension, embedding Pi in a Node or TypeScript app, driving Pi from another language, or using ecosystem packages such as pi-subagents, pi-mcp-adapter, pi-interview or pi-web-access.

The skill's description lists the areas it covers, so naming one of them in your request helps. Examples of requests that match are given in the use cases below.

  • Set up Pi with a specific provider and model
  • Write a custom Pi extension that adds a tool
  • Connect MCP servers to Pi
  • Stream Pi events as JSON in a shell pipeline

Use the reference map behind the skill

The skill ships reference files and routes each task to one of them. The files listed with this skill cover compaction, containerization, custom providers, development, environment variables, extensions, JSON output, keybindings, local llama.cpp models, MCP, models, the overview, packages, pi-interview and SKILL.md itself. Knowing these names helps you check what the agent read when it answers.

  • references/extensions.md for custom tools, commands and hooks
  • references/custom-provider.md for building custom providers
  • references/llama-cpp.md for local llama.cpp models
  • references/mcp.md for MCP servers
  • references/environment-variables.md for setting variables

Safety, requirements and what the skill does not do

The skill runs scripts and uses the network. Pi is local and not sandboxed by default. Extensions, packages, skills and shell commands run with the permissions of the Pi process. Project trust only controls which project inputs load and is not a sandbox. For untrusted repositories or unattended automation, the skill's guidance is to isolate Pi, for example with Docker, a VM or a remote sandbox.

The skill also advises against storing secrets in project files. Prefer environment variables, ~/.pi/agent/auth.json, OAuth via /login, or command-backed secret lookups in models.json or provider config.

  • Runs scripts: yes. Uses network: yes.
  • Do not run untrusted repos without isolation.
  • Do not put API keys in project files.
  • The skill is not useful if you only want a general coding assistant and have no interest in Pi.

What people use it for

  • Install Pi and configure a provider, model and environment variables for a development machine.
  • Write a custom Pi extension that adds a tool or command handler.
  • Embed Pi in a Node or TypeScript app using the SDK, or drive it from another language over RPC or JSON event streams.
  • Run local models through the llama.cpp router and connect MCP servers or pi-web-access for web search and fetching.

Frequently asked questions

Is the pi-agent skill free to use?

The skill is published under the MIT licence. Pi itself is installed from npm, and you still need provider API keys or an OAuth login for the models you choose, which may have their own costs.

What do I need before using the pi-agent skill?

You need Node.js 22.19 or newer, npm, and the @earendil-works/pi-coding-agent package. You also need provider API keys or an OAuth login for any hosted model you plan to use.

Where do I put the pi-agent skill folder?

Unzip the downloaded ZIP into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills instead.

Does the pi-agent skill run code on my machine?

Yes. The skill runs scripts and uses the network, and Pi is not sandboxed by default. Anything Pi runs has the same permissions as the Pi process, so review extensions and commands before you run them.

Should I use this skill for untrusted repositories?

The skill's guidance is not to, unless you isolate Pi first. Project trust only controls which project inputs load and is not a sandbox. Options named in the skill include Docker, OpenShell, Gondolin, a VM or a remote sandbox.

How is this different from a general coding assistant?

The skill is specific to Pi. It gives the agent Pi's setup steps, settings, provider configuration and extension APIs. If you have no interest in Pi, a general coding assistant without this skill is likely a better fit.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use the pi-agent skill if you are installing, configuring or building on the Pi terminal coding agent, or embedding it in an app via the SDK, RPC or JSON output. Skip it if you only want a general coding assistant or plan to run untrusted code unattended, since Pi is not sandboxed by default.

Download the skill