# Skills & prompts

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

A **skill** is a `SKILL.md` procedure in your recipe that the model loads when
its description matches the work. A **prompt template** is a named deliverable
the user runs as a slash command.

**You need:** a recipe ([Create a recipe](/build)).

## 1. Write the skill

Create `skills/<name>/SKILL.md`. Write `description` as the trigger condition,
not a title: it is all the model sees before loading the skill.

```md filename="skills/refund-policy/SKILL.md"
---
description: Use when deciding whether an order qualifies for a refund.
---

# Refund policy

1. Read the order record and the current policy in references/policy.md.
2. Name the rule that controls the decision and the evidence for it.
3. Escalate fraud, chargebacks, and conflicting records.
4. Start the answer with `Decision: approve`, `decline`, or `escalate`.
```

Put long references and scripts beside it (`skills/refund-policy/references/`,
`scripts/`). Skills follow the [Agent Skills](https://agentskills.io/specification)
format, as [Pi loads them](https://pi.dev/docs/latest/skills).

## 2. Select it in an agent

The name is the frontmatter `name`, or the directory name. An agent with no
`skills` key gets none.

```yaml filename="agents/agent.yaml"
skills:
  - refund-policy
```

## 3. Add a prompt template

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.
```

Run it as `/brief "Acme Corp"`. `$1`, `$2` are positional, `$ARGUMENTS` joins
them all, and `${1:-default}` sets a fallback. See
[Pi prompt templates](https://pi.dev/docs/latest/prompt-templates).

## Verify

```bash
introspection check
introspection local -p "Can order 1842 be refunded?"
```

Expect the session to read `skills/refund-policy/SKILL.md` before answering.

## Choose where an instruction goes

| Put it in | When |
| --- | --- |
| `SYSTEM.md` | It must hold on every run. |
| A skill | It is how a kind of work is done; the model decides when to load it. |
| A prompt | It is what the user asks for, by name. |
| A [tool or hook](/build/tools) | It must be deterministic. |

Skills are selected per agent; prompts are available to every agent.

## Limits

| Not supported | Do this instead |
| --- | --- |
| Hiding a procedure from an agent as a security boundary | Skill selection controls what the agent sees, not what it can do. Enforce rules in a [hook](/build/sandbox#block-a-tool-call). |
| Hiding a prompt from one agent | Make it a skill and select it only where it belongs. |

Or ask your agent: "Turn our refund policy doc into a skill for the main agent and test an approve and an escalate case locally."

Skills & prompts

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

A skill is a SKILL.md procedure in your recipe that the model loads when its description matches the work. A prompt template is a named deliverable the user runs as a slash command.

You need: a recipe (Create a recipe).

1. Write the skill

Create skills/<name>/SKILL.md. Write description as the trigger condition, not a title: it is all the model sees before loading the skill.

skills/refund-policy/SKILL.md


---
description: Use when deciding whether an order qualifies for a refund.
---
 
# Refund policy
 
1. Read the order record and the current policy in references/policy.md.
2. Name the rule that controls the decision and the evidence for it.
3. Escalate fraud, chargebacks, and conflicting records.
4. Start the answer with `Decision: approve`, `decline`, or `escalate`.

Put long references and scripts beside it (skills/refund-policy/references/, scripts/). Skills follow the Agent Skills format, as Pi loads them .

2. Select it in an agent

The name is the frontmatter name, or the directory name. An agent with no skills key gets none.

agents/agent.yaml


skills:
  - refund-policy

3. Add a prompt template

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.

Run it as /brief "Acme Corp". $1, $2 are positional, $ARGUMENTS joins them all, and ${1:-default} sets a fallback. See Pi prompt templates .

Verify


introspection check
introspection local -p "Can order 1842 be refunded?"

Expect the session to read skills/refund-policy/SKILL.md before answering.

Choose where an instruction goes

Put it in	When
`SYSTEM.md`	It must hold on every run.
A skill	It is how a kind of work is done; the model decides when to load it.
A prompt	It is what the user asks for, by name.
A tool or hook	It must be deterministic.

Skills are selected per agent; prompts are available to every agent.

Limits

Not supported	Do this instead
Hiding a procedure from an agent as a security boundary	Skill selection controls what the agent sees, not what it can do. Enforce rules in a hook.
Hiding a prompt from one agent	Make it a skill and select it only where it belongs.

Or ask your agent: “Turn our refund policy doc into a skill for the main agent and test an approve and an escalate case locally.”