BYU 技术文档库

外观

Pi Agent Skills 技能系统 ​

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

Pi Agent 实现了 Agent Skills 标准。

什么是 Skill ​

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

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

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

Skill 工作原理 ​

整个加载过程分四步，核心思路是"先看目录，再读全文"。

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

需要注意，模型不一定主动读取，必要时在提示词中明确要求，或用 /skill:名称 强制加载。

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

Skill 的目录结构 ​

只有 SKILL.md 是必需的，其余目录按需创建。

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

SKILL.md 格式 ​

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

实例 ​

bash

---

name: my-skill

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

---

# My Skill

## 安装

首次使用前运行：

```bash

cd ~/projects/brave-search-skill && npm install

```

## 使用

```bash

bash scripts/process.sh <input>

```

## 参考

详见 [参考指南](references/api-reference.md)

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

Frontmatter 字段 ​

只有 name 和 description 必填，其余字段按需添加。

字段必填说明
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 会在全局和项目两个层级扫描 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 条目
CLI当前这次运行--skill 路径 显式加载，可重复传入

补充一点：在 ~/.agents/skills/ 与项目 .agents/skills/ 中，分组子目录里声明了合法 Frontmatter 的嵌套 .md 文件也会被识别，而顶层没有 Frontmatter 的 .md 会被忽略。

CLI 参数 \--no-skills 可禁用技能自动发现，但显式给出的 \--skill 路径 仍会加载。

校验与命名冲突 ​

Pi Agent 会按 Agent Skills 标准校验 Skill，多数问题只给出警告，Skill 仍会加载。

缺少 description 的 SKILL.md 不会被加载，畸形文件同样只给警告且不加载。

同名 Skill 来自不同位置时会发出警告，并保留最先发现的那个。

Skill 命令 ​

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

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

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

以 /skill:pdf-tools extract report.pdf 为例，展开后的内容大致如下：

bash
/skill:pdf-tools extract report.pdf

User: extract report.pdf

AI 收到这份内容后，会按 SKILL.md 中的指令去查找并执行 scripts/ 目录下的脚本。

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

实例 ​

bash

// 文件路径：~/.pi/agent/settings.json

{

  "enableSkillCommands": false

}

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

从其他工具导入 Skill ​

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

下面两个配置分别写入全局与项目的 settings.json，路径按你的实际目录调整。

实例 ​

bash

// 文件路径：~/.pi/agent/settings.json（全局导入）

{

  "skills": [

    "~/.claude/skills",

    "~/.codex/skills"

  ]

}

对于项目级的 Claude Code Skills：

实例 ​

bash

// 文件路径：.pi/settings.json（项目级导入）

{

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

}

Skills 中的指令可以要求 AI 执行任意操作，包括运行可执行文件。

在使用第三方 Skill 之前，建议先审查其内容。

完整 Skill 示例 ​

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

实例 ​

bash

---

name: brave-search

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

---

# Brave Search

## 安装

首次使用前安装依赖：

```bash

cd ~/projects/brave-search-skill && npm install

```

## 搜索

```bash

# 用 node 执行，无需可执行权限

node scripts/search.js "查询关键词"              # 基础搜索

node scripts/search.js "查询关键词" --content    # 包含页面内容

# 若已赋权（chmod +x scripts/search.js），也可直接执行

./scripts/search.js "查询关键词"

```

## 提取页面内容

```bash

node scripts/content.js https://example.com

```

Skill 仓库推荐 ​

这两个仓库提供了大量可直接使用的 Skill，安装前仍建议通读一遍内容。

仓库内容方向适用场景
Anthropic Skills文档处理（docx、pdf、pptx、xlsx）、网页开发日常办公文档批量处理、前端页面搭建
Pi Skills网页搜索、浏览器自动化、Google API、音频转录需要联网取数、自动化操作和多媒体转写的任务

AI 思考中...

Pi Agent 提示词模板

Pi Agent 配置详解

基于 VitePress 构建，部署于 GitHub Pages

Copyright © 2026 BYU 技术文档库 · 豫ICP备2026030124号