Where Pi stores skills, prompts, rules, and settings

Pi (Mario Zechner’s deliberately minimal coding agent) keeps its global config under ~/.pi/agent/ — one directory deeper than the ~/.pi/ you’d guess — plus per-project .pi/ folders, and it speaks the same Agent Skills SKILL.md convention as Claude Code and Codex. ~ is your home directory; paths starting with .pi/ are relative to a project root.

At a glance

Artifact	Global	Per-project	Format
Skills	~/.pi/agent/skills/<name>/SKILL.md, ~/.agents/skills/	.pi/skills/, .agents/skills/ (cwd and parent dirs)	Markdown + YAML frontmatter
Context files (rules)	~/.pi/agent/AGENTS.md	AGENTS.md or CLAUDE.md (project root and parents)	Markdown
System prompt override	~/.pi/agent/SYSTEM.md, ~/.pi/agent/APPEND_SYSTEM.md	.pi/SYSTEM.md, .pi/APPEND_SYSTEM.md	Markdown
Prompt templates	~/.pi/agent/prompts/*.md	.pi/prompts/*.md	Markdown
Settings	~/.pi/agent/settings.json	.pi/settings.json (overrides global)	JSON
Extensions / themes	~/.pi/agent/{extensions,themes}/	.pi/{extensions,themes}/	TS / JSON
MCP servers	—	—	Pi has no built-in MCP

Global config lives in ~/.pi/agent/, not ~/.pi/

Everything global — settings, skills, prompts, sessions, trust decisions — sits under ~/.pi/agent/ (overridable with PI_CODING_AGENT_DIR). A backup or scan of a bare ~/.pi/ top level that doesn’t descend into agent/ finds nothing.

Skills

Pi loads Agent Skills natively: a folder with a SKILL.md whose frontmatter has name (lowercase, hyphens) and description (up to 1024 characters), plus optional allowed-tools and disable-model-invocation. It looks in ~/.pi/agent/skills/ and ~/.agents/skills/ globally, and .pi/skills/ and .agents/skills/ from the working directory up through parents — the same format Claude Code and Cursor use, so skills usually port with no changes at all. Skills (plus prompts, extensions, and themes) can also arrive bundled as pi packages installed from npm or git into ~/.pi/agent/{npm,git}/.

AGENTS.md context files

At startup Pi reads ~/.pi/agent/AGENTS.md, then AGENTS.md (or CLAUDE.md) from the project root and parent directories — all matching files are concatenated, not first-match. It’s the same cross-tool convention Codex, Cursor, and Claude Code read.

SYSTEM.md and APPEND_SYSTEM.md

SYSTEM.md replaces the entire default system prompt

.pi/SYSTEM.md (project) or ~/.pi/agent/SYSTEM.md (global) replaces Pi’s built-in system prompt wholesale — tool guidance included. APPEND_SYSTEM.md in the same locations appends instead. If you only want to add instructions, APPEND_SYSTEM.md is almost always the file you mean.

Prompt templates

Markdown files in ~/.pi/agent/prompts/ or .pi/prompts/ become slash commands — type /name to expand the file’s content into the conversation. These are Pi’s equivalent of Claude Code’s commands/ directory and Codex’s prompts/.

Settings and project trust

~/.pi/agent/settings.json is global; .pi/settings.json overrides it per project. Before loading a project’s .pi/ settings, resources, or .agents/skills, Pi asks you to trust the folder and records the decision in ~/.pi/agent/trust.json — untrusted projects get none of their local config executed. Sessions auto-save under ~/.pi/agent/sessions/.

No MCP — by design

Pi ships no MCP client. Its position is that CLI tools with good READMEs (wrapped as skills) cover most of what MCP servers do; an extension can add MCP support if you need it. Practically: there is no mcp.json to find, and MCP configs from other tools have nothing to convert into for Pi.

Seeing all of it at once

Quartermaster’s scanner walks every location on this page — including the ~/.pi/agent/ layer and the SYSTEM.md/APPEND_SYSTEM.md overrides — and indexes the artifacts into one searchable registry alongside Claude Code, Cursor, Codex, and 8 more tools. Because Pi uses the shared Agent Skills format, conversion to and from other tools is often a straight copy. Secrets are never indexed — env/header key names kept, values dropped. See the full discovery map or the quickstart.