---
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