跳转到主要内容

12 技能

技能的加载位置、工作原理、SKILL.md 结构、frontmatter 字段与校验规则。

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

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

Pi 实现了 Agent Skills 标准，对大多数违规情况只给出警告但保持宽容。Pi 允许技能名称与其父目录不同，尽管标准不允许；对于在多个智能体框架之间共享的技能目录来说，那条规则并不理想。

目录

位置

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

Pi 从以下位置加载技能：

  • 全局：
    • ~/.pi/agent/skills/
    • ~/.agents/skills/
  • 项目（仅在项目受信任之后）：
    • .pi/skills/
    • cwd 及祖先目录中的 .agents/skills/（向上直到 git 仓库根目录；不在仓库中时则到文件系统根目录）
  • 包：skills/ 目录或 package.json 中的 pi.skills 条目
  • 设置：skills 数组，元素为文件或目录
  • CLI：--skill <path>（可重复，即使使用 --no-skills 也会叠加加载）

发现规则：

  • 在 ~/.pi/agent/skills/ 和 .pi/skills/ 中，根目录下的 .md 文件只要带有合法的技能 frontmatter 且 description 非空，就会被识别为独立技能
  • 在所有技能位置中，包含 SKILL.md 的目录会被递归发现
  • 在 ~/.agents/skills/ 和项目级 .agents/skills/ 中，根目录下的 .md 文件会被忽略，但分组文件夹中嵌套的 .md 文件在声明了技能 frontmatter 后会被发现
  • 除 SKILL.md 外，其他看起来不像技能的根级 Markdown 文件会被静默忽略

使用 --no-skills 可以禁用发现（显式指定的 --skill 路径仍会加载）。

使用来自其他智能体框架的技能

要使用来自 Claude Code 或 OpenAI Codex 的技能，把它们的目录加入设置：

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

对于项目级的 Claude Code 技能，在 .pi/settings.json 中添加：

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

技能的工作原理

  1. 启动时，pi 扫描技能位置并提取名称和描述
  2. 系统提示词按照规范以 XML 格式包含可用技能
  3. 当任务匹配时，智能体使用 read（在 read 不可用时使用 bash）加载完整的 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>
```

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

详情请参阅参考指南。

Frontmatter

依据 Agent Skills 规范：

字段必填说明
name是最多 64 个字符。仅限小写 a-z、0-9 和连字符。与标准不同，Pi 不要求它与父目录同名，因为该标准要求对共享技能目录而言并不理想。
description是最多 1024 个字符。说明技能做什么以及何时使用。
license否许可证名称，或指向包内许可证文件的引用。
compatibility否最多 500 个字符。环境要求。
metadata否任意键值映射。
allowed-tools否以空格分隔的预批准工具列表（实验性）。
disable-model-invocation否为 true 时，技能不会出现在系统提示词中。用户必须使用 /skill:name。

名称规则

  • 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 字段会被忽略。

声明为技能但缺少描述的不会被加载。格式错误的 SKILL.md 文件以及没有描述的 SKILL.md 文件会产生警告且不会被加载。其他不带合法技能 frontmatter 的 Markdown 文件会被忽略。

名称冲突（不同位置出现同名）会产生警告，并保留最先找到的技能。

示例

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——Web 搜索、浏览器自动化、Google API、语音转写
最后修改 2026-10-16