Prompt templates

Two flavours

A prompt template is a slash command. The filename without extension becomes the command name. The simplest version is a Markdown file with a prompt body; for anything that needs argument parsing, custom UI, or background work, use a TypeScript module instead.

Where they live

~/.omp/agent/commands/<name>.md           # global, markdown
~/.omp/agent/commands/<name>/index.ts     # global, typescript
.omp/commands/<name>.md                   # project, markdown
.omp/commands/<name>/index.ts             # project, typescript
 
# also discovered:
~/.claude/commands/  .claude/commands/
~/.codex/commands/   .codex/commands/

Project commands shadow global commands of the same name. Run omp -p '/extensions' to see what loaded.

Markdown templates

A Markdown command is YAML frontmatter plus a prompt body. The body becomes the user message when the command is invoked. Positional args are $1, $2, …; the joined remainder is $@ or $ARGUMENTS.

---
description: Review a PR with a structured checklist
---
 
Review pull request #$1.
 
Focus areas (from `$@`):
 
1. Correctness — logic errors, off-by-ones, wrong return paths.
2. Security — injection, authn/authz, secret handling.
3. Performance — N+1, allocations on hot paths, blocking I/O.
4. Tests — new code paths covered, no flakiness or hidden mocks.
 
Use `gh pr view $1 --json title,body,files` to start, then
`gh pr diff $1` for the patch. Surface findings inline with file:line.

Invoke it with /review-pr 482 --focus security. $1 resolves to 482, $@ resolves to --focus security.

Frontmatter

Field	Effect
`description`	One-line summary shown in `/` autocomplete. Falls back to the first non-empty body line.
`name`	Override the command name (honored for `.codex`/OpenCode-style command files; OMP-native commands use the filename).

TypeScript modules

When you need to parse arguments, prompt the user, run shell commands, or render custom UI, use a TS module instead. Default-export a factory that receives the custom-command API and returns the command definition (or an array of them).

// ~/.omp/agent/commands/changelog/index.ts
import type { CustomCommandAPI } from "@oh-my-pi/pi-coding-agent"
 
export default function (pi: CustomCommandAPI) {
  return {
    name: "changelog",
    description: "Summarise recent commits into CHANGELOG bullets",
    async execute(args: string[], ctx) {
      const range = args[0] || "HEAD~10..HEAD"
      const log = await pi.exec("git", ["log", "--oneline", range], {
        cwd: pi.cwd,
      })
      if (log.code !== 0) {
        ctx.ui.notify("git log failed: " + log.stderr, "error")
        return
      }
      // Returning a string sends it as the prompt for this turn.
      return `Summarise these commits as CHANGELOG bullets, grouped by Added / Changed / Fixed:\n\n${log.stdout}`
    },
  }
}

The factory can return more than one command. Return an array of them.rning undefined from execute means the command handled everything itself (no prompt is sent). For custom UI, message renderers, and keyboard shortcuts, write a plugin instead. See Hooks for the related lifecycle API and Skills when you want on-demand playbooks rather than a fixed prompt.

Invocation

All templates surface in the / autocomplete picker in interactive mode. From the CLI, pass the slash command as your prompt: omp -p '/review-pr 482'. See Slash commands for the picker, history, and built-in command reference.