Pi Roles — Development skill for Claude Code

pi-roles

Unified composable roles and dynamic skill scoping for Pi coding agent and subagents.

The Problem

1. Context Bloat: Loading 40+ skills into Pi injects thousands of tokens of XML descriptions into the system prompt on every turn. This wastes budget and degrades instruction following.
2. Harness Schizophrenia: Subagents get isolated roles and skill scoping, but the interactive main agent is stuck as an unspecialized generalist carrying every skill at once.
3. Monolithic Prompts: Teams write giant 600-line system prompts that try to do everything, instead of composing small, focused capabilities.

The Solution

**Define once. Run as the main agent, or dispatch as a subagent.**

                 ~/.pi/agent/agents/.md
                             │
            ┌────────────────┴────────────────┐
            ▼                                 ▼
   Main Agent (/role)                Subagent (subagent tool)
   Embody the role interactively      Dispatch to run in background
   Scoped skills & system prompt      Isolated child session

Features

• Composition over Inheritance: Roles can compose other roles via roles: [role-a, role-b]. Skills, tools, and instructions are recursively resolved and deduplicated.
• Dynamic Skill Scoping: When a role is active, only its declared skills appear in . Shrinks prompt overhead by up to 80%.
• On-Demand Skill Loading: Model can call load_skill to pull in an unlisted skill temporarily when an unexpected subtask arises.
• Startup Ergonomics:
  • CLI flag: pi --role architect
  • Project default: "defaultRole": "architect" in .pi/settings.json
  • Interactive TUI: type /role to open a keyboard-navigable role selector
• Full Subagent Compatibility: Standard Agent Markdown format compatible with pi-subagents.

Role Definition Format

Save roles to `~/.pi/agent/agents/.md` (global) or `.pi/agents/.md` (project):

--