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、转录