14 Skills

14.1 Overview

Skills are self-contained capability packages that the agent loads on-demand. They provide specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks. Pi implements the Agent Skills standard for cross-harness compatibility.

14.2 Skill Locations

Skills are discovered from multiple locations:

Location	Scope	Trust Required
`~/.pi/agent/skills/*/SKILL.md`	Global (all projects)	No
`.pi/skills/*/SKILL.md`	Project-local	Yes
`.agents/skills/*/SKILL.md`	Project-local (Agent Skills standard)	Yes
`--skill <path>`	CLI override	N/A
Via packages	Installed by `pi install`	Per package

Additional paths can be configured in settings.json:

{
  "skills": [
    "/path/to/skills/dir"
  ]
}

Disable skill discovery with --no-skills.

14.3 Cross-Harness Compatibility

Pi skills follow the Agent Skills standard, making them compatible with other AI agent harnesses that implement the same standard. A skill written for Pi can work in other harnesses, and skills written for compatible harnesses can work in Pi.

The Agent Skills standard specifies:

Directory structure with SKILL.md as the entry point
Progressive disclosure pattern (summary → details → scripts)
YAML frontmatter for metadata
Standard file naming conventions

14.4 How Skills Work

Skills use a progressive disclosure pattern. The agent does not load all skill content at once. Instead, it loads progressively:

graph TD
    A[System Prompt] --> B[Skill Summaries]
    B --> C{Agent needs skill?}
    C -->|Yes| D[Load SKILL.md]
    D --> E[Load referenced files]
    E --> F[Execute scripts]
    C -->|No| G[Skip]

14.4.1 Level 1: Summary

All skill names and descriptions are included in the system prompt. This gives the model awareness of available capabilities without consuming context.

14.4.2 Level 2: Full SKILL.md

When the model determines a skill is relevant, it reads the full SKILL.md file to understand the workflow, instructions, and available resources.

14.4.3 Level 3: Referenced Files

The model reads specific referenced files from the skill directory as needed: setup scripts, reference docs, examples, templates.

14.4.4 Level 4: Execution

The model executes helper scripts or follows detailed procedures described in the skill.

14.5 Skill Commands

Skills are available as slash commands in the interactive editor:

/skill:my-skill-name

This explicitly loads the skill and makes it available for the current conversation. The agent can also load skills autonomously based on context.

14.5.1 Listing Available Skills

At startup, Pi shows loaded skills in the header. You can also check available skills via:

pi --verbose

14.6 Skill Structure

A skill is a directory containing a SKILL.md file and optional supporting files:

my-skill/
├── SKILL.md              # Entry point (required)
├── scripts/
│   ├── setup.sh          # Helper scripts
│   └── deploy.sh
├── examples/
│   └── example-config.json
├── references/
│   └── api-docs.md
└── templates/
    └── template.ts

14.6.1 Minimal Skill

my-skill/
└── SKILL.md

Even a single SKILL.md file constitutes a valid skill.

14.7 SKILL.md Format

The SKILL.md file is the entry point for a skill. It contains YAML frontmatter for metadata and markdown body content with instructions.

14.7.1 Example

---
name: deploy-vercel
description: Deploy a Next.js project to Vercel
version: 1.0.0
author: example@example.com
---

## Overview

This skill helps deploy Next.js projects to Vercel.

## Prerequisites

- Vercel CLI installed (`npm i -g vercel`)
- Logged in to Vercel (`vercel login`)

## Deployment Steps

1. Run `scripts/deploy.sh`
2. Verify the deployment URL

## Scripts

- `scripts/deploy.sh` — Builds and deploys the project

14.8 Frontmatter

14.8.1 Required Fields

Field	Type	Description
`name`	`string`	Skill identifier (lowercase, hyphens)
`description`	`string`	Short description for system prompt

14.8.2 Optional Fields

Field	Type	Description
`version`	`string`	Semantic version
`author`	`string`	Author email or name
`tags`	`string[]`	Categorization tags
`categories`	`string[]`	Alternative categories
`minPiVersion`	`string`	Minimum Pi version required
`dependencies`	`string[]`	Other skills this depends on

14.9 Naming Rules

Skill names must follow these rules:

Lowercase letters only (a-z)
Digits allowed (0-9)
Hyphens to separate words (-)
Must start with a letter
3-64 characters in length

Valid names: deploy-vercel, code-review, api-testing, db-migration-helper

Invalid names: Deploy_Vercel, 123-skill, x, skill with spaces

14.10 Validation

Pi validates skills at load time:

SKILL.md exists — the file must be present
Valid frontmatter — required fields present and correctly typed
Valid name — follows naming rules
No circular dependencies — dependency graph must be acyclic

Invalid skills are skipped with a warning. Use pi --verbose to see validation messages.

14.11 Creating a Skill

14.11.1 Step 1: Create the Directory

mkdir -p ~/.pi/agent/skills/my-skill

14.11.2 Step 2: Write SKILL.md

---
name: my-skill
description: Does something useful
---

## What This Skill Does

Detailed description of the skill's purpose and capabilities.

## When to Use

Guidance on when the agent should activate this skill.

## Instructions

Step-by-step instructions the agent should follow.

14.11.3 Step 3: Add Supporting Files (Optional)

mkdir -p ~/.pi/agent/skills/my-skill/scripts
cat > ~/.pi/agent/skills/my-skill/scripts/setup.sh << 'EOF'
#!/bin/bash
echo "Setting up..."
EOF
chmod +x ~/.pi/agent/skills/my-skill/scripts/setup.sh

14.11.4 Step 4: Test

# Load Pi with the skill
pi --verbose

# Explicitly invoke the skill
# Type: /skill:my-skill

# Or let the agent discover it based on context

14.12 Examples

14.12.1 Code Review Skill

---
name: code-review
description: Perform a thorough code review
---

## Overview

This skill guides the agent through a structured code review process.

## Review Checklist

1. **Correctness** — Does the code do what it claims?
2. **Security** — Are there vulnerabilities?
3. **Performance** — Are there bottlenecks?
4. **Style** — Does it follow project conventions?
5. **Tests** — Are changes covered by tests?

## Process

1. Read the diff: `git diff main`
2. Review each changed file
3. Run linters: `!npm run lint`
4. Run tests: `!npm test`
5. Provide structured feedback

## Output Format

Present findings as a table:

| Severity | File | Line | Issue |
|----------|------|------|-------|

14.12.2 Database Migration Skill

---
name: db-migration
description: Create and apply database migrations safely
---

## Prerequisites

- Check `references/schema-conventions.md` for project standards
- Verify backup exists before applying migrations

## Creating Migrations

1. Read current schema
2. Design migration (up and down)
3. Test locally: `scripts/test-migration.sh`
4. Apply: `scripts/apply-migration.sh`

## Safety Rules

- NEVER drop columns without confirmation
- ALWAYS create a backup first
- Test rollback procedure

Tip

Pi can create skills for you. Ask it: “Create a skill that helps with [your use case].” Pi will generate the directory structure, SKILL.md, and supporting files.