Pi 可创建技能：请它为你的用例构建一个

技能（Skills）

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

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

目录

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

位置

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

Pi 从以下位置加载技能：

• 全局：
  • ~/.pi/agent/skills/
  • ~/.agents/skills/
• 项目（仅在项目被信任后）：
  • .pi/skills/
  • .agents/skills/ 位于 cwd 及其父目录（向上到 git 仓库根目录，若不在仓库中则到文件系统根目录）
• 包：skills/ 目录或 package.json 中的 pi.skills 条目
• 设置：skills 数组，包含文件或目录
• 命令行：--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，遵循 规范
3. 当任务匹配时，智能体使用 read 加载完整的 SKILL.md（模型不一定总会这样做；可以通过提示或 /skill:name 强制加载）
4. 智能体按照指令操作，使用相对路径引用脚本和资源

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

技能命令

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

/skill:brave-search           # 加载并执行技能
/skill:pdf-tools extract      # 加载技能并附带参数

命令后的参数会作为 User: <args> 附加到技能内容中。

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

{
  "enableSkillCommands": true
}

技能结构

一个技能是一个包含 SKILL.md 文件的目录。其余内容自由组织。

my-skill/
├── SKILL.md              # 必需：前置元数据 + 指令
├── scripts/              # 辅助脚本
│   └── process.sh
├── references/           # 详细文档，按需加载
│   └── api-reference.md
└── assets/
    └── template.json

SKILL.md 格式

---
name: my-skill
description: 这个技能做什么以及何时使用。请具体说明。
---

## My Skill

### 设置

首次使用抢跑一次：
```bash
cd /path/to/skill && npm install
```

### 用法

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

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

详见 [参考指南](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/references/REFERENCE.md) 了解详情。

前置元数据

根据 Agent Skills 规范：

名称规则

• 1-64 个字符
• 仅限小写字母、数字、连字符
• 不能以连字符开头或结尾
• 不能包含连续连字符 Pi 不要求名称与父目录匹配。Agent Skills 标准要求这样，但该要求对于多个工具共享的技能目录来说并不理想。

有效：pdf-processing，data-analysis，code-review 无效：PDF-Processing，-pdf，pdf--processing

描述最佳实践

描述决定了智能体何时加载该技能。请具体说明。

良好示例：

description: 从 PDF 文件中提取文本和表格，填写 PDF 表单，合并多个 PDF 文件。处理 PDF 文档时使用。

不佳示例：

description: 帮助处理 PDF。

验证

Pi 根据 Agent Skills 标准验证技能。大多数问题会产生警告，但技能仍会加载：

• 名称超过 64 个字符或包含无效字符
• 名称以连字符开头/结尾或包含连续连字符
• 描述超过 1024 个字符

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

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

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

示例

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

SKILL.md：

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

技能仓库

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

• 原文链接： github.com/badlogic/pi-m...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～