Skills

pi 可以創造技能。要求它為您的用例建立一個。

Skills 是代理按需載入的獨立功能包。技能為特定任務提供專門的工作流程、設定說明、幫助腳本和參考文件。

Pi 實施Agent Skills standard，對大多數違規行為發出警告，但保持寬鬆。 Pi 允許技能名稱與其父目錄不同，即使標準不允許；對於跨多個代理工具使用的共享技能目錄，該規則並不是最佳選擇。

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

安全性： Skills 可以指示模型執行任何操作，並且可能包括模型呼叫的可執行程式碼。使用前查看技能內容。

Pi 從以下位置載入技能：

• 全球的：
  • ~/.pi/agent/skills/
  • ~/.agents/skills/
• 項目（僅在專案信任後）：
  • .pi/skills/
  • cwd 和祖先目錄中的 .agents/skills/ （直至 git repo 根目錄，或不在儲存庫中時的檔案系統根目錄）
• 包：skills/目錄或package.json中的pi.skills條目
• 設定：skills包含檔案或目錄的陣列
• CLI：--skill <path>（可重複，可與--no-skills相加）

發現規則：

• 在~/.pi/agent/skills/和.pi/skills/中，直接根.md文件被發現為個人技能
• 在所有技能位置中，遞歸地發現包含SKILL.md的目錄
• 在~/.agents/skills/和項目.agents/skills/中，根.md檔案被忽略

使用 --no-skills 停用發現（仍載入明確 --skill 路徑）。

若要使用 Claude Code 或 OpenAI Codex 中的技能，請將其目錄新增至設定：

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

對於專案層級的 Claude Code 技能，請加入 .pi/settings.json：

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

1. 啟動時，pi 掃描技能位置並提取名稱和描述
2. 系統提示包含 XML 格式的可用技能，依照specification
3. 當任務匹配時，代理使用read加載完整的SKILL.md（模型並不總是這樣做；使用提示或/skill:name強制它）
4. 代理程式按照說明操作，使用相對路徑來引用腳本和資產

這是漸進式揭露：只有描述始終處於上下文中，完整的說明按需載入。

Skills 註冊為/skill:name 指令：

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

指令後面的參數將作為User: <args>附加到技能內容中。

在互動模式或settings.json下透過/settings切換技能指令：

{
  "enableSkillCommands": true
}

技能是一個包含 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 /路徑/到/技能 && npm 安裝
```

## Usage

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

使用技能目錄中的相對路徑：

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

根據 Agent Skills specification：

• 1-64 個字符
• 僅小寫字母、數字、連字符
• 沒有前導/尾隨連字符
• 沒有連續的連字符 Pi 不要求名稱與父目錄相符。 Agent Skills 標準確實如此，但對於多個工具使用的共享技能目錄來說，該要求並不是最優的。

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

描述決定代理何時加載技能。具體一點。

好的：

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 標準驗證技能。大多數問題都會產生警告，但仍會載入技能：

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

未知的 frontmatter 欄位將被忽略。

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

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

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

技能.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" # 基本搜索
./search.js "query" --content # 包含頁面內容
```

## Extract Page Content

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

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