---
type: reference
title: How Pi Loads Skills
description: The discovery flow, progressive disclosure pattern, and system prompt integration for skills in pi.
tags:
  - unverified
  - skills
  - loading
  - progressive-disclosure
timestamp: 2026-07-18
verified: 2026-08-28
---

# How the Pi Agent Loads and Uses Skills

## Discovery Flow

1. Pi scans all configured skill locations at startup
2. Extracts names and descriptions from each `SKILL.md`
3. Builds the system prompt with skill descriptions in XML format
4. The LLM decides which skill(s) to activate based on the user's prompt
5. When activated, the agent reads the full SKILL.md using the `read` tool

## Progressive Disclosure Pattern

```
System prompt (always in context):
  - "Available skills: brave-search (Web search...), browser-tools (Browser automation...), ..."

User: "Search for information about React hooks"

Agent decides: activate brave-search
Agent reads: ~/.pi/agent/skills/brave-search/SKILL.md (full file)
Agent executes: {baseDir}/search.js "React hooks"
```

## This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.

## Related

* [Skills Specification](/tools/npx-skills/skills-spec.md) — What the agent sees in the system prompt
* [Skill Commands](/tools/npx-skills/skill-commands.md) — The `/skill:name` override