Frank
02883d3ed2
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
51 lines
1.8 KiB
Markdown
51 lines
1.8 KiB
Markdown
---
|
|
type: reference
|
|
title: Skills vs Extensions
|
|
description: Side-by-side comparison of skills (markdown-based) vs extensions (TypeScript-based) for pi coding agent.
|
|
tags:
|
|
- unverified
|
|
- skills
|
|
- extensions
|
|
- comparison
|
|
timestamp: 2026-07-18
|
|
verified: 2026-08-28
|
|
---
|
|
|
|
# Skills vs Extensions
|
|
|
|
| Feature | Skills | Extensions |
|
|
|---------|--------|------------|
|
|
| **Format** | Markdown (`SKILL.md` + optional scripts) | TypeScript (`.ts` files) |
|
|
| **Purpose** | Instructions for the LLM to follow | Code that intercepts events, registers tools/commands |
|
|
| **Execution** | Agent reads and follows instructions | Runs in pi's Node.js runtime |
|
|
| **Loading** | On-demand (progressive disclosure) | Always loaded at startup |
|
|
| **Power** | Can instruct the agent to run anything | Full programmatic access to pi's API |
|
|
| **Security** | Review content (instructs model) | Review code (runs arbitrary code) |
|
|
| **Best for** | Domain knowledge, workflows, scripts | Permission gates, custom tools, event handling |
|
|
| **Location** | `skills/` directory | `extensions/` directory |
|
|
| **Can distribute via npm?** | Yes (via pi packages) | Yes (via pi packages) |
|
|
|
|
## When to Use Each
|
|
|
|
- **Skill**: You want to teach the agent a new workflow, provide domain expertise, or bundle helper scripts
|
|
- **Extension**: You need to intercept tool calls, register new LLM-callable tools, modify system prompts programmatically, or add custom TUI components
|
|
|
|
## They Can Work Together
|
|
|
|
A pi package can contain both:
|
|
|
|
```json
|
|
{
|
|
"pi": {
|
|
"extensions": ["./extensions"],
|
|
"skills": ["./skills"]
|
|
}
|
|
}
|
|
```
|
|
|
|
Example: `pi-web-access` provides both a web-search extension AND skill documentation for it.
|
|
|
|
## Related
|
|
|
|
* [Package Structure](/tools/npx-skills/package-structure.md) — How to bundle both in one npm package
|