# Skills & prompts

Skills package your method; prompts name the shape of what comes out.

## Skills

A skill is a focused procedure stored in a `SKILL.md` file. It can explain how
to investigate an incident, review a contract, apply a support policy, or use a
particular tool safely. Keeping that guidance in a skill makes the agent's core
instructions shorter and lets several agents share the same procedure.

```text
skills/
  investigate-incident/
    SKILL.md
    references/
    scripts/
```

The skill's frontmatter `description` is what the model reads when deciding
whether to load it, so write it as the trigger condition rather than as a
title. Recipes adds nothing to the format: these are
[Agent Skills](https://agentskills.io/specification) as
[Pi loads them](https://pi.dev/docs/latest/skills), one directory per skill
with a `SKILL.md` inside.

The recipe manifest declares which skill resources belong to the package. Each
[agent definition](/recipes/agents) then selects skills by the skill's name —
its frontmatter `name`, defaulting to the skill's directory name — never by
path — so an agent with no `skills` key gets none. The example above declares
no `name`, so agents select it as `investigate-incident`. Selection controls
what guidance is presented to the agent; it is not a security boundary.

## Prompts

A prompt template names a deliverable once, so every run comes out in the same
shape. The filename is the command name:

```md filename="prompts/brief.md"
---
description: Write a sourced brief on an account
argument-hint: <account name>
---

Write a brief on $1.

## Positioning
What they sell, to whom, in their own words.

## Three proof points
Each with a source and a date.
```

These are ordinary [Pi prompt templates](https://pi.dev/docs/latest/prompt-templates);
Recipes adds no second mechanism, so one template is both a slash command in
the TUI (`/brief "NordStream Media"`) and a string you pass to
`session.prompt()` from a host. Arguments are parsed bash-style: `$1`/`$2` are
positional, `$ARGUMENTS` joins them all, and `${1:-default}` supplies a
fallback.

## Where each belongs

A skill is how the work is done, and the model decides when to load it. A
prompt is what you asked for, and you invoke it by name. A rule that must hold
on every run regardless of the request belongs in `SYSTEM.md`. Deterministic
runtime behavior belongs in an [extension](/recipes/extensions-and-tools) or
script.

They differ in how they are scoped, too. A skill is selected per agent, through
that agent's `skills` list, so two agents in one recipe can see different sets.
Prompts have no such per-agent selection: a prompt in the package is invocable
across the recipe. If a procedure has to be available to one agent and withheld
from another, that is a skill, not a prompt.

Skills and prompts are ordinary versioned recipe files, so changes move
through review, local proof, and deployment with the rest of the agent
behavior. See the
[Recipes documentation](https://pi.recipes/docs/skills-and-prompts)
for the current package contract.

Skills & prompts

Skills package your method; prompts name the shape of what comes out.

Skills

A skill is a focused procedure stored in a SKILL.md file. It can explain how to investigate an incident, review a contract, apply a support policy, or use a particular tool safely. Keeping that guidance in a skill makes the agent’s core instructions shorter and lets several agents share the same procedure.


skills/
  investigate-incident/
    SKILL.md
    references/
    scripts/

The skill’s frontmatter description is what the model reads when deciding whether to load it, so write it as the trigger condition rather than as a title. Recipes adds nothing to the format: these are Agent Skills as Pi loads them , one directory per skill with a SKILL.md inside.

The recipe manifest declares which skill resources belong to the package. Each agent definition then selects skills by the skill’s name — its frontmatter name, defaulting to the skill’s directory name — never by path — so an agent with no skills key gets none. The example above declares no name, so agents select it as investigate-incident. Selection controls what guidance is presented to the agent; it is not a security boundary.

Prompts

A prompt template names a deliverable once, so every run comes out in the same shape. The filename is the command name:

prompts/brief.md


---
description: Write a sourced brief on an account
argument-hint: <account name>
---
 
Write a brief on $1.
 
## Positioning
What they sell, to whom, in their own words.
 
## Three proof points
Each with a source and a date.

These are ordinary Pi prompt templates ; Recipes adds no second mechanism, so one template is both a slash command in the TUI (/brief "NordStream Media") and a string you pass to session.prompt() from a host. Arguments are parsed bash-style: $1/$2 are positional, $ARGUMENTS joins them all, and ${1:-default} supplies a fallback.

Where each belongs

A skill is how the work is done, and the model decides when to load it. A prompt is what you asked for, and you invoke it by name. A rule that must hold on every run regardless of the request belongs in SYSTEM.md. Deterministic runtime behavior belongs in an extension or script.

They differ in how they are scoped, too. A skill is selected per agent, through that agent’s skills list, so two agents in one recipe can see different sets. Prompts have no such per-agent selection: a prompt in the package is invocable across the recipe. If a procedure has to be available to one agent and withheld from another, that is a skill, not a prompt.

Skills and prompts are ordinary versioned recipe files, so changes move through review, local proof, and deployment with the rest of the agent behavior. See the Recipes documentation for the current package contract.