| name | pi-prompt-authoring |
| topic | Pi Prompt Authoring |
| description | Author SYSTEM.md or APPEND_SYSTEM.md for pi coding agent. Use when extending the default system prompt with custom principles, guidelines, or project rules. |
| token_cost | 350 |
| keywords | ["prompt","system","guideline","rule","principle","authoring"] |
Pi Prompt Authoring
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:
