Pi Agent Skills 技能系统

Skills（技能）是自包含的能力包，让 AI 可以按需加载专业领域的工作流指令和工具脚本。

Pi Agent 实现了 Agent Skills 标准。

什么是 Skill

一个 Skill 就是一个包含 SKILL.md 文件的目录。

SKILL.md 中包含技能的名称、描述和详细的使用指令，AI 会在需要时自动读取并执行。

你可以把 Skill 理解为 AI 的「专业培训手册」——平时不占上下文空间，需要时才加载。

Skill 工作原理

Pi Agent 启动时扫描所有 Skill 位置，提取名称和描述
所有可用 Skill 的描述以 XML 格式嵌入系统提示词中
当用户的任务匹配某个 Skill 的描述时，AI 会自动用 read 工具加载完整的 SKILL.md
AI 按照 SKILL.md 中的指令工作，使用相对路径引用技能目录中的脚本和资源

这种设计被称为「渐进式披露（Progressive Disclosure）」——只有描述始终在上下文中，完整的指令按需加载。

Skill 的目录结构

my-skill/
├── SKILL.md              # 必需：Frontmatter + 指令
├── scripts/              # 辅助脚本
│   └── process.sh
├── references/           # 详细参考文档（按需加载）
│   └── api-reference.md
└── assets/
    └── template.json

SKILL.md 格式

SKILL.md 使用 YAML Frontmatter 定义元信息，之后是 Markdown 格式的指令正文：

实例

---
name: my-skill
description: 这个技能做什么以及何时使用。描述要具体明确。
---

# My Skill

## 安装

首次使用前运行：
```bash
cd /path/to/skill && npm install
```

## 使用

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

## 参考

详见 [参考指南](references/REFERENCE.md)

引用技能目录中的文件时，使用相对路径。

Frontmatter 字段

字段	必填	说明
name	是	最多 64 字符，仅小写字母/数字/连字符。Pi Agent 不要求名称与父目录一致
description	是	最多 1024 字符。描述技能的功能和使用时机，这是 AI 判断是否加载该技能的依据
license	否	许可证名称
compatibility	否	最多 500 字符，环境要求
metadata	否	自定义键值对
allowed-tools	否	预批准的工具列表（实验性）
disable-model-invocation	否	设为 true 时，Skill 从系统提示词中隐藏，只能通过 /skill:name 手动调用

description 是 AI 决定是否加载你的 Skill 的关键依据，务必写得具体明确。一个模糊的 description 会导致 Skill 在不合适的场景被触发，或者在需要的场景被忽略。

Skill 加载位置

位置	作用范围	加载规则
~/.pi/agent/skills/	全局	根目录 .md 文件和包含 SKILL.md 的目录被递归发现
~/.agents/skills/	全局	仅包含 SKILL.md 的目录被递归发现，根目录 .md 文件被忽略
.pi/skills/	项目	根目录 .md 文件和包含 SKILL.md 的目录被递归发现
.agents/skills/	项目	仅包含 SKILL.md 的目录被递归发现
Pi Packages	全局或项目	skills/ 目录或 package.json 的 pi.skills 条目

Skill 命令

每个 Skill 自动注册为 /skill:名称命令：

/skill:brave-search
/skill:pdf-tools extract

命令后的参数会以 User: 参数的形式追加到 Skill 内容中。

可以通过设置禁用 Skill 命令注册：

实例

{
"enableSkillCommands": false
}

也可以通过设置中的 disable-model-invocation 让某些 Skill 仅能手动调用，不自动出现在系统提示词中。

从其他工具导入 Skill

Pi Agent 可以加载 Claude Code 或 OpenAI Codex 的 Skills：

实例

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

对于项目级的 Claude Code Skills：

实例

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

Skills 中的指令可以要求 AI 执行任意操作，包括运行可执行文件。在使用第三方 Skill 之前，建议先审查其内容。

完整 Skill 示例

以下是一个网页搜索 Skill 的完整示例：

实例

---
name: brave-search
description: 通过 Brave Search API 进行网页搜索和内容提取。适用于搜索文档、事实查询或任何网页内容检索。
---

# Brave Search

## 安装

首次使用前安装依赖：
```bash
cd /path/to/brave-search && npm install
```

## 搜索

```bash
./search.js "查询关键词" # 基础搜索
./search.js "查询关键词" --content # 包含页面内容
```

## 提取页面内容

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

Skill 仓库推荐

Anthropic Skills - 文档处理（docx, pdf, pptx, xlsx）、网页开发
Pi Skills - 网页搜索、浏览器自动化、Google API、音频转录

返回顶部

菜鸟教程