Skills and prompts

Your method, and the shape of what comes out.

A skill is a procedure written down: the order to work in, what counts as evidence, the mistake to avoid. It loads only when a task calls for it.

skills/research/SKILL.md

---
name: research
description: Work an account from public and CRM sources
---

## Order of work

1. Read the CRM record first. It is the only source for
   relationship history.
2. Check the company's own site for positioning and pricing.
   Note the date on every page you use.
3. Search for funding and hiring signals last. They are the
   weakest evidence and the easiest to over-read.

## What counts as a source

A page you opened in this session, with a date. A summary of
a summary is not a source.

The description is what the model reads when deciding whether to load the skill, 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.

Declare, then select

package.json

{
  "pi": {
    "skills": ["skills/**/SKILL.md"]
  }
}

agents/agent.yaml

skills: [research]   # by the name in the frontmatter, not the path

The package declares which skills exist; each agent selects the ones its role needs. An agent with no skills key gets none, which is usually right for a narrowly scoped role. Omitting the manifest key entirely falls back to skills/**/SKILL.md, so one directory per skill is found without writing a glob.

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.

## Open questions
What you could not establish. Say so plainly.

These are ordinary Pi prompt templates. Recipes adds no second mechanism, so one template is both a slash command and a string you pass in.

TUI

/brief "NordStream Media"

SDK

// Pi expands the slash command and its arguments itself.
await handle.session.prompt('/brief "NordStream Media"');

// The templates a recipe contributed, by name.
const names = handle.session.promptTemplates.map((t) => t.name);

Placeholder	Expands to
`$1`, `$2`	The first, second positional argument
`$ARGUMENTS` or `$@`	Every argument, joined
`${1:-none given}`	The first argument, or a default when absent
`${@:2}`	Every argument from the second onward

Arguments are parsed bash-style, so quote anything containing a space.