Prompt Authoring

Prompt authoring

Use this skill when the user wants a reusable slash prompt, workflow shortcut, or global/imported prompt template for parent Pi Agent sessions.

Runtime facts

• Prompt templates are Markdown files that expand when the user types /name in a parent Pi session.
• The filename is the invocation name: review-staged.md becomes /review-staged.
• Prompt templates are user-message macros, not system prompts and not skills.
• Agent Deck scans prompt templates into a catalog.
• Agent Deck parent sessions launch with --no-prompt-templates and pass only assigned templates with explicit --prompt-template <path> flags.
• Native subagents do not receive prompt templates.

Locations

Create reusable catalog prompts in Agent Deck's prompt library unless the user asks to keep an existing file elsewhere and import it by reference through Agent Deck’s + flow:

~/.pi/agent/prompt-library/<name>.md

Agent Deck no longer discovers project-local .pi/prompts or project settings prompts/package prompt sources as catalog resources. Global/default and project availability are Agent Deck assignments. Do not rely on ambient Pi prompt discovery. Import is by reference, not a copy.

Format

Use Markdown with optional frontmatter:

---
description: Short autocomplete description
argument-hint: "[optional-focus]"
---

Prompt body here.

Rules:

• Keep the description short and user-facing.
• Use argument-hint only when arguments are expected.
• If no arguments are needed, omit argument-hint and do not include placeholders.
• Make the body complete enough to be useful after expansion.
• Avoid hidden, broad, or permanent behavioral instructions; templates are one-shot user prompts.

Arguments

Supported placeholders:

$1, $2, ...        positional arguments
$@                 all arguments joined
$ARGUMENTS         all arguments joined
${@:N}             arguments from N onward, 1-indexed
${@:N:L}           L arguments starting at N

Examples:

---
description: Review a target with an optional focus
argument-hint: "<target> [focus]"
---

Review $1.

Focus on: ${@:2}

No-argument template:

---
description: Review staged git changes
---

Review the staged git changes with `git diff --cached`.

Focus on:
- bugs
- regressions
- missing tests

Authoring workflow

1. Choose a short kebab-case filename/invocation.
2. Decide whether the prompt needs arguments.
3. Write concise frontmatter.
4. Write a clear, self-contained prompt body.
5. Save it to the requested prompt catalog/source location.
6. Tell the user the invocation, file path, whether it expects arguments, and whether it still needs Default or Project assignment in Agent Deck.