Skills

✓ Fresh · 2026-02-24

Skills are on-demand capability packages that follow the Agent Skills standard. They are Markdown files that provide the agent with domain-specific knowledge and step-by-step instructions.

What Skills Do

Skills give Pi specialized knowledge without code. They are Markdown documents that:

• Teach the agent how to perform specific tasks
• Provide step-by-step procedures
• Include reference information
• Can be invoked on-demand or loaded automatically

Creating a Skill

A skill is a Markdown file named SKILL.md inside a named directory:

skills/
└── my-skill/
    └── SKILL.md

Skill Format

<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# My Skill

Use when user asks about X.

## Steps
1. Do this first
2. Then do that
3. Finally, verify the result

## Reference
- Important fact A
- Important fact B

Skills can include any Markdown content: headings, lists, code blocks, tables. The agent reads and follows the instructions.

Skill with Supporting Files

Skills can include additional files alongside SKILL.md:

skills/
└── deployment/
    ├── SKILL.md           # Main skill instructions
    ├── checklist.md       # Supporting reference
    └── config-template.yaml  # Template file

Skill Directories

Pi searches for skills in these locations (all are scanned):

Directory	Scope
~/.pi/agent/skills/	Global (available in all projects)
~/.agents/skills/	Cross-agent global (shared with other agents)
.pi/skills/	Project-specific (from cwd)
.agents/skills/	Project-specific cross-agent
Parent directories	Walking up from cwd
Pi packages	Installed via pi install

Invoking Skills

Explicit Invocation

Type the skill's slash command:

/skill:my-skill

This loads the skill's content into the conversation context.

Automatic Loading

Pi can automatically detect when a skill is relevant based on the user's request and load it without explicit invocation. The skill's description (first line or heading) helps Pi determine relevance.

Example Skills

Code Review Skill

# Code Review

Use when user asks for a code review.

## Process
1. Read all files in the change set
2. Check for bugs and logic errors
3. Review error handling
4. Check for security vulnerabilities
5. Assess code style and readability
6. Provide specific, actionable feedback

## Review Checklist
- [ ] No hardcoded secrets or credentials
- [ ] Error cases handled
- [ ] Input validated
- [ ] Tests cover new behavior
- [ ] No unnecessary complexity

Database Migration Skill

# Database Migration

Use when user needs to create or run database migrations.

## Steps
1. Check current migration state: `npx prisma migrate status`
2. Create new migration: `npx prisma migrate dev --name <description>`
3. Review generated SQL in migrations/ directory
4. Test migration on development database
5. Verify schema matches expected state

## Rules
- Never modify existing migrations
- Always add NOT NULL with a default value
- Include both up and down migration logic

Skills vs Extensions vs Prompt Templates

Feature	Skills	Extensions	Prompt Templates
Format	Markdown	TypeScript	Markdown with
Adds tools	No	Yes	No
Domain knowledge	Yes	Optional	Minimal
Invocation	/skill:name or auto	Auto-loaded or -e flag	/templatename
Complexity	Low	High	Low
Use case	Teach procedures	Add capabilities	Reusable prompts