Skip to main content

​
Customization

Pi is designed to adapt to your workflow through prompt templates, skills, themes, and shareable packages. All customizations can be project-specific or global.

​
Prompt Templates

Reusable prompts as Markdown files with variable substitution.

​
Creating Templates

1

Create Template File

Create a .md file in:
  • ~/.pi/agent/prompts/ (global)
  • .pi/prompts/ (project-specific)
<!-- ~/.pi/agent/prompts/review.md -->
---
description: Code review with security focus
---

Review this code for:
- Security vulnerabilities
- Performance issues
- Best practices violations

Focus areas: $ARGUMENTS

Provide specific line numbers and suggested fixes.
2

Use Template

# In Pi:
/review authentication, input validation

# Or with file reference:
/review @src/auth.ts "session management"

​
Variable Substitution

Templates support bash-style argument substitution: 
<!-- prompts/greet.md -->
Hello, $1! Welcome to $2.
Usage:
/greet Alice "the project"
# Expands to: Hello, Alice! Welcome to the project.

​
Template Frontmatter

---
description: Brief description shown in autocomplete
custom-field: Any metadata you want
---

Template content here...

​
Loading Templates

# Templates in ~/.pi/agent/prompts/ load automatically
ls ~/.pi/agent/prompts/
# review.md, test.md, debug.md

​
Skills

On-demand capability packages following the Agent Skills standard.

​
Creating Skills

1

Create Skill Directory

mkdir -p ~/.pi/agent/skills/api-testing
cd ~/.pi/agent/skills/api-testing
2

Create SKILL.md

<!-- SKILL.md -->
---
name: api-testing
description: Test REST APIs with comprehensive validation
---

# API Testing Skill

Use this skill when the user asks to test an API endpoint.

## Steps

1. Read the API documentation or code
2. Identify endpoints, methods, and expected responses
3. Use bash tool to send requests with curl
4. Validate:
   - HTTP status codes
   - Response schema
   - Error handling
   - Edge cases
5. Generate test report

## Example

```bash
# Test authentication endpoint
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"test123"}'

​
Bundled Resources

See ./test-templates/ for reusable test scripts.
</Step>

<Step title="Add Resources (Optional)">
```bash
mkdir test-templates
echo '#!/bin/bash\ncurl -X GET "$1" -H "Accept: application/json"' > test-templates/get.sh
chmod +x test-templates/get.sh
Skills can reference bundled files using relative paths.

​
Skill Frontmatter

---
name: my-skill              # Must match directory name
description: What it does   # Required, shown to the model
disable-model-invocation: false  # If true, only /skill:name works
---
  • name: Lowercase, hyphens only, max 64 chars
  • description: Max 1024 chars, tells model when to use skill
  • disable-model-invocation: Prevents automatic loading (manual /skill:name only)

​
Using Skills

The model loads skills automatically when needed:
> "Test the /api/users endpoint"
> Model sees api-testing skill in available_skills
> Model uses read tool to load skill
> Model follows skill instructions

​
Skill Discovery

Skills are discovered from:
  1. ~/.pi/agent/skills/ (global)
  2. ~/.agents/skills/ (XDG standard)
  3. .pi/skills/ (project, from cwd upward)
  4. .agents/skills/ (project, XDG standard)
  5. Pi packages (see below)
Name collisions: Project skills override global skills.

​
Real-World Skill Example

<!-- ~/.pi/agent/skills/db-migration/SKILL.md -->
---
name: db-migration
description: Create and manage database migrations safely
---

# Database Migration Skill

Use when the user needs to modify database schema.

## Pre-flight Checks

1. Read current schema from `./prisma/schema.prisma` or `./migrations/`
2. Understand existing tables, columns, relationships
3. Check for:
   - Data loss risks (dropping columns/tables)
   - Constraint violations
   - Index requirements

## Migration Creation

1. Generate migration file in `./migrations/` with timestamp
2. Include both `up` and `down` SQL
3. Add comments explaining changes
4. Handle data transformations if needed

## Safety Rules

- **NEVER** drop columns without user confirmation
- **ALWAYS** use transactions when possible
- **ALWAYS** create backups for destructive changes
- **TEST** with sample data first

## Example Migration

```sql
-- migrations/20250303_add_user_email.sql
-- UP
BEGIN;
ALTER TABLE users ADD COLUMN email VARCHAR(255);
CREATE UNIQUE INDEX idx_users_email ON users(email);
COMMIT;

-- DOWN
BEGIN;
DROP INDEX idx_users_email;
ALTER TABLE users DROP COLUMN email;
COMMIT;

​
Bundled Tools

Use ./scripts/test-migration.sh to validate migrations against test database.

​
Themes

Customize Pi’s appearance with theme files.

​
Built-in Themes

  • dark (default)
  • light

​
Creating Custom Themes

1

Create Theme File

// ~/.pi/agent/themes/nord.ts
import { Theme } from '@mariozechner/pi-coding-agent';

export const theme: Theme = {
  name: 'nord',
  
  // Editor colors
  editor: {
    border: '#5E81AC',
    borderFocused: '#88C0D0',
    background: '#2E3440',
    text: '#ECEFF4',
    placeholder: '#4C566A',
  },
  
  // Message colors
  user: '#88C0D0',
  assistant: '#A3BE8C',
  system: '#EBCB8B',
  error: '#BF616A',
  
  // Tool colors
  tool: '#B48EAD',
  toolOutput: '#8FBCBB',
  
  // Thinking colors
  thinking: '#5E81AC',
  thinkingText: '#D8DEE9',
  
  // UI elements
  footer: {
    background: '#3B4252',
    text: '#ECEFF4',
    highlight: '#88C0D0',
  },
  
  // Syntax highlighting
  syntax: {
    keyword: '#81A1C1',
    string: '#A3BE8C',
    number: '#B48EAD',
    comment: '#616E88',
    function: '#88C0D0',
  },
};
2

Activate Theme

pi
/settings  # Select Themes > nord

# Or via settings.json:
{
  "theme": "nord"
}

# Or command line:
pi --theme ~/.pi/agent/themes/nord.ts

​
Hot Reloading

Themes hot-reload automatically. Modify the active theme file and see changes instantly in Pi.

​
Theme Locations

  • ~/.pi/agent/themes/ (global)
  • .pi/themes/ (project)
  • Explicit: pi --theme /path/to/theme.ts

​
Pi Packages

Bundle and share extensions, skills, prompts, and themes via npm or git.

​
Installing Packages

# Install from npm
pi install npm:@user/pi-tools

# Specific version
pi install npm:@user/[email protected]

# Project-local
pi install npm:@user/pi-tools -l

​
Managing Packages

# List installed packages
pi list

# Update packages (skips pinned versions)
pi update

# Update specific package
pi update npm:@user/pi-tools

# Remove package
pi remove npm:@user/pi-tools

# Configure (enable/disable resources)
pi config

​
Creating Packages

1

Initialize Package

mkdir my-pi-package
cd my-pi-package
npm init -y
2

Add Pi Manifest

// package.json
{
  "name": "my-pi-package",
  "version": "1.0.0",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}
3

Add Resources

mkdir -p skills/my-skill prompts themes

# Create skill
cat > skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Does something useful
---

# My Skill
Instructions here...
EOF

# Create prompt template
cat > prompts/template.md << 'EOF'
---
description: Quick template
---

Do something with $ARGUMENTS
EOF
4

Publish

# To npm
npm publish

# To GitHub
git init
git add .
git commit -m "Initial commit"
git tag v1.0.0
git push origin main --tags

​
Package Auto-Discovery

Without a pi field, Pi auto-discovers from conventional directories: 
my-package/
├── extensions/    # Auto-discovered
├── skills/        # Auto-discovered
├── prompts/       # Auto-discovered
└── themes/        # Auto-discovered

​
Finding Packages

Security Notice: Pi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action. Review source code before installing third-party packages.

​
Package Storage

  • Global: ~/.pi/agent/git/ (git), global npm
  • Project: .pi/git/, .pi/npm/ (with -l flag)

​
Configuration Files

​
Global vs Project

~/.pi/agent/ - Applies to all projects
~/.pi/agent/
├── settings.json        # Default settings
├── auth.json            # OAuth credentials
├── keybindings.json     # Custom shortcuts
├── models.json          # Custom model definitions
├── prompts/             # Global prompt templates
├── skills/              # Global skills
├── themes/              # Global themes
└── sessions/            # Session history

​
Environment Variables

# Override config directory
export PI_CODING_AGENT_DIR=~/.config/pi

# Override package directory (for Nix/Guix)
export PI_PACKAGE_DIR=/nix/store/...

# Disable version check
export PI_SKIP_VERSION_CHECK=1

# External editor
export VISUAL=code
export EDITOR=vim

​
Examples

# In your project
mkdir -p .pi/prompts .pi/skills/deploy

# Add deployment skill
cat > .pi/skills/deploy/SKILL.md << 'EOF'
---
name: deploy
description: Deploy application to production
---

# Deployment Skill

1. Run tests: `npm test`
2. Build: `npm run build`
3. Deploy: `./scripts/deploy.sh`
4. Verify: Check health endpoint
EOF

# Add prompt template
cat > .pi/prompts/pr.md << 'EOF'
---
description: Generate PR description
---

Generate a pull request description for:

$ARGUMENTS

Include:
- Summary of changes
- Testing steps
- Breaking changes (if any)
EOF

# Use them
pi
> /skill:deploy
> /pr "Add user authentication"

# Create team package
mkdir team-pi-tools && cd team-pi-tools
npm init -y

# Add team conventions
mkdir -p skills/code-review prompts

cat > skills/code-review/SKILL.md << 'EOF'
---
name: code-review
description: Review code following team standards
---

# Code Review Skill

Apply team standards from ./CONVENTIONS.md:
- TypeScript strict mode
- No any types
- Functional components
- Props interface naming
EOF

cat > prompts/commit.md << 'EOF'
Generate conventional commit message for: $ARGUMENTS

Format: type(scope): description
Types: feat, fix, docs, style, refactor, test, chore
EOF

# Publish to internal registry
npm publish --registry=https://npm.yourcompany.com

# Team members install
pi install npm:@yourcompany/team-pi-tools --registry=https://npm.yourcompany.com

Build docs developers (and LLMs) love

Get started for freeTalk to us