prompt-template-authoring

Prompt Template Authoring

Use this skill when working on prompt templates for pi-prompt-template-model. Templates are markdown files that register as slash commands.

Where Templates Live

• ~/.pi/agent/prompts/ — user prompts (highest priority)
• .pi/prompts/ inside a trusted project — project-specific prompts

Extension examples/ are reference files only. Copy them to a prompt directory to register them.

Minimal Template

---
model: claude-sonnet-4-20250514
---
Your prompt body here.

Save as my-command.md, restart Pi, run /my-command. Use description: for autocomplete text.

Model Selection

Omit model: to inherit the current session model. Otherwise:

• model: claude-sonnet-4-20250514 — specific model
• model: claude-opus-4, gpt-5.4 — fallback order (tries first, falls back to second if unavailable)
• model: claude-opus-4, gpt-5.4 + rotate: true — cycle through list on each loop iteration

Argument Substitution

The prompt body can use placeholders:

• $@ — all arguments passed to the command
• $1, $2 — specific positional arguments
• ${@:1} — argument 1 and everything after

Deterministic Steps (Pre-LLM Execution)

Run a command or script before the LLM turn. The model only sees the output if you want it to.

Two equivalent forms. Don't mix them in the same prompt.

Shorthand form — top-level keys:

---
run: git status --short
handoff: always
---
Summarize the repo state.

Nested form — under deterministic::

---
deterministic:
  run: ./scripts/ship.sh
  handoff: on-failure
  timeout: 60000
---
Diagnose the failure and suggest a fix.

Handoff controls when the LLM sees the result:

• never — run, show result, done (no LLM turn)
• always — always hand result to model
• on-failure — only hand off if command exits non-zero
• on-success — only hand off if command exits zero

Execution forms:

• run: command string — runs via /bin/bash -lc
• run: {command: git, args: [status], shell: false} — explicit args, optional shell
• script: ./script.sh or script: {path: ./script.sh, args: [--fast]} — run a file