GuidesHosting choices

Pi agent skills and subagents: where they live, how they run

Where the Pi coding agent loads skills from, /skill:name, pi install and project trust, and how to add subagents, which Pi doesn't build in.

November 18, 2026The Everpod team
The short answer

Pi reads skills in the open Agent Skills format (a folder with a SKILL.md) from ~/.pi/agent/skills/ and ~/.agents/skills/ for you, and from a project’s .pi/skills/ and .agents/skills/ once you trust that project. The model sees each skill’s name and description and reads the file when a task matches; you can force one with /skill:name. Shared skills come as packages, through pi install. Sub-agents are not built in: Pi’s README says it “skips features like sub-agents and plan mode.” The nearest thing from Pi’s makers is the subagent example extension shipped with Pi 1.5.2, which adds a subagent tool that runs each named agent as a separate pi process with its own context, alone, in parallel or in a chain.

Where Pi looks for skills

As of version 1.5.2, from Pi’s skills page and its loader’s source:

FolderRead
~/.pi/agent/skills/
Always (moves with PI_CODING_AGENT_DIR)
~/.agents/skills/
Always
.pi/skills/
In the folder you start Pi in, once the project is trusted
.agents/skills/
In that folder and each parent up to the repository root (the folder holding .git), once trusted
Paths in the skills list of settings.json
With that settings file
Installed packages
A user package always; a project package once trusted
pi --skill <path>
For that run

The parent walk is the detail that differs from most agents: a skill in .agents/skills/ at the top of a monorepo is found when you start Pi in a subfolder, while .pi/skills/ is read only in the folder Pi starts in. Inside a skills folder Pi searches subfolders for SKILL.md, stops descending once it finds one, skips dot-folders and node_modules, and respects .gitignore, .ignore and .fdignore. It also accepts “some standalone Markdown skills,” in the docs’ words, but a folder with SKILL.md is the form other agents read too.

When two skills share a name, the first one found wins and Pi prints a name "…" collision warning; your own folders are read before the project’s. Run /reload after editing a skill mid-session. pi -ns (--no-skills) starts a run with none, though a --skill path given on the same line still loads.

The format, and what Pi enforces

Pi follows the Agent Skills specification: what agent skills are covers the file itself and how the same skill behaves in Claude Code, Codex and OpenCode. Pi’s own handling, from its source:

How a skill gets used

At start-up Pi adds an <available_skills> block to the system prompt with each skill’s name, description and file path, introduced by “Use the read tool to load a skill’s file when the task matches its description.” There is no skill tool: the model opens SKILL.md with Pi’s ordinary read, so the description is the whole of what decides whether it does.

To use one yourself, type /skill: and the name, with the request after it:

/skill:sql-migration add a nullable email column to users
Copied

Pi replaces the command with the skill’s body, wrapped in a <skill> tag that carries its location, and puts your text after it. The /skill: commands are listed in the command menu while enableSkillCommands is on, which is the default. In Pi’s source the expansion sits in the session code every mode shares, so a scripted pi -p "/skill:name …" is expanded the same way.

Installing skills other people wrote

Skills are shared as Pi packages, the same unit that carries extensions, prompt templates and themes. Pi’s packages page:

pi install npm:@example/pi-tools@1.0.0
pi install git:github.com/example/pi-tools@v1
pi install ./local-package
pi install -l npm:@example/pi-tools@1.0.0   # this project only
Copied

A package names its skill folders in the pi key of its package.json (for example "skills": ["./resources/skills"]); without that key, Pi picks up a skills/ folder in the package. With -l, the package is recorded in the project’s .pi/settings.json, and “Project packages are installed and loaded only after project trust is resolved.” pi config turns single resources from a package on or off.

A plain skills repository can also simply be cloned into a skills folder. That is how badlogic/pi-skills, one of the two collections Pi’s skills page points to, says to install it: git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills for every project, or into .pi/skills/pi-skills for one.

A package can carry an extension as well as skills, and an extension runs code inside Pi with your permissions the moment it loads; Pi’s page puts it as “Packages can execute extension code and can include skills that instruct the model to run programs.” The Pi extensions guide covers what that reaches and what to check before installing.

Project skills and trust

A project’s .pi/skills/ and .agents/skills/ load only after you trust the project, as do its extensions and packages. Pi’s skills page says to “Review unfamiliar skills and their supporting files before granting project trust,” because a skill is instructions the model follows with your access, often with scripts beside them. /trust saves the decision for later runs.

On a server, where Pi runs from a script or a timer, the security page is exact: “Print, JSON, and RPC modes cannot show the built-in trust prompt.” With the default defaultProjectTrust: "ask" the project’s skills are skipped in such a run. Either trust the project once in an interactive session with /trust, pass --approve for the one run, or keep the skills an unattended job needs in ~/.agents/skills/, which loads regardless.

Sub-agents: what Pi offers instead

Pi has no sub-agent feature. Its README says it “skips features like sub-agents and plan mode,” and its home page offers three routes instead: “Spawn Pi instances via tmux, or build your own with extensions, or install a package that does it your way.” Pi’s makers ship one such extension themselves, as an example: the subagent extension in the repository’s examples/extensions/, which also comes inside the npm package of Pi itself. Its neighbour plan-mode/ is described in the same list as “Claude Code-style plan mode.”

What the subagent extension does, as of 1.5.2:

An agent file, in the form the example’s README gives:

---
name: my-agent
description: What this agent does
tools: read, grep, find, ls
model: claude-haiku-4-5
---

System prompt for the agent goes here.
Copied

name and description are required, or the file is skipped. tools becomes the child’s --tools allowlist; without it the child has Pi’s default tools. Without model, the sub-agent “inherits the dispatching session’s active model and thinking level.”

It is not installed by pi install. The README has you run its commands from the root of a checkout of Pi’s repository, symlinking index.ts and agents.ts into ~/.pi/agent/extensions/subagent/, the agent files into ~/.pi/agent/agents/ and the prompts into ~/.pi/agent/prompts/, so the links break if that checkout moves. Copying the files instead of linking them keeps them, at the cost of updating them by hand.

If you want Claude Code’s sub-agents

The example covers the core of what Claude Code’s sub-agents do, a named agent with its own prompt, tools and model working in a separate context, and differs in ways that matter once it is in use:

The tmux route Pi’s home page names is the low-tech alternative: start further pi sessions in other tmux windows yourself, which keeps each one visible but leaves the hand-off to you. Which of these is enough depends on how much you leaned on sub-agents; Pi against Claude Code weighs that difference with the others, and what the Pi coding agent is covers installing it. Tools from outside, rather than instructions, come through MCP servers in Pi.

Run the Pi coding agent on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.