skills/README.md

pi Skills

This directory contains custom skills for pi, a coding agent harness. Each skill adds specialized capabilities that extend what pi can do.

Installed Skills

Skill	Description
phased-execution	Runs phased build pipelines in isolated subprocesses
find-skills	Discovers and installs new skills
gog	Google Workspace CLI (Gmail, Calendar, Drive, Contacts, Sheets, Docs)

How Skills Work

A skill is a directory containing at minimum a SKILL.md file. When pi loads, it reads all SKILL.md files in this directory and makes their instructions available to the agent. The description field in each skill's front matter tells pi when to activate that skill.

Skills can include:

• Scripts — shell scripts, Node modules, or any executable code
• Assets — templates, prompts, validation gates, etc.
• Additional docs — referenced via relative paths from SKILL.md

Adding a New Skill

1. Create a directory under ~/.pi/agent/skills/<name>/
2. Add a SKILL.md with front matter and instructions
3. Optionally add scripts, assets, or subdirectories
4. Restart pi (or the skill will be picked up on next load)

SKILL.md Format

---
name: my-skill
description: What this skill does — when pi should activate it
---

# My Skill

Instructions for the agent go here.

Cloning Skills from Other Sources

To install a skill from a git repo or another location, you can clone it directly into this directory:

git clone https://github.com/user/my-skill ~/.pi/agent/skills/my-skill

Or symlink for development:

ln -s /path/to/my-skill ~/.pi/agent/skills/my-skill

---

phased-execution

Runs phased build pipelines in isolated subprocesses. Ported from opencode's next-phase / auto-phase commands.

Overview

This skill orchestrates a project's development as a sequence of phases, each executed by the LLM in its own fresh pi process. Phases are managed via files — not chat context — so even very long-running pipelines don't bloat your session history.

Each phase:

1. Reads the master plan (.agent/PLAN.md) and any already-completed phases
2. Implements all tasks from its phase file
3. Runs tests, linting, and coverage checks via .agent/validate.sh
4. Retries up to MAX_FIX_ATTEMPTS times on failure (resuming the same session)
5. Moves to complete/ only when everything passes

Directory Structure

<project>/
├── .agent/
│   ├── PLAN.md                  # Master plan; LOCKED DECISIONS are binding
│   ├── validate.sh              # Quality gate (created from skill template on first run)
│   ├── phases/
│   │   ├── todo/                # Pending phases: 01_name.md, 02_name.md, …
│   │   └── complete/            # Finished phases
│   ├── reports/                 # Per-phase executor reports, stderr, validation logs
│   └── phase-sessions/          # Resumable child pi sessions

Usage

From within a project that has .agent/phases/todo/:

Run the next pending phase:

cd /path/to/project
bash ~/.pi/agent/skills/phased-execution/scripts/run-phase.sh

Run a specific phase:

bash ~/.pi/agent/skills/phased-execution/scripts/run-phase.sh 03_api.md

Run the entire pipeline (all pending phases, in order, stopping at first failure):

bash ~/.pi/agent/skills/phased-execution/scripts/auto-phase.sh

Re-running auto-phase.sh after a failure continues where it stopped.

Configuration

Environment variables passed to the scripts control behavior:

Variable	Default	Meaning
MAX_FIX_ATTEMPTS	3	Fixer retries per phase
PHASE_MODEL	session default	Model for child executors (e.g. anthropic/claude-sonnet-4-5)
PHASE_THINKING	session default	Thinking level for child executors
PHASE_COMMIT	0	1 = auto-git-commit after each passing phase
PI_TRUST	0	1 = pass --approve to children (load project .pi/ settings)
FRESH_FIX	0	1 = fixer retries start fresh instead of resuming the failed session
QUIET	0	1 = suppress live progress display (reports still written)

Example:

PHASE_MODEL=anthropic/claude-sonnet-4-5 PHASE_COMMIT=1 bash ~/.pi/agent/skills/phased-execution/scripts/auto-phase.sh

How It Works

1. run-phase.sh / auto-phase.sh finds the project root (walks up from PWD for .agent/phases/todo/)
2. For each phase, it spawns a separate pi subprocess with --mode json to capture structured output
3. progress.mjs streams live progress (tool calls, assistant text) to the terminal and writes the final report to .agent/reports/
4. After the child exits, .agent/validate.sh is run as the quality gate
5. On success: phase moves to complete/, report is printed
6. On failure: up to MAX_FIX_ATTEMPTS fixer retries (resuming the same session), then the phase stays in todo/

After a Run

• Success: The executor report is printed at the end of the script output. Phases in .agent/phases/complete/ are already done.
• Failure: Point to .agent/reports/<phase>.a*.{md,err,validate} for logs. Resume with:

  pi --session-dir .agent/phase-sessions -c
  

  Or re-run the script to retry automatically.

Creating Phases

Phase files are typically created by prompt templates like /to-phase, /audit-create, /new-project, and /new-python-*. Each phase file in todo/ should list concrete tasks the executor must complete, including testing & quality criteria.