打造你的专属 Pi：上下文、技能与主题定制

📝

Pi（earendil-works/pi）定制完全指南：AGENTS.md/CLAUDE.md 上下文文件自动加载机制与搜索优先级、SYSTEM.md 完全替换 vs APPEND_SYSTEM.md 追加、Skill 渐进式披露与 SKILL.md 编写规范、Prompt Template 变量语法与分发、主题热重载与 51 个颜色 token。附代码审查/App Store 发布/数据库迁移三个实战 Skill 案例。

上下文文件让 AI 在第一条消息前就理解项目全貌；技能、提示模板和主题则让 AI 遵循你的工作流和审美。

什么是上下文文件

上下文文件是 pi 在启动时自动加载的 Markdown 文件，用于告诉 AI 关于项目和代码库的关键信息，相当于项目的”自我介绍”。

自动加载机制

pi 启动时会自动搜索并加载以下文件：

• ~/.pi/agent/AGENTS.md（全局，适用于所有项目）
• AGENTS.md 或 CLAUDE.md（从 cwd 向上遍历目录）

所有找到的文件会拼接后加入系统提示。

搜索路径优先级

~/.pi/agent/AGENTS.md        ← 全局（固定路径）
<git_root>/AGENTS.md         ← 项目根目录
<git_root>/CLAUDE.md         ← 兼容 Claude Code
<parent>/AGENTS.md           ← 父目录
<parent>/CLAUDE.md
<cwd>/AGENTS.md              ← 当前目录
<cwd>/CLAUDE.md

pi 从 cwd 开始向上遍历到 git 仓库根目录（如果没有 git 仓库则到文件系统根），合并所有找到的文件。

禁用：

pi --no-context-files        # 单次运行禁用
pi -nc "帮我重构代码"        # 简写形式

AGENTS.md 编写指南

一个好的 AGENTS.md 应该让 AI 在第一条消息之前就对项目有完整的理解。

# 项目概述
MyApp 是一个 iOS/Android 跨平台应用，使用 Expo + React Native 构建。
后端使用 Supabase 提供数据库和认证服务。

## 关键文档
- README.md - 项目简介和入门指南
- ARCHITECTURE.md - 架构设计文档
- CONTRIBUTING.md - 贡献指南

## 快速开始
- `npm start` 启动开发服务器
- `npm run ios` 在 iOS 模拟器中运行
- `npm run android` 在 Android 模拟器中运行
- `npm test` 运行测试

## 技术栈
| 层 | 技术 | 说明 |
|------|--------|------|
| 前端 | React Native + Expo | 主应用 |
| 路由 | Expo Router (file-based) | 文件系统路由 |
| 样式 | NativeWind (Tailwind) | 实用优先的 CSS |
| 后端 | Supabase | 数据库、认证、实时 |
| 状态 | React Query + Zustand | 服务端/客户端状态 |
| 测试 | Jest + Detox | 单元/端到端测试 |

## 项目结构
src/
├── app/          # Expo Router 页面
├── components/   # 可复用组件
├── hooks/        # 自定义 hooks
├── lib/          # 工具函数
├── providers/    # 上下文提供者
└── types/        # TypeScript 类型

## 代码规范
### TypeScript
- 尽可能使用 `strict` 模式
- 函数组件使用箭头函数
- Props 使用 `interface` 而非 `type`
- 避免使用 `any`，尽量用 `unknown`
### 命名约定
- 组件：PascalCase (`UserProfile`)
- 文件：kebab-case (`user-profile.tsx`)
- 函数：camelCase (`fetchUserData`)
- 常量：SCREAMING_SNAKE_CASE (`MAX_RETRY_COUNT`)

## 常见陷阱
1. **不要直接修改 `node_modules/`** — 使用 patch-package
2. **Expo Go 不支持原生模块** — 需要开发构建
3. **环境变量前缀必须是 `EXPO_PUBLIC_`** — 才能在客户端使用
4. **图片需要正确配置宽高** — 否则布局会跳动
5. **Supabase RLS 策略** — 不要绕过行级安全

系统提示定制

除了上下文文件，pi 还支持更底层的系统提示定制。

SYSTEM.md — 完全替换

创建 .pi/SYSTEM.md 来完全替换 pi 的默认系统提示：

你是一个专注于 iOS 开发的编码助手。
你的回复应该简洁、以代码为主。
除非有严重问题，否则不要给出安全警告。
优先使用 Swift 6 和 SwiftUI。

注意：这会完全替换 pi 的所有默认指令，包括工具使用指南。慎用。

APPEND_SYSTEM.md — 追加内容

创建 .pi/APPEND_SYSTEM.md（或全局 ~/.pi/agent/APPEND_SYSTEM.md）来追加到系统提示末尾，不替换默认行为。

额外指南
- 使用中文回复
- 优先使用函数式组件
- 每次修改代码前先读取完整的文件内容，不要假设

这是推荐的定制方式——保留 pi 的核心能力，同时补充你的需求。

使用场景对比

方式	适用场景
AGENTS.md	项目信息、规范、命令
APPEND_SYSTEM.md	行为习惯、偏好设置
SYSTEM.md	完全自定义的助手角色（专家级）

优先级

AGENTS.md (拼接)  ←  APPEND_SYSTEM.md (追加)  ←  SYSTEM.md (完全替换)

实际上：

• 如果有 SYSTEM.md，它完全替换默认系统提示
• AGENTS.md / CLAUDE.md 拼接在系统提示中
• APPEND_SYSTEM.md 追加在末尾
• --system-prompt CLI 参数替换所有
• --append-system-prompt CLI 参数追加在最后

团队协作中的上下文文件管理

版本控制

AGENTS.md 和 .pi/SYSTEM.md 应该纳入版本控制：

# 保留 .pi/*.md（上下文文件），排除其他
.pi/settings.json      # 个人配置不提交
.pi/extensions/        # 个人扩展不提交
!.pi/SYSTEM.md         # 团队系统提示要提交
!.pi/APPEND_SYSTEM.md
AGENTS.md              # 项目上下文要提交

模板化项目上下文

创建一个团队模板 template-AGENTS.md：

# {{PROJECT_NAME}} 项目上下文
## 技术栈
{{TECH_STACK}}
## 团队成员
| 姓名 | 角色 | 关注领域 |
|------|------|----------|
| {{NAME}} | {{ROLE}} | {{FOCUS}} |
## 代码规范
{{CODE_STANDARDS}}
## 常用命令
{{COMMON_COMMANDS}}

新项目初始化时，复制模板并替换变量。

多语言团队注意事项

• 上下文文件的语言应与团队使用的语言一致
• 如果团队使用混合语言，建议用英文写上下文文件，并在 APPEND_SYSTEM.md 中指定回复语言：

## 语言
请用中文回复，但保留英文的技术术语（如 API、Route、Component）。

什么是 Skill

Skill 是一个遵循 Agent Skills 标准的 Markdown 指令集。它告诉 AI 如何执行特定任务，包含详细的步骤、脚本和参考资料。

pi 实现了 Agent Skills 标准——一个开放的技能规范，技能文件在不同 AI 编码助手之间可移植。

按需加载，不污染核心指令

Skill 的核心机制是渐进式披露（Progressive Disclosure）：

1. 启动时，pi 扫描所有 Skill 目录，提取名称和描述
2. 只有描述会一直放在系统提示中（很轻量）
3. 当任务匹配时，AI 使用 read 工具加载完整的 SKILL.md
4. 然后 AI 按照指令执行

这意味着 Skill 的完整内容不会占用上下文窗口，只有匹配时才会加载。

两种触发方式

方式	说明
自动加载	AI 根据任务描述自动匹配合适的 Skill
手动触发	输入 /skill:name 强制加载指定 Skill

如果 AI 没有自动加载某个 Skill，可以通过手动触发来提示它：

/skill:brave-search
/skill:code-review 帮我审查刚刚修改的代码

可以传递参数，参数会被追加到 Skill 内容后作为 User: <args>。

安装并使用已有的 Skill

# 安装包含技能的 pi 包
pi install git:github.com/badlogic/pi-skills
# 然后输入 /list 查看可用的技能列表

Skill 仓库推荐：

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

手动放置技能文件

你可以直接创建或复制 SKILL.md 文件到以下位置：

位置	作用域	说明
~/.pi/agent/skills/	用户级（全局）	所有项目可见
~/.agents/skills/	用户级（通用）	兼容其他 Agent 的工具
.pi/skills/	项目级	仅当前项目
.agents/skills/	项目级（从 cwd 向上搜索）	兼容其他 Agent

查看已启用的技能：启动 pi 时，启动头会显示 Skills: N（已发现 N 个技能）。也可以在 settings 中控制技能命令的启用：

{
  "enableSkillCommands": true
}

编写你的第一个 Skill

一个 Skill 是一个目录，核心是 SKILL.md 文件，其他辅助文件自由组织。

my-skill/
├── SKILL.md           # 必需：frontmatter + 指令
├── scripts/           # 辅助脚本（可选）
│   └── analyze.sh
├── references/        # 参考文档（可选，按需加载）
│   └── api-reference.md
└── assets/
    └── template.json

SKILL.md 文件结构：

---
name: my-skill
description: 描述这个技能做什么以及何时使用。要具体。
---
# My Skill

## Setup
首次使用前运行：
cd /path/to/skill && npm install

## Usage
./scripts/process.sh <input>

Frontmatter 字段

字段	必需	说明
name	是	最长 64 字符。小写字母、数字、连字符。无需与目录名一致
description	是	最长 1024 字符。描述技能做什么和何时使用。决定 AI 何时加载此技能
license	否	许可证名称或引用
compatibility	否	环境要求
metadata	否	自定义键值对
allowed-tools	否	空格分隔的预批准工具（实验性）
disable-model-invocation	否	true 时隐藏 Skill，仅 /skill:name 可触发

描述的最佳实践

描述决定了 AI 何时自动加载这个 Skill。要具体：

• 好：description: 从 PDF 文件中提取文本和表格、填写 PDF 表单、合并多个 PDF 文件。处理 PDF 文档时使用。
• 差：description: 帮助处理 PDF。

Skill 发现规则

Pi 按以下顺序搜索 Skill：

• 用户级：~/.pi/agent/skills/（直接放 .md 文件，或目录含 SKILL.md）
• 用户级兼容：~/.agents/skills/
• 项目级：.pi/skills/（仅在项目被信任后）
• 项目级兼容：.agents/skills/（从 cwd 向上搜索到 git 根目录）
• 包：已安装的 pi 包中的 skills/ 目录
• 设置：settings.json 中的 skills 数组
• CLI：--skill <path> 参数

项目级 vs 用户级技能

维度	用户级	项目级
路径	~/.pi/agent/skills/	.pi/skills/
加载时机	始终	项目被信任后
适用场景	个人常用工作流	团队共享的工作流
版本控制	个人目录	可纳入项目 git 仓库

项目信任机制的影响

项目级的 Skill（.pi/skills/）只有在项目被信任后才会加载。首次进入一个新项目时，pi 会询问：

Trust this project?
/path/to/project
[Yes] [No]

信任后，项目级资源和配置才能生效。可以通过 --approve / --no-approve 跳过交互。

实战案例一：代码审查 Skill

---
name: code-review
description: 对代码变更进行全面审查，检查 bug、安全问题和性能问题。提交 PR 前使用。
---
# Code Review

## Step 1: 了解变更范围
git diff --stat

## Step 2: 逐文件审查
对每个变更的文件，检查：
- 逻辑错误和边界情况
- 安全漏洞（注入、XSS、权限）
- 性能问题（不必要的循环、内存泄漏）
- 错误处理是否充分
- 代码风格是否一致

## Step 3: 生成审查报告
# 代码审查报告
## 概述
- 文件数：N
- 变更行数：+N / -N
- 严重问题：N
- 建议：N
## 问题清单
...

实战案例二：一键发布 App Store

---
name: appstore-submit
description: 构建并提交 iOS 应用到 App Store Connect。准备发布时使用。
---
# App Store Submit

## Prerequisites
- Xcode 和开发者账号已配置
- `asc` CLI 已安装

## Steps
1. 版本号递增
2. 构建归档
3. 上传到 App Store Connect
4. 填写版本信息
5. 提交审核

## Commands
# 版本递增
xcrun agvtool new-marketing-version $VERSION
xcrun agvtool next-version -all
# 构建
xcodebuild -workspace App.xcworkspace -scheme App archive
# 上传
xcodebuild -upload-to-app-store ...

实战案例三：数据库迁移检查

---
name: db-migration-check
description: 检查数据库迁移脚本的安全性和兼容性。部署前使用。
---
# Database Migration Check

## Step 1: 列出未应用的迁移
# 根据项目类型选择
ls -la migrations/*.sql | head -20

## Step 2: 逐文件检查风险
对每个迁移文件检查：
- 是否存在 `DROP TABLE` 或 `DROP COLUMN`（数据丢失风险）
- 是否有 `ALTER COLUMN` 改变类型（兼容性问题）
- 是否有 `RENAME` 操作（影响现有查询）
- 索引创建是否会阻塞写入

## Step 3: 生成安全报告
列出：
- ✅ 安全迁移
- ⚠️ 有风险的操作（需要人工确认）
- ❌ 禁止的操作

什么是 Prompt Template

Prompt Template 是可复用的 Markdown 提示片段，通过 /templatename 在编辑器中展开。

与 Skill 的区别

维度	Prompt Template	Skill
本质	可展开的文本片段	带执行步骤的指令集
触发方式	/name 展开到编辑器	AI 自动加载或 /skill:name
复杂度	简单文本，支持变量	含脚本、参考资料、资源文件
适用场景	固定格式的任务、模板化写作	完整的工作流、工具链操作
内容	提示文本 + 变量	步骤 + 脚本 + 参考文献

简单来说：Template 是让你少打字，Skill 是让 AI 知道怎么做。

适合的场景：代码审查模板（每次说差不多的话）、PR 描述生成器、安全审计模板、架构设计评审模板、错误日志分析模板、报告生成模板。

创建与使用

创建 ~/.pi/agent/prompts/review.md：

---
description: Review staged git changes
---
Review the staged changes (`git diff --cached`). Focus on:
- Bugs and logic errors
- Security issues
- Error handling gaps

• 文件名成为命令名：review.md → /review
• description 可选：如果缺失，使用第一个非空行
• argument-hint 可选：显示在自动补全中的参数提示

变量替换：

模板支持简单的变量语法：

---
description: Create a component
argument-hint: "<name> [features...]"
---
Create a React component named $1 with features: $@

语法	说明
$1, $2, …	位置参数
$@ 或 $ARGUMENTS	所有参数连接在一起
${1:-default}	参数 1 存在时使用，否则用 default
${@:N}	从第 N 个位置开始的参数
${@:N:L}	从第 N 个位置开始，取 L 个参数

默认值示例：

---
description: Summarize with custom bullet count
---
Summarize the current state in ${1:-7} bullet points.

这样 /summarize 用 7 个要点，/summarize 5 用 5 个要点。

使用方式

在编辑器输入 / 即可触发自动补全：

/review                    # 展开 review.md
/component Button          # 展开并传入参数
/component Button "click handler"   # 多个参数

模板管理

位置	作用域	说明
~/.pi/agent/prompts/*.md	用户级	全局可用
.pi/prompts/*.md	项目级	项目被信任后加载
包中的 prompts/	包级	通过 pi 包分发

发现规则：prompts/ 目录中的模板发现是非递归的（只扫描顶层 .md 文件）。如果要使用子目录中的模板，需要通过 settings 或包清单显式添加。

在 pi 包中分发模板

通过 package.json 的 pi 清单分发：

{
  "name": "my-pi-templates",
  "keywords": ["pi-package"],
  "pi": {
    "prompts": ["./prompts"]
  }
}

进阶技巧

组合多个模板：模板可以互相引用：

---
description: Generate PR description
---
First, analyze the changes:
git diff --stat
git diff --cached

Then write a PR description covering:
1. What changed and why
2. Key implementation details
3. Testing notes
4. Breaking changes (if any)

模板中引用上下文文件：模板中可以指示 AI 读取特定文件作为上下文：

---
description: Review codebase architecture
---
Review the architecture of this project. Read:
- @README.md for project overview
- @package.json for dependencies
- @tsconfig.json for TypeScript config
Focus on: architectural decisions, dependency management, build configuration.

模板 + 管道输入：结合打印模式使用：

cat README.md | pi -p /review

Argument Hints：显示在自动补全中的参数提示：

---
description: Review PRs from URLs with structured issue and code analysis
argument-hint: "<PR-URL>"
---

渲染效果：

→ pr <PR-URL> — Review PRs from URLs with structured issue and code analysis
is <issue>    — Analyze GitHub issues (bugs or feature requests)
wr [instructions] — Finish the current task end-to-end
cl — Audit changelog entries before release

示例模板库

PR 描述生成器：

---
description: Generate PR description from staged changes
argument-hint: "[focus]"
---
Generate a GitHub PR description from the staged changes (git diff --cached).
Structure:
## Summary
Brief description of the changes
## Changes
- List key changes with file paths
## Testing
- How was this tested?
## Notes
- Any additional context

安全审计模板：

---
description: Security audit checklist for code changes
---
Security audit for the recent changes. Check:
1. **Authentication & Authorization**
   - Are permissions checked on every protected endpoint?
   - Is there any privilege escalation risk?
2. **Input Validation**
   - Are all user inputs sanitized?
   - Any SQL injection or XSS vectors?
3. **Data Protection**
   - Are secrets hardcoded?
   - Is sensitive data properly encrypted?
4. **Dependencies**
   - Any known vulnerable dependencies?
   - Are dependencies up to date?

架构设计评审模板：

---
description: Architecture design review
argument-hint: "<component>"
---
Architecture review of $1. Evaluate:
- **Single Responsibility**: Does this component have a clear purpose?
- **Dependencies**: Are dependencies well-defined and minimal?
- **Testability**: Can this be easily tested in isolation?
- **Scalability**: Will this design scale with the codebase?
- **Extensibility**: Can new features be added without modifying existing code?
For each concern, rate: ✅ Good / ⚠️ Needs Improvement / ❌ Problem

主题定制

内置主题

pi 内置两个主题：

• dark - 深色背景（默认）
• light - 浅色背景（自动检测）

首次启动时，pi 会自动检测你的终端背景色，默认选择 dark 或 light。

切换主题

# 在交互模式中
/settings
# 选择 Theme 选项
# 或直接编辑 settings.json：

{
  "theme": "dark"
}

热重载特性

这是 pi 主题最酷的特性之一：修改当前正在使用的主题文件后，pi 会自动重新加载，修改立即生效。你可以在运行 pi 的同时编辑主题文件，实时预览效果。

创建自定义主题

主题文件位置：

~/.pi/agent/themes/
└── my-theme.json

发现路径与扩展类似：

位置	作用域
~/.pi/agent/themes/*.json	用户级
.pi/themes/*.json	项目级
包中的 themes/	包级

基本结构：

{
  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
  "name": "my-theme",
  "vars": {
    "primary": "#00aaff",
    "gray": 242
  },
  "colors": {
    "accent": "primary",
    "border": "primary",
    "text": ""
  }
}

字段	说明
name	必填，必须唯一，不能包含 /
$schema	可选，开启编辑器的自动补全和校验
vars	可选，定义可复用的颜色变量
colors	必填，定义 51 个颜色 token

51 个颜色 token 一览

核心 UI（11 个）：

Token	用途
accent	主色调（Logo、选中项、光标）
border	普通边框
borderAccent	高亮边框
borderMuted	柔和边框（编辑器）
success	成功状态
error	错误状态
warning	警告状态
muted	次要文本
dim	第三级文本
text	默认文本（通常设为 "" 使用终端默认色）
thinkingText	思考块文本

背景与内容（11 个）：

Token	用途
selectedBg	选中行背景
userMessageBg	用户消息背景
userMessageText	用户消息文本
customMessageBg	扩展消息背景
customMessageText	扩展消息文本
customMessageLabel	扩展消息标签
toolPendingBg	工具框（等待中）
toolSuccessBg	工具框（成功）
toolErrorBg	工具框（错误）
toolTitle	工具标题
toolOutput	工具输出文本

Markdown（10 个）：

Token	用途
mdHeading	标题
mdLink	链接文本
mdLinkUrl	链接 URL
mdCode	行内代码
mdCodeBlock	代码块内容
mdCodeBlockBorder	代码块边框
mdQuote	引用文本
mdQuoteBorder	引用边框
mdHr	水平分割线
mdListBullet	列表项标记

差异显示（3 个）：

Token	用途
toolDiffAdded	新增行
toolDiffRemoved	删除行
toolDiffContext	上下文行

语法高亮（9 个）：

Token	用途
syntaxComment	注释
syntaxKeyword	关键字
syntaxFunction	函数名
syntaxVariable	变量
syntaxString	字符串
syntaxNumber	数字
syntaxType	类型
syntaxOperator	运算符
syntaxPunctuation	标点符号

思考层级边框（6+1 个）：

Token	用途
thinkingOff	思考关闭
thinkingMinimal	最小思考
thinkingLow	低度思考
thinkingMedium	中度思考
thinkingHigh	高度思考
thinkingXhigh	极高思考
thinkingMax	最大思考（可选，默认用 Xhigh）

Bash 模式（1 个）：

Token	用途
bashMode	Bash 模式下的编辑器边框

颜色格式

格式	示例	说明
Hex	"#ff0000"	6 位十六进制 RGB
256 色	39	xterm 256 色调色板索引（0-255）
变量引用	"primary"	引用 vars 中的定义
默认色	""	使用终端的默认颜色

256 色调色板：

• 0-15：基础 ANSI 颜色（终端相关）
• 16-231：6×6×6 RGB 立方体（16 + 36×R + 6×G + B）
• 232-255：灰度渐变

终端兼容性

pi 使用 24 位真彩色。检查你的终端是否支持：

echo $COLORTERM   # 应输出 "truecolor" 或 "24bit"

如果你的终端只支持 256 色，pi 会自动回退到最近的近似颜色。

分享与安装主题

通过 pi 包分发——在 package.json 中声明主题目录：

{
  "name": "my-pi-themes",
  "keywords": ["pi-package"],
  "pi": {
    "themes": ["./themes"]
  }
}

然后通过 npm 或 git 分享：

pi install git:github.com/user/pi-nord-theme

设计建议

背景	建议
深色终端	使用亮色、高饱和度的颜色，高对比度
浅色终端	使用暗色、柔和的颜色，低对比度

配色灵感：Nord、Gruvbox、Tokyo Night、Catppuccin。

本文转载自微信公众号（youngxhui），内容有删节整理。