Skills

pi 可以建立 Skills。可以讓它為你的使用情境產生一個 Skill。

Skills 是 Agent 隨需載入的獨立能力包。Skill 會為特定任務提供專門的工作流程、設定說明、輔助指令碼和參照檔案。

Pi 實作了 Agent Skills standard，會對大多數違規行為發出警告，但整體保持寬松。即使標準不允許，Pi 也允許 Skill 名稱與父目錄不同；對於跨多個 Agent harness 共享的 Skill 目錄，這條標準規則並不理想。

• Locations
• How Skills Work
• Skill Commands
• Skill Structure
• Frontmatter
• Validation
• Example
• Skill Repositories

安全性： Skills 可以指示模型執行任意操作，也可能包含模型會呼叫的可執行程式碼。使用前請檢查 Skill 內容。

Pi 從以下位置載入技能：

• 全域：
  • ~/.pi/agent/skills/
  • ~/.agents/skills/
• 專案（僅在專案被信任後）：
  • .pi/skills/
  • cwd 和祖先目錄中的 .agents/skills/ （直至 git repo 根目錄，或不在儲存庫中時的檔案系統根目錄）
• Packages：skills/ 目錄或 package.json 中的 pi.skills 條目
• 設定：skills 陣列，包含檔案或目錄
• CLI：--skill <path>（可重複；即使使用 --no-skills 也會追加載入）

探索規則：

• 在 ~/.pi/agent/skills/ 和 .pi/skills/ 中，根目錄下的 .md 檔案會被探索為單一 Skill
• 在所有 Skill 位置中，包含 SKILL.md 的目錄會被遞迴探索
• 在 ~/.agents/skills/ 和專案 .agents/skills/ 中，根目錄下的 .md 檔案會被忽略

使用 --no-skills 停用探索（仍載入顯式 --skill 路徑）。

要使用 Claude Code 或 OpenAI Codex 中的 Skills，請將它們的目錄新增到設定中：

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

對於專案層級的 Claude Code Skills，請新增到 .pi/settings.json：

{
  "skills": ["../.claude/skills"]
}

1. 啟動時，pi 會掃描 Skill 位置並提取名稱和描述
2. 系統 Prompt 按照 specification 以 XML 格式包含可用 Skills
3. 當任務比對時，Agent 使用 read 載入完整的 SKILL.md（模型並不總是會這樣做；可以透過 Prompt 或 /skill:name 強制載入）
4. Agent 按照說明操作，並使用相對路徑引用指令碼和 assets

這是 progressive disclosure：只有描述會始終進入上下文，完整說明隨需載入。

Skills 會註冊為 /skill:name 指令：

/skill:brave-search           # Load and execute the skill
/skill:pdf-tools extract      # Load skill with arguments

指令後的參數會作為 User: <args> 附加到 Skill 內容中。

在互動模式中透過 /settings，或在 settings.json 中切換 Skill 指令：

{
  "enableSkillCommands": true
}

Skill 是一個包含 SKILL.md 檔案的目錄。其他內容沒有固定格式。

my-skill/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Helper scripts
│   └── process.sh
├── references/           # Detailed docs loaded on-demand
│   └── api-reference.md
└── assets/
    └── template.json

---
name: my-skill
description: What this skill does and when to use it. Be specific.
---

# My Skill

## Setup

Run once before first use:
```bash
cd /path/to/skill && npm install
```

## Usage

```bash
./scripts/process.sh <input>
```

使用相對於 Skill 目錄的路徑：

See [the reference guide](references/REFERENCE.md) for details.

根據 Agent Skills specification：

• 1-64 個字元
• 僅小寫字母、數字、連字元
• 沒有前導/尾隨連字元
• 沒有連續的連字元 Pi 不要求名稱與父目錄比對。Agent Skills 標準有此要求，但對多個工具共用的 Skill 目錄來說並不理想。

有效：pdf-processing、data-analysis、code-review 無效：PDF-Processing、-pdf、pdf--processing

描述決定 Agent 何時載入 Skill。請寫得具體。

好的：

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.

不佳：

description: Helps with PDFs.

Pi 會根據 Agent Skills 標準驗證 Skills。大多數問題會產生警告，但仍會載入 Skill：

• 名稱超過 64 個字元或包含無效字元
• 名稱以連字元開頭/結尾或具有連續的連字元
• 描述超過 1024 個字元

未知的 frontmatter 欄位將被忽略。

例外： 缺少描述的 Skills 不會載入。

名稱衝突（不同位置的相同名稱）會發出警告並保留找到的第一個技能。

brave-search/
├── SKILL.md
├── search.js
└── content.js

SKILL.md:

---
name: brave-search
description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content.
---

# Brave Search

## Setup

```bash
cd /path/to/brave-search && npm install
```

## Search

```bash
./search.js "query"              # Basic search
./search.js "query" --content    # Include page content
```

## Extract Page Content

```bash
./content.js https://example.com
```

• Anthropic Skills - 檔案處理（docx、pdf、pptx、xlsx）、Web 開發
• Pi Skills - 網路搜尋、瀏覽器自動化、Google APIs、轉錄