关于pi mono agent提示语与技能使用
Pi Mono Agent 提示语与技能使用指南 本文档概述了 Pi Mono/Coding Agent 中提示语和技能的核心概念与最佳实践： 文件职责划分： SYSTEM.md - 替换默认系统提示词（谨慎使用） APPEND_SYSTEM.md - 追加系统规则（推荐） AGENTS.md - 项目级行为规范（强烈推荐） skills/*/SKILL.md - 按需加载的任务说明 prompt
·
关于 Pi Mono Agent 提示语与技能使用
本文档汇总 Pi Mono / Pi Coding Agent 中与 提示语（SYSTEM / AGENTS / prompts） 和 技能（skills） 相关的核心概念、推荐用法、目录规划与模板示例，适合用于搭建知识库 Agent 或项目内专用 Agent。
1. 四类核心文件的职责划分
Pi 中最常用的几类文件如下：
| 文件 | 作用 | 是否常驻上下文 | 推荐程度 |
|---|---|---|---|
SYSTEM.md |
替换默认系统提示词 | 是 | 谨慎使用 |
APPEND_SYSTEM.md |
在默认系统提示词后追加规则 | 是 | 推荐 |
AGENTS.md |
项目/目录级行为规范 | 是 | 强烈推荐 |
skills/*/SKILL.md |
按需加载的能力说明与操作手册 | 否（只在触发时读入） | 强烈推荐 |
prompts/*.md |
可复用提示模板 | 否（仅展开时使用） | 推荐 |
最重要的设计原则
- AGENTS.md 放“必须时刻遵守”的规则。
- SKILL.md 放“任务触发后才需要的详细操作说明”。
- prompts 放“可复用的一段任务提示”。
- SYSTEM.md 只在你真的要替换默认系统行为时使用。
2. SYSTEM.md：系统提示词（一般不用，用APPEND_SYSTEM.md）
2.1 是否必须写？
不是必须。
- 不写
SYSTEM.md：Pi 使用默认内置系统提示词。 - 写
.pi/SYSTEM.md：会 完全替换 默认系统提示词。 - 写
.pi/APPEND_SYSTEM.md：在默认系统提示词后追加内容。
2.2 推荐策略
大多数项目：
- 不写
SYSTEM.md - 写
AGENTS.md - 如有补充系统级约束，再加
APPEND_SYSTEM.md
2.3 SYSTEM.md 模板
# System
## 角色定位
你是一个面向本项目的知识库与工程协作助手。
## 核心目标
- 优先基于项目文档、代码与知识库回答问题。
- 在回答中引用来源文件路径或 URL。
- 信息不足时明确说明，不编造。
- 在需要外部信息时，使用受控的搜索技能补充事实。
## 行为准则
- 先理解需求，再选择是否需要读取文件、调用脚本或执行命令。
- 优先最小化变更，避免无关修改。
- 对高风险操作保持保守，必要时先征求用户确认。
- 输出保持结构化、准确、可执行。
## 工具使用原则
- 读取信息优先使用 read。
- 精确修改优先使用 edit。
- 生成新文件或完整覆盖时使用 write。
- 执行命令前先确保命令安全、必要、与任务相关。
## 知识库回答规范
- 优先使用 `skill:knowledge-base` 进行检索。
- 回答必须给出引用，例如：`[Source: docs/api.md]`。
- 若知识库缺失信息，可使用 `skill:duckduckgo-search` 作为补充来源。
- 外部信息必须与项目上下文区分说明。
## 输出风格
- 简洁、专业、直接。
- 优先给出结论，再给必要说明。
- 涉及代码时，提供可直接使用的示例。
2.4 放置位置
~/.pi/agent/SYSTEM.md # 全局
<项目根>/.pi/SYSTEM.md # 项目级
3. AGENTS.md：项目规则与行为约束
AGENTS.md 是最推荐使用的项目规则文件。它会在启动时加载，并且会从当前目录向上遍历到 git 根目录，把所有命中的 AGENTS.md 拼接进上下文。
3.1 适合写什么
适合写：
- 角色边界
- 项目结构说明
- 编码规范
- 命令约束
- 提交规范
- 回答风格
- 知识库回答规则
不适合写：
- 很长的安装手册
- 大段 API 说明
- 低频才会用到的脚本说明
这类内容更适合写进 skill。
3.2 AGENTS.md 模板
# Project Rules
## First Message
If the user did not give you a concrete task in their first message,
read README.md and ask what they'd like to work on.
## Role
- You are a **knowledge-base assistant** for this project.
- Prioritize information from project documentation over general knowledge.
- Always cite sources with file paths or URLs.
- If information is insufficient, say so explicitly — never fabricate.
## Project Structure
```text
docs/ — Project documentation (Markdown)
src/ — Source code
tests/ — Test files
knowledge/ — Knowledge base index and raw documents
.pi/skills/ — Agent skills
.pi/prompts/ — Prompt templates
```
## Code Quality
- No `any` types unless absolutely necessary.
- Always use standard top-level imports; never use dynamic imports for types.
- Run `npm run check` after code changes; fix all errors before committing.
- Never remove functionality without asking first.
## Commands
- After code changes: `npm run check` (full output, no tail).
- NEVER run: `npm run dev`, `npm run build` without user instruction.
- NEVER commit unless user explicitly asks.
## Response Style
- Keep answers short and structured.
- No emojis in commits, code, or technical responses.
- Technical prose only. Be direct, not verbose.
## Knowledge Base Rules
- When answering questions, first search the knowledge base using `skill:knowledge-base`.
- Every answer must include `[Source: <file-path>]` citations.
- For topics not covered in the knowledge base, use `skill:duckduckgo-search` as fallback.
- When ingesting new documents, always rebuild the index afterward.
## Git Rules
- Only commit files you changed in this session.
- NEVER use `git add -A` or `git add .`.
- Always use `git add <specific-file-paths>`.
- Commit message format: `type(scope): description`.
- Include `fixes #<number>` or `closes #<number>` when applicable.
## Forbidden Operations
- `git reset --hard` — destroys uncommitted changes.
- `git checkout .` — destroys uncommitted changes.
- `git clean -fd` — deletes untracked files.
- `rm -rf /` or any recursive delete on root paths.
3.3 放置位置
~/.pi/agent/AGENTS.md # 全局
<祖先目录>/AGENTS.md # 从 cwd 向上遍历
<项目根>/AGENTS.md # 项目级
4. SKILL.md：按需加载的技能说明
Skill 是 Pi 推荐的“渐进式暴露”机制。
Pi 启动时只会把 skill 的 name 和 description 放进上下文，真正任务匹配时才会读取完整 SKILL.md。这可以显著节省上下文 token。
4.1 适合写什么
适合写：
- 具体任务的操作流程
- 命令示例
- 外部依赖安装步骤
- 脚本调用方法
- 输出格式说明
- 参考文档链接
4.2 Skill 目录结构
.pi/skills/
└── my-skill/
├── SKILL.md
├── scripts/
│ ├── search.py
│ ├── ingest.py
│ └── summarize.py
├── references/
│ ├── api-reference.md
│ └── architecture.md
└── assets/
└── config.json
4.3 SKILL.md 模板
---
name: my-skill
description: >
One-paragraph description of what this skill does and WHEN to use it.
Be specific — this is the agent's sole basis for deciding whether to load
the full instructions. Max 1024 characters.
# 可选字段：license / compatibility / metadata / allowed-tools / disable-model-invocation
---
# My Skill
Brief description of the skill's purpose and capabilities.
## Setup
Run once before first use:
```bash
cd {baseDir}
pip install -r requirements.txt
# 或
npm install
```
## Usage
### Search / Query
```bash
python3 {baseDir}/scripts/search.py "your query" --top-k 5
```
### Ingest / Index
```bash
python3 {baseDir}/scripts/ingest.py /path/to/docs --format markdown
```
### Other Commands
```bash
python3 {baseDir}/scripts/summarize.py input.md
```
## Options
| Flag | Default | Description |
|------|---------|-------------|
| `--top-k <n>` | `5` | Number of results to return |
| `--format <fmt>` | `markdown` | Input format: `markdown`, `pdf`, `txt` |
| `--output <path>` | stdout | Write results to file instead of stdout |
## Output Format
```json
{
"query": "search query",
"results": [
{
"source": "docs/api-guide.md",
"score": 0.95,
"content": "Relevant text snippet..."
}
]
}
```
## References
See [API Reference](references/api-reference.md) for detailed function signatures.
See [Architecture](references/architecture.md) for system design overview.
## When to Use
- User asks questions about project documentation.
- User wants to search internal knowledge base.
- User needs to ingest new documents into the index.
- User requests document summarization.
## When NOT to Use
- General coding questions unrelated to project docs.
- Web search for external information (use `skill:duckduckgo-search` instead).
4.4 Frontmatter 规则
| 字段 | 必需 | 说明 |
|---|---|---|
name |
是 | 1-64 字符，小写字母、数字、连字符，且必须与目录名一致 |
description |
是 | skill 的用途与触发场景，最大 1024 字符 |
license |
否 | 许可证 |
compatibility |
否 | 环境要求 |
metadata |
否 | 任意元数据 |
allowed-tools |
否 | 预批准工具列表 |
disable-model-invocation |
否 | 为 true 时不让模型自动加载，只能手动 skill:name |
4.5 Skill 使用方式
skill:knowledge-base
skill:my-skill search docs/api.md
4.6 Skill 放置位置
~/.pi/agent/skills/
~/.agents/skills/
<项目根>/.pi/skills/
<项目根>/.agents/skills/
5. prompts：可复用提示模板
prompts 适合封装一段重复使用的任务说明，例如：
- 从知识库检索并回答
- 生成文档摘要
- 代码审查
- 比较两个文档或两个接口版本
prompts 不负责实现能力，而是 组织 agent 的提示输入。
5.1 prompts 模板格式（示例 1：检索问答）
---
description: 在知识库中检索问题并给出带来源引用的回答
---
请先使用 `skill:knowledge-base` 检索以下问题，并基于检索结果回答：
问题：`$ARGUMENTS`
要求：
1. 优先引用项目内部文档。
2. 每个关键结论都附带来源路径，例如 `[Source: docs/xxx.md]`。
3. 如果知识库信息不足，明确说明缺失点。
4. 如有必要，再使用 `skill:duckduckgo-search` 补充外部资料，并单独标注“外部来源”。
5. 输出结构：
- 结论
- 依据
- 风险或不确定点
- 参考来源
5.2 prompts 模板格式（示例 2：知识摘要）
---
description: 基于知识库内容生成结构化摘要
---
请先使用 `skill:knowledge-base` 检索与以下主题相关的资料，并输出结构化摘要：
主题：`$ARGUMENTS`
要求：
1. 先给出 3-5 条核心结论。
2. 再给出关键背景与上下文。
3. 每个结论尽量附带来源路径，例如 `[Source: docs/xxx.md]`。
4. 如果存在版本差异、前置条件或限制，请单独列出。
5. 如果知识库信息不足，明确说明缺失部分。
5.3 prompts 使用方式
假设文件名为：
.pi/prompts/kb-search.md
.pi/prompts/kb-summary.md
则在 Pi 中可直接输入：
/kb-search 如何部署检索服务
/kb-summary 向量索引构建流程
Pi 会自动展开模板，并把后续文本作为参数传入。
5.4 prompts 放置位置
~/.pi/agent/prompts/
<项目根>/.pi/prompts/
6. 推荐目录规划
对于一个知识库 Agent 项目，推荐目录如下：
my-project/
├── AGENTS.md
├── .pi/
│ ├── SYSTEM.md # 可选
│ ├── APPEND_SYSTEM.md # 推荐：补充系统规则
│ ├── prompts/
│ │ ├── kb-search.md
│ │ └── kb-summary.md
│ └── skills/
│ └── knowledge-base/
│ ├── SKILL.md
│ ├── scripts/
│ │ ├── search.py
│ │ ├── ingest.py
│ │ └── summarize.py
│ ├── references/
│ │ ├── api-reference.md
│ │ └── architecture.md
│ └── assets/
│ └── config.json
├── docs/
├── knowledge/
│ ├── docs/
│ └── index/
└── src/
7. 实战建议
推荐组合
最常见、最稳妥的搭配是：
AGENTS.md：定义项目规则SKILL.md：定义知识库检索能力prompts/*.md：封装常见问答场景APPEND_SYSTEM.md：补充系统级约束（如有需要）
不推荐一开始就做的事
- 一上来就重写
SYSTEM.md - 把所有长文档都塞进
AGENTS.md - 在 skill description 中写得过于模糊
一句话原则
- AGENTS.md = 常驻规则
- SKILL.md = 按需手册
- prompts = 可复用问题模板
- SYSTEM.md = 替换默认人格，谨慎使用
8. 本次生成的模板文件
当前模板文件已生成在：
templates/
├── AGENTS.md
├── SYSTEM.md
├── prompts/
│ ├── kb-search.md
│ └── kb-summary.md
└── my-skill/
├── SKILL.md
├── scripts/
└── references/
├── api-reference.md
└── architecture.md
你可以直接复制这些模板到项目的 .pi/ 或项目根目录后开始使用。
有“AI”的1024 = 2048，欢迎大家加入2048 AI社区
更多推荐
6
0- 0
已为社区贡献3条内容
所有评论(0)