Authors custom system prompt additions for pi coding agent. Pi provides a default system prompt with identity, tools, and guidelines. This skill covers what to add via SYSTEM.md (replace default) or APPEND_SYSTEM.md (extend default).
How Pi's System Prompt Works
Pi builds the system prompt dynamically: identity → tools → guidelines → docs → append → context → skills → metadata.
SYSTEM.md replaces the default. APPEND_SYSTEM.md extends it.
Locations: .pi/SYSTEM.md (project), ~/.pi/agent/SYSTEM.md (global), or --system-prompt (CLI).
See detailed prompt structure for full construction order, tool listing, skills format, and context file loading.
Section 1: Core Principles (Optional)
Define coding standards and architectural preferences. Common categories: simplicity, code quality, codebase health, build verification, security.
See example principles for working examples.
Section 2: Behavioral Guidelines (Optional)
Enforce specific behaviors: debugging, architecture, testing, scope, error handling, documentation, user directives.
See example guidelines for working examples.
Section 3: Custom Tool Usage Guidelines (Optional)
Add usage patterns for custom tools from extensions. Built-in tools are auto-documented.
See example tool guidelines for working examples.
Section 4: Project-Specific Context (Optional)
Add project conventions not covered by AGENTS.md/CLAUDE.md.
See example project context for working examples.
Architectural Patterns
Use APPEND_SYSTEM.md for extensions: Don't replace pi's default unless necessary. Append custom principles to preserve built-in functionality.
Use SYSTEM.md for replacements: Only if you need to fundamentally change pi's behavior.
XML tags for organization: Use <section_name> tags to organize principles logically.
Concise, value-based rules: "Scope is sacred" not "When asked to do X, only touch files that Y".
No procedural details: Avoid code snippets, variable names, or step-by-step scenarios.
Validation Checklist
Before finalizing:
- No duplication of pi's default (identity, date, tools, skills)
- Principles are concise and value-based, not procedural
- XML tags used for logical organization
- No code snippets or variable names in principles
- Custom tool guidelines only for extension-specific tools
- Project context only for non-obvious conventions
- File placed correctly:
SYSTEM.md(replace) orAPPEND_SYSTEM.md(extend) - No political, ethical, or moral points — these are not relevant and should not be in system prompts
- Focus on agent accountability and factuality — these are the only behavioral values that belong in system prompts