pi 可以创建技能。让它为你的用例构建一个。

技能

技能是智能体按需加载的自包含能力包。技能为特定任务提供专门的工作流程、设置说明、辅助脚本和参考文档。

Pi 实现了 智能体技能标准，对大多数违规行为发出警告，但保持宽松。Pi 允许技能名称与其父目录不同，即使标准不允许这样做；该规则对于跨多个智能体框架使用的共享技能目录来说不是最优的。

目录

• 位置
• 技能如何工作
• 技能命令
• 技能结构
• 前置元数据
• 验证
• 示例
• 技能仓库

位置

安全性： 技能可以指示模型执行任何操作，并可能包含模型调用的可执行代码。使用前请检查技能内容。

Pi 从以下位置加载技能：

• 全局：
  • ~/.pi/agent/skills/
  • ~/.agents/skills/
• 项目（仅在项目受信任后）：
  • .pi/skills/
  • .agents/skills/ 在 cwd 和祖先目录中（直到 git 仓库根目录，或不在仓库中时直到文件系统根目录）
• 包： skills/ 目录或 pi.skills 条目在 package.json
• 设置： 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. 系统提示根据 规范
3. 以 XML 格式包含可用的技能。当任务匹配时，智能体使用 read 加载完整的 SKILL.md（模型并不总是这样做；使用提示或 /skill:name 来强制加载）
4. 智能体遵循指令，使用相对路径引用脚本和资源

这是渐进式披露：只有描述始终在上下文中，完整指令按需加载。

技能命令

技能注册为 /skill:name 命令：

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

命令后的参数作为 User: <args>.

在交互模式下或通过 /settings 切换技能命令 settings.json:

{
  "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

SKILL.md 格式

---
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>
```

使用相对于技能目录的路径：

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

前置元数据

根据 Agent Skills 规范:

命名规则

• 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 个字符

未知的前置元数据字段将被忽略。

例外： 缺少描述的技能不会被加载。

名称冲突（来自不同位置的相同名称）会发出警告，并保留找到的第一个技能。

示例

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"              # Basic search
./search.js "query" --content    # Include page content
```
 
## Extract Page Content
 
```bash
./content.js https://example.com
```

技能仓库

• Anthropic 技能 - 文档处理（docx、pdf、pptx、xlsx）、Web 开发
• Pi技能 - Web 搜索、浏览器自动化、Google API、转录