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.
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:
| Folder | Read |
|---|---|
~/.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:
- No description, no skill. A
SKILL.mdwithout one is dropped with “description is required” in the startup diagnostics. - A bad name only warns. Capitals, spaces or doubled hyphens produce warnings such as “name contains invalid characters (must be lowercase a-z, 0-9, hyphens only)”, and the skill still loads. Pi does not warn when the name differs from the folder; other agents may refuse it.
disable-model-invocation: trueremoves the skill from the list the model sees; it is then used only when you call it.
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 usersCopiedPi 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 onlyCopiedA 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:
- It adds one tool,
subagent, that the model calls with an agent’s name and a task. Each call starts a separatepiprocess (--mode json -p --no-session), so the sub-agent works in its own context window and hands back only its result. - Three ways to call it: one agent; up to 8 tasks in parallel, 4 at a time; or a chain, each step given the previous one’s output.
- Agents are Markdown files in
~/.pi/agent/agents/, the frontmatter naming the agent and saying when to use it, the body its system prompt. - Four sample agents (scout, planner, reviewer, worker) and three prompts that chain them:
/implement,/scout-and-planand/implement-and-review.
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.Copiedname 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:
- Nothing is there by default. Claude Code ships general and Explore agents; in Pi there is no sub-agent until you add the extension or write your own.
- Project agents are off. Only your own
~/.pi/agent/agents/load unless a call asks foragentScope: "project"or"both"; then the nearest.pi/agents/above the working folder is read, and its agents override yours of the same name. Interactively the tool asks before running them. With no interface, as inpi -p, there is no one to ask and the source runs them without confirmation. - Cost is harder to see. A sub-agent’s usage shows in the tool’s details but is not added to the parent session’s totals, and each one is a full model run of its own.
- Output is capped at 50 KB or 2,000 lines for a single or chained call, with the full result kept in the tool’s details.
- Nothing is kept. Children run with
--no-session, an in-memory session, so a sub-agent’s own conversation is not saved; what remains is the result it handed back. - No permission prompts, as everywhere in Pi: a worker with the default tools can write and run what it likes as you.
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.