Skills & Extensions

Skills are markdown (or MDX) files that give the pi agent specialized knowledge, workflows, or instructions for a particular domain. PizzaPi automatically loads skills from well-known directories and makes them available to every session.

---

Skill Discovery

PizzaPi searches for skills in these locations (all merged):

Path	Scope
(built-in CLI skills)	Shipped with PizzaPi
~/.pizzapi/skills/	Global — available in all projects
<cwd>/.pizzapi/skills/	Project-local — scoped to this repo
~/.pizzapi/agents/	Global agents treated as skills
<cwd>/.pizzapi/agents/	Project-local agents treated as skills
<cwd>/.agents/skills/	Claude Code compatible project skills
<cwd>/.agents/agents/	Claude Code compatible project agents
Paths in the skills config array	Custom locations

---

Writing a Skill

A skill is a directory containing a SKILL.md file:

• Directory.pizzapi/

  • Directoryskills/

    • Directorymy-skill/

      • SKILL.md
      • helpers.md
      • Directoryexamples/

        • example-1.md

SKILL.md Frontmatter

Skills support YAML frontmatter for metadata:

---
name: my-skill
description: Use when working on authentication code
tools: read,bash,edit
---

# My Skill

Instructions for the agent...

Field	Type	Description
name	string	Identifier for the skill (used with /skill:name invocation). Required by the Agent Skills standard.
description	string	Tells the agent when to apply this skill. Required — skills without a description are discovered but not loaded.
allowed-tools	string	Space-delimited list of tools this skill needs (Agent Skills standard)
license	string	License identifier
compatibility	string	Compatibility statement
metadata	object	Arbitrary metadata
disable-model-invocation	boolean	Disable model invocation when this skill is active

A skill can also be a bare .md file directly in a skills directory (name = basename without .md), or a subdirectory containing SKILL.md.

Skill Content Structure

---
name: my-skill
description: Use when working on authentication code
---

# My Skill Name

A one-line description of what this skill does.

## When to Use This Skill

Describe the situations where the agent should apply this skill.

## Instructions

Step-by-step guidance, rules, or domain knowledge the agent should follow.

## Examples

Include examples to help the agent understand expected behavior.

Tip

Skills are loaded into the agent’s context when they match. Keep them focused and concise — one skill per domain works best.

---

Skill Matching

The agent decides which skills to load based on two mechanisms:

Automatic matching — The agent compares the user’s task against each skill’s description field and loads relevant skills automatically.

Manual invocation — Users can explicitly load a skill with the /skill:name syntax:

/skill:my-skill Implement the login flow

This bypasses automatic matching and loads the specified skill directly.

---

Referencing Files Within Skills

Skills can reference other files in their directory:

• Relative paths are resolved against the skill directory (the parent of SKILL.md)
• Plugin skills use the same relative-path rules as any other skill: paths are resolved from the SKILL.md directory. There is no special ${CLAUDE_PLUGIN_ROOT} substitution for skill content.

For example, if your skill is at ~/.pizzapi/skills/deploy/SKILL.md, a reference to ./templates/k8s.yaml resolves to ~/.pizzapi/skills/deploy/templates/k8s.yaml.

---

Built-in PizzaPi Extensions

PizzaPi ships with several built-in extensions that are active by default (some can be skipped with --safe-mode or PIZZAPI_NO_* flags):

Extension	What it does
remote	Streams all session events (tokens, tool calls, file diffs) to the relay server
mcp	Bridges Model Context Protocol (MCP) servers into the agent’s tool set
restart	Allows the agent to restart itself within a session
set-session-name	Gives the agent the set_session_name tool to title sessions in the UI
update-todo	Gives the agent the update_todo tool to maintain a live task list in the UI
spawn-session	Gives the agent the spawn_session tool to launch linked child sessions via the runner
claude-plugins	Discovers Claude Code plugins and loads their commands, hooks, skills, and rules into the runtime

Many other extensions (triggers, subagents, hooks, tool-search, goal, providers, etc.) are also active by default. Use pizza --safe-mode to skip the optional ones entirely.

---

Example: Project-Local Skill

Create .pizzapi/skills/nextjs/SKILL.md in your Next.js project:

# Next.js 15 App Router

Use this skill when working on Next.js projects.

## Rules

- Always use TypeScript
- Use the App Router (not Pages Router)
- Server Components by default; add `"use client"` only when needed
- Use `next/image` for all images
- API routes go in `app/api/route.ts`

## File Structure

- `app/` — pages and layouts
- `app/api/` — API routes
- `components/` — shared UI components
- `lib/` — utilities and server-only code

This skill will automatically be available to every pizzapi session started from that project directory.

---

Claude Code Plugin Skills

PizzaPi can also load skills from Claude Code plugins. Both Claude Code and pi use the Agent Skills standard, so plugin skills work natively.

Skills from global plugins (~/.pizzapi/plugins/, ~/.agents/plugins/) are automatically discovered alongside your regular skills. Plugins under ~/.claude/plugins/ are loaded only through Claude Code’s installed_plugins.json marketplace manifest, not by scanning the directory. See the Claude Code Plugins guide for details.

---

Example: Test-Driven Development Skill

---
name: test-driven-development
description: Use when implementing any feature or bugfix, before writing implementation code
---

# Test-Driven Development

## Process

1. Write a failing test first
2. Run the test to confirm it fails
3. Write the minimum code to make the test pass
4. Run the test to confirm it passes
5. Refactor if needed
6. Repeat

## Rules

- Never write implementation code without a failing test
- Tests must be deterministic — no network calls, no time-dependent assertions
- Use descriptive test names that explain the expected behavior
- Keep test files co-located with source: `foo.ts` → `foo.test.ts`

---

Managing Skills via the API

PizzaPi exposes a full CRUD API for managing skills on a connected runner. This lets you create, edit, and delete skills from the web UI without touching the filesystem directly.

API Endpoints

All endpoints are scoped to a specific runner and require an authenticated session.

Method	Endpoint	Description
GET	/api/runners/{runnerId}/skills	List all discovered skills (from Redis cache)
GET	/api/runners/{runnerId}/skills/{name}	Get full content of a specific skill
POST	/api/runners/{runnerId}/skills	Create a new skill (body: { name, content })
PUT	/api/runners/{runnerId}/skills/{name}	Update an existing skill (body: { content })
DELETE	/api/runners/{runnerId}/skills/{name}	Delete a skill
POST	/api/runners/{runnerId}/skills/refresh	Re-scan the filesystem and refresh the skill list
POST	/api/runners/{runnerId}/skills/reload	Re-scan and reload skills inside every live session on the runner

Using the Web UI

In the PizzaPi web interface, navigate to a runner’s detail page and open the Skills tab. From there you can:

• Browse all skills discovered from the runner’s skill directories
• Create a new skill with the in-browser editor
• Edit an existing skill’s content (including frontmatter)
• Delete skills you no longer need
• Reload to re-scan the filesystem and pick the skills up in the runner’s live sessions

Reloading skills without restarting

Skills are read when a session starts, so a skill added mid-session isn’t visible until the session reloads its resources. Two ways to do that:

• In a session: run /skills reload. This re-reads skills, prompt templates, extensions, and context files in place.
• From the web UI: the Reload button in a runner’s Skills tab re-scans the runner’s skill directories and sends /skills reload to each of that runner’s live sessions.

The response reports how many sessions were reloaded:

{ "ok": true, "skills": [...], "reloaded": 2, "failed": 0, "sessionIds": ["..."], "failedSessionIds": [] }

Relationship to File-Based Discovery

The API writes directly to ~/.pizzapi/skills/ only. Project-local, plugin, config, and built-in skills are not visible or editable through the API or the web UI Skills tab.

Note

Skill names must be lowercase letters, numbers, and hyphens (1–64 characters). The runner rejects underscores, dots, and uppercase letters. The web UI may allow broader names, but a name that doesn’t pass the runner validator will fail when saved.

---

Agent Skills Standard

PizzaPi’s skill format is compatible with the Agent Skills open standard. Skills written for other compatible tools (like Claude Code) work in PizzaPi without modification, and vice versa.