singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
singularity-forge/docs/dev/what-is-pi/09-the-customization-stack.md
ace-pm b29c12d5e5 refactor(native): rename gsd_parser.rs to forge_parser.rs 
Final rebrand: rename remaining Rust source file to complete the gsd → forge
transition. All parser references already use forge_parser after earlier commits.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00

3.8 KiB
Raw Blame History

The Customization Stack

Pi has four layers of customization, each serving a different purpose:

┌─────────────────────────────────────┐
│           Extensions                │  ← TypeScript code. Full runtime access.
│  Custom tools, events, UI,          │     Can do anything.
│  commands, providers                │
├─────────────────────────────────────┤
│           Skills                    │  ← Markdown instructions + scripts.
│  On-demand capability packages      │     Loaded when the task matches.
│  loaded by the agent                │
├─────────────────────────────────────┤
│       Prompt Templates              │  ← Markdown snippets.
│  Reusable prompts expanded          │     Quick text expansion via /name.
│  via /templatename                  │
├─────────────────────────────────────┤
│           Themes                    │  ← JSON color definitions.
│  Visual appearance                  │     Hot-reload on change.
└─────────────────────────────────────┘

Extensions

TypeScript modules with full runtime access. They can hook into every event, register tools the LLM can call, add commands, render custom UI, override built-in behavior, and register model providers. Extensions are the most powerful customization mechanism.

Placement:

  • ~/.sf/agent/extensions/ (global)
  • .sf/extensions/ (project-local)

See the companion doc Pi-Extensions-Complete-Guide.md for the full 50KB reference.

Skills

On-demand capability packages following the Agent Skills standard. A skill is a directory with a SKILL.md file containing instructions the agent follows. Skills are progressive: only their names and descriptions are in the system prompt. The agent reads the full SKILL.md only when the task matches.

How skills work:

  1. At startup, pi scans for skills and extracts names + descriptions
  2. Descriptions are listed in the system prompt
  3. When a task matches, the agent uses read to load the full SKILL.md
  4. The agent follows the instructions, using relative paths for scripts/assets

Invocation:

/skill:brave-search              # Explicit invocation
/skill:pdf-tools extract file.pdf  # With arguments

Placement:

  • ~/.agents/skills/ (global — shared across all agents)
  • .agents/skills/ (project, searched up to git root)

Skill structure:

my-skill/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Helper scripts (optional)
│   └── process.sh
└── references/           # Reference docs (optional)
    └── api-guide.md

Prompt Templates

Markdown files that expand into prompts via /name. Simple text expansion with positional argument support ($1, $2, $@).

<!-- ~/.sf/agent/prompts/review.md -->
---
description: Review staged git changes
---
Review the staged changes (`git diff --cached`). Focus on:
- Bugs and logic errors  
- Security issues
- Performance problems
Focus area: $1

Usage: /review "error handling" → expands with $1 = "error handling"

Placement:

  • ~/.sf/agent/prompts/ (global)
  • .sf/prompts/ (project-local)

Themes

JSON files defining the color palette for the TUI. Hot-reload: edit the file and pi applies changes immediately.

Built-in: dark, light

Placement:

  • ~/.sf/agent/themes/ (global)
  • .sf/themes/ (project-local)