Pi 手动添加

Pi 里可以手动添加两类内容：

1. 规则（Rules / Context）：每次对话自动生效
2. Skill：按需加载，适合特定任务流程

---

一、添加项目级规则

方式 1：创建 AGENTS.md

在项目根目录创建：

touch AGENTS.md

例如：

# Project Rules

## General

- 使用 TypeScript，不要使用 JavaScript
- 修改代码前先阅读相关文件
- 不要修改 node_modules、dist 和 .env 文件
- 所有代码修改后运行相关测试

## Code Style

- 使用 2 个空格缩进
- 函数和变量使用 camelCase
- React 组件使用 PascalCase
- 优先使用已有工具函数，避免重复实现

## Validation

修改完成后执行：

```bash
npm run lint
npm test

如果测试无法执行，需要说明原因。

Pi 启动时会自动读取：

```text
~/.pi/agent/AGENTS.md       # 全局规则
项目父目录/AGENTS.md         # 父目录规则
项目根目录/AGENTS.md         # 项目规则
当前目录/AGENTS.md

也可以使用：

CLAUDE.md

Pi 会兼容读取 CLAUDE.md。如果某个目录下存在：

AGENTS.override.md

它会优先替代该目录下的 AGENTS.md 或 CLAUDE.md。

推荐的项目结构

your-project/
├── AGENTS.md
├── .pi/
│   ├── settings.json
│   └── skills/
└── src/

验证是否生效

启动 Pi 时，顶部启动信息会显示加载的 AGENTS.md 文件。

也可以在会话中输入：

请告诉我当前加载了哪些项目规则，并总结关键要求。

---

二、添加全局规则

如果希望所有项目都使用同一套规则：

mkdir -p ~/.pi/agent
touch ~/.pi/agent/AGENTS.md

例如：

# Global Development Rules

- 始终先理解现有代码，再进行修改
- 不要执行破坏性命令
- 不要删除用户未明确要求删除的文件
- 修改完成后说明修改了哪些文件
- 如果需求存在歧义，先询问用户

全局规则适合放：

• 通用编码习惯
• Git 使用规范
• 安全要求
• 个人偏好
• 回复格式

项目专属规则则放到项目根目录的 AGENTS.md。

---

三、使用 SYSTEM.md 修改 Pi 的系统提示词

如果你需要修改 Pi 的底层系统提示词，可以创建：

.pi/SYSTEM.md

或者全局创建：

~/.pi/agent/SYSTEM.md

注意：SYSTEM.md 是替换默认系统提示词，风险较高。除非你清楚默认提示词内容，否则不建议直接覆盖。

更推荐使用：

.pi/APPEND_SYSTEM.md

或者：

~/.pi/agent/APPEND_SYSTEM.md

它会在默认系统提示词后追加内容。

例如 .pi/APPEND_SYSTEM.md：

## Additional Project Instructions

- 你是本项目的高级前端工程师
- 任何修改都必须保持现有 API 兼容
- 不要引入新的依赖，除非用户明确同意
- 优先使用项目已有的组件和工具函数
- 回复时使用中文

三者区别

文件	作用
AGENTS.md	项目上下文和开发规则，推荐使用
SYSTEM.md	完全替换 Pi 默认系统提示词
APPEND_SYSTEM.md	在默认系统提示词后追加规则

一般推荐：

AGENTS.md                 # 项目规则
APPEND_SYSTEM.md          # 需要影响 Agent 行为的额外指令
SYSTEM.md                 # 高级定制，谨慎使用

---

四、手动添加 Skill

Skill 是一个目录，里面至少包含一个 SKILL.md。

创建项目级 Skill

mkdir -p .pi/skills/code-review
touch .pi/skills/code-review/SKILL.md

内容示例：

---
name: code-review
description: 审查代码中的功能缺陷、安全问题、性能问题和测试缺失。用户要求 code review、代码审查或检查代码质量时使用。
---

# Code Review Skill

## Review Process

按照以下步骤执行：

1. 先阅读相关源代码和测试文件
2. 查看当前 git diff
3. 理解代码修改的业务目的
4. 检查功能正确性
5. 检查边界条件和异常处理
6. 检查安全问题
7. 检查性能问题
8. 检查测试覆盖率

## Output Format

按照严重程度输出问题：

### Critical

会导致数据丢失、安全漏洞或系统不可用的问题。

### Major

明显的功能缺陷或重要的异常处理问题。

### Minor

代码质量、可维护性或轻微性能问题。

每个问题包含：

- 文件路径和行号
- 问题描述
- 影响
- 修改建议

如果没有发现问题，明确说明"未发现明显问题"。

然后重新启动 Pi，或者在会话中执行：

/reload

---

五、调用 Skill

通过命令强制调用

/skill:code-review

也可以带参数：

/skill:code-review 请重点检查安全问题

让 Pi 自动判断

Skill 的 description 会被放入系统提示词中。比如用户说：

帮我审查这次提交的代码

Pi 可能自动加载 code-review Skill。

不过自动加载并不总是可靠。如果希望强制执行，建议直接使用：

/skill:code-review

---

六、全局 Skill

如果希望所有项目都能使用：

mkdir -p ~/.pi/agent/skills/code-review
touch ~/.pi/agent/skills/code-review/SKILL.md

目录结构：

~/.pi/agent/skills/
└── code-review/
    ├── SKILL.md
    ├── references/
    │   └── review-checklist.md
    └── scripts/
        └── collect-diff.sh

Skill 可以包含辅助文件：

# Code Review Skill

详细审查规则请阅读：

- [审查清单](references/review-checklist.md)

如果需要收集 Git 信息，可以执行：

```bash
./scripts/collect-diff.sh

Skill 中的相对路径以 Skill 所在目录为基准。

---

## 七、Skill 的标准 Frontmatter

最少需要：

```yaml
---
name: skill-name
description: 说明这个 Skill 做什么，以及什么时候使用
---

name 要求：

• 小写字母
• 数字
• 连字符
• 不能以连字符开头或结尾
• 不能出现连续连字符

例如：

name: frontend-debug

不要写成：

name: Frontend_Debug

推荐的 description 写法

不推荐：

description: 帮助处理前端问题

推荐：

description: 用于排查 React 页面白屏、组件渲染异常、状态更新错误和浏览器控制台报错。用户要求调试前端问题时使用。

description 会直接影响 Pi 是否能够自动匹配这个 Skill。

---

八、通过配置添加外部 Skill

也可以在：

~/.pi/agent/settings.json

添加：

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills",
    "/path/to/my-skills"
  ]
}

项目级配置可以放在：

.pi/settings.json

例如：

{
  "skills": [
    ".pi/skills",
    "../shared-skills"
  ],
  "enableSkillCommands": true
}

还可以通过命令行临时加载：

pi --skill ./skills/code-review/SKILL.md

多个 Skill：

pi \
  --skill ./skills/code-review/SKILL.md \
  --skill ./skills/frontend-debug/SKILL.md

---

九、规则和 Skill 应该怎么分工？

放到 AGENTS.md

适合始终生效的内容：

- 项目使用 pnpm
- 所有回复使用中文
- 不要修改 API 返回结构
- 修改后必须运行测试
- 不允许操作 .env

放到 Skill

适合特定任务流程：

- 如何执行代码审查
- 如何发布 npm 包
- 如何排查线上问题
- 如何生成数据库迁移
- 如何编写 React 组件
- 如何处理 PDF、Excel、文档

一个实用示例

AGENTS.md
├── 项目技术栈
├── 通用代码规范
├── 测试命令
├── 禁止事项
└── Git 规范

.pi/skills/
├── code-review/
├── frontend-debug/
├── release/
└── database-migration/

推荐方案

对于大多数项目，建议这样配置：

项目根目录/
├── AGENTS.md
└── .pi/
    ├── APPEND_SYSTEM.md
    └── skills/
        ├── code-review/
        │   └── SKILL.md
        └── frontend-debug/
            └── SKILL.md

其中：

• AGENTS.md：项目永久规则
• .pi/APPEND_SYSTEM.md：少量全局行为约束
• .pi/skills/*/SKILL.md：按场景加载的专业流程

修改后执行：

/reload

如果项目包含项目级 .pi 配置，Pi 可能会要求确认项目信任；确认信任后，项目级 Skill 和扩展才会被加载。