Pi native reference
Start with the Pi setup.
Native mappings
Instructions
- Pi reads instruction files along the path from the filesystem root to its current directory.
- A scoped rule at
services/api/AGENTS.mdreaches a session started there. A root session that reads a file inservices/api/does not load it. - In one directory, Pi takes the first readable file of
AGENTS.override.md,AGENTS.md,AGENTS.MD,CLAUDE.md,CLAUDE.MD. - See Pi configuration.
Skills
SKILL.mdmetadata and bundled files stay in.pi/skills/.- Pi also discovers shared
.agents/skills/directories. It keeps the first skill for a duplicate name, so a user-level skill can win over the project copy.
Commands
- Commands become prompt templates in
.pi/prompts/, withdescriptionandargument-hintfrontmatter. - Pi expands
$ARGUMENTS,$@, and positional arguments in bodies. Sync keeps that text as written. - See prompt templates.
MCP
Entries live under mcpServers in .pi/mcp.json (Pi MCP).
- Stdio:
command,args,env, optionalcwd. HTTP:url, optionalheaders. - Portable
disabled: truebecomes nativeenabled: false. - Sync accepts a leading UTF-8 byte order mark (BOM) in native MCP files and keeps it when updating.
- Pi reads
timeoutin seconds. The spec holds milliseconds, so sync divides by 1000 exactly (1500 becomes 1.5) and import multiplies by 1000. - A value under 1000 gets a note, since it most likely holds seconds.
x-pi.timeoutis already seconds, must be positive, and wins.- Environment placeholders stay literal. Native extras belong under
x-pi. toolExposurepatterns keep source order. Exact tool names take priority over patterns.
Settings
- Portable
modelbecomesdefaultModel.effortbecomesdefaultThinkingLevel. - Pi accepts
off,minimal,low,medium,high,xhigh,max. - Choose a provider with native
x-pi.defaultProvider. Sync does not split model IDs. - Unrelated settings stay in place.
Global configuration
agnostic-ai sync --global -t pi writes instructions, skills, MCP, and settings under ~/.pi/agent/. See global configuration.
PI_CODING_AGENT_DIRreplaces the whole agent directory.- Global HTTP MCP entries also keep
x-pi.auth: {provider: radius}. Pi limits provider auth to globalmcp.jsonand extensions (release reference), so project output omits it. - Existing
x-pi.oauthstays separate. - Global import scopes
authunderx-pi, so equal native entries can be adopted without rewriting user content.
Config keys
For the shared root instruction file, see entry-point files.
| Key | Default |
|---|---|
outputs.pi.rules-file | unset, uses instruction files |
outputs.pi.skills-dir | .pi/skills |
outputs.pi.commands-dir | .pi/prompts |
outputs.pi.mcp-file | .pi/mcp.json |
outputs.pi.conf-file | .pi/settings.json |
Changing a path does not change where Pi looks. Keep overrides aligned with your native configuration.
Import
agnostic-ai import pi
agnostic-ai lint
agnostic-ai sync -t pi
agnostic-ai sync --check -t pi
Import reads root and scoped instructions, skill folders and resources, direct prompt templates, .pi/mcp.json, and .pi/settings.json.
- Native MCP
enabledis inverted back to portabledisabled. - Project control-only overrides import with
targets: [pi]. - Model and thinking level become portable settings.
defaultProviderstays underx-pi. agnostic-ai import --global pireads supported user-level files.