14  Agent Skills

14.1 Skills 概述

Skills（技能）是自包含的能力包，Agent 按需加载。每个 Skill 提供特定任务的专业工作流、安装说明、辅助脚本和参考文档。

Pi 实现了 Agent Skills 标准，这意味着 Pi 的 Skills 可以与 Claude Code、OpenAI Codex 等其他兼容 Agent Harness 的工具共享使用。

Tip

让 Pi 帮你创建 Skill！直接在对话中说”帮我创建一个 Skill，实现 XXX 功能”。

14.2 Skills 位置

Pi 从以下位置加载 Skills：

位置 作用域 说明
~/.pi/agent/skills/ 全局 所有项目共享
~/.agents/skills/ 全局共享 跨 Harness 共享（Claude Code、Codex 等）
.pi/skills/ 项目级 需项目受信任后加载
.agents/skills/ 项目级共享 cwd 及父目录（至 git 仓库根目录）
包的 skills/ 目录 包级 通过 Pi 包分发
--skill <path> CLI 仅本次运行

14.2.1 发现规则

  • 在 ~/.pi/agent/skills/ 和 .pi/skills/ 中，根目录 .md 文件作为独立 Skill 被发现
  • 所有 Skills 位置中，包含 SKILL.md 的目录会被递归发现
  • 在 ~/.agents/skills/ 和项目 .agents/skills/ 中，根 .md 文件被忽略（只有目录形式有效）
  • 使用 --no-skills 禁用发现（显式 --skill 路径仍会加载）
Warning

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

14.3 跨 Harness 使用

Pi 的 Skills 兼容 Agent Skills 标准，可以直接使用来自其他 Harness 的 Skills。

14.3.1 使用 Claude Code Skills

在 settings.json 中添加 Claude Code 的 Skill 目录：

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

14.3.2 使用 OpenAI Codex Skills

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

14.3.3 项目级共享

在项目的 .pi/settings.json 中：

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

路径相对于 settings 文件解析。这使得同一套 Skills 可以在不同 AI 编程助手中共享使用。

14.4 工作原理：渐进式披露

Skills 采用渐进式披露（Progressive Disclosure）机制，这是其设计的核心理念：

graph LR
    A[启动时扫描] --> B[提取名称和描述]
    B --> C[系统提示包含 Skill 列表]
    C --> D{任务匹配?}
    D -->|是| E[Agent 读取完整 SKILL.md]
    D -->|否| F[不加载，节省上下文]
    E --> G[执行 Skill 指令]
    G --> H[引用脚本和资源]

  1. 启动时：Pi 扫描所有 Skills 位置，提取每个 Skill 的名称和描述
  2. 系统提示：可用 Skills 以 XML 格式包含在系统提示中
  3. 按需加载：当任务匹配时，Agent 使用 read 工具加载完整的 SKILL.md
  4. 执行指令：Agent 按照指令执行，使用相对路径引用脚本和资源
Note

模型并不总是自动加载匹配的 Skill。可以通过提示语或 /skill:name 命令强制加载。

14.5 Skill 命令

Skills 注册为 /skill:name 斜杠命令：

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

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

通过 settings.json 或交互式 /settings 启用：

{
  "enableSkillCommands": true
}

14.6 Skill 结构

一个 Skill 是一个包含 SKILL.md 文件的目录，其余内容自由组织：

my-skill/
├── SKILL.md           # 必须：frontmatter + 指令
├── scripts/           # 辅助脚本
│   └── process.sh
├── references/        # 按需加载的详细文档
│   └── api-reference.md
└── assets/            # 模板和其他资源
    └── template.json

14.7 SKILL.md 格式

SKILL.md 文件由 YAML frontmatter 和 Markdown 正文组成：

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

Use relative paths from the skill directory:

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

14.7.1 Frontmatter 字段

根据 Agent Skills 规范：

字段 必需 说明
name ✅ 最长 64 字符。小写 a-z、0-9、连字符
description ✅ 最长 1024 字符。描述 Skill 的用途和使用场景
license ❌ 许可证名称或对捆绑文件的引用
compatibility ❌ 最长 500 字符。环境要求说明
metadata ❌ 任意键值对
allowed-tools ❌ 空格分隔的预批准工具列表（实验性）
disable-model-invocation ❌ 为 true 时从系统提示中隐藏，用户必须用 /skill:name

14.7.2 命名规则

  • 1-64 个字符
  • 仅小写字母、数字、连字符
  • 不能以连字符开头或结尾
  • 不能有连续的连字符
示例 是否有效
pdf-processing ✅
data-analysis ✅
code-review ✅
PDF-Processing ❌ 包含大写字母
-pdf ❌ 以连字符开头
pdf--processing ❌ 连续连字符
Note

Pi 不要求 name 与父目录名匹配。Agent Skills 标准要求匹配，但 Pi 对此放宽了限制，因为共享 Skill 目录在不同工具间使用时，目录名可能不同。

14.7.3 描述最佳实践

描述决定了 Agent 何时加载该 Skill。描述要具体明确：

好的示例 ✅：

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.

好的描述应该包含： - 做什么：具体功能描述 - 何时用：使用场景说明 - 关键词：方便模型匹配相关任务

14.8 验证

Pi 根据 Agent Skills 标准验证每个 Skill。大多数问题会产生警告但不会阻止加载：

  • 名称超过 64 字符或包含无效字符 → ⚠️ 警告，仍加载
  • 名称以连字符开头/结尾或有连续连字符 → ⚠️ 警告，仍加载
  • 描述超过 1024 字符 → ⚠️ 警告，仍加载
  • 缺少描述的 Skill 不会被加载 → ❌ 错误

未知的 frontmatter 字段会被忽略。

名称冲突（不同位置的相同名称）会产生警告，并保留第一个发现的 Skill。

14.9 完整示例

以下是一个 brave-search Skill 的完整示例：

目录结构：

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

14.10 Skill 仓库

以下是一些知名的 Skill 仓库资源：

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

你也可以创建自己的 Skill 仓库并发布到 npm 或 GitHub，让其他 Pi 用户使用。通过 Pi 包（见下一章）可以方便地分发 Skills。