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
~/.pizzapi/skills/	Global — available in all projects
<cwd>/.pizzapi/skills/	Project-local — scoped to this repo
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)
description	string	Tells the agent when to apply this skill — matched against the user’s task
tools	string	Comma-separated list of tools this skill needs (informational)

All frontmatter fields are optional. If no frontmatter is provided, the skill is still loaded — the agent uses the file content to decide relevance.

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 (or content) 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 can use ${CLAUDE_PLUGIN_ROOT} to reference files relative to the plugin root

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 always active:

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 sub-sessions via the runner
session-messaging	Gives the agent send_message, wait_for_message, and check_messages tools for inter-agent communication
claude-plugins	Discovers Claude Code plugins and loads their commands, hooks, and skills into the runtime

---

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/, ~/.claude/plugins/) are automatically discovered alongside your regular skills. 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

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
• Refresh to re-scan the filesystem if you’ve added skills outside the UI

Relationship to File-Based Discovery

The API writes directly to the same directories used by file-based discovery (~/.pizzapi/skills/, etc.). A skill created via the API is a regular SKILL.md file on disk — there’s no separate “API-only” storage. Similarly, skills added to the filesystem can be picked up by hitting the Refresh button or calling the /refresh endpoint.

Note

Skill names are validated to prevent path traversal — only alphanumeric characters, hyphens, and underscores are allowed.

---

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.