提示模板与技能

Pi 的理念是「让 Pi 适应你的工作流」：可以让 Pi 帮你创建所需的提示模板、技能、扩展和主题，或安装 Pi 包。选择最小的、能满足需求的机制：重复使用同样的提示用提示模板；工作流比提示模板需要更多上下文、但不需要新的可执行集成点用技能；需要工具、命令、事件处理或界面用扩展；要分享用 Pi 包。

提示模板

提示模板把 Markdown 文件变成可复用的 / 命令，不增加可执行行为。放在个人配置 ~/.pi/agent/prompts/、项目配置 .pi/prompts/（需项目信任）、显式路径或 Pi 包。例如 ~/.pi/agent/prompts/review.md：

---
description: Review staged git changes
argument-hint: "[focus]"
---
Review the staged changes. Focus on ${1:-correctness, security, and error handling}.

文件名即命令名（/review），description 显示在补全里（省略则取第一行非空内容），argument-hint 可选（必需参数用 <尖括号>，可选参数用 [方括号]）。使用：/review、/review concurrency。替换语法：$1、$2 位置参数；$@ 或 $ARGUMENTS 全部参数；${1:-default} 带默认值；${@:N} 从位置 N 开始；${@:N:L} 取 L 个。参数遵循类 shell 引用，/review "API compatibility" 提供一个含空格的参数。在活动会话里新增或修改模板后运行 /reload。

技能

技能给 Pi 特定类型工作的专门指令和支持文件：Pi 按名称和描述宣告每个可用技能，只在任务需要时才加载完整指令。Pi 实现了 Agent Skills 规范，多数无效字段只产生警告而不阻止启动。技能是含 SKILL.md 的目录，可带 scripts/、references/、assets/：

---
name: pdf-tools
description: Extract text and tables from PDF files. Use when reading, converting, or inspecting PDFs.
---
# PDF tools
Read `references/formats.md` before converting a document. Run scripts relative to this skill directory.

description 决定模型何时考虑加载该技能：要同时说明技能做什么、何时适用，避免「Helps with PDFs」这类路由信息不足的描述。引用随附文件时用相对于技能目录的路径。加载：启动时 Pi 扫描配置的技能位置，把每个技能的名称、描述和路径加入系统提示（不加完整指令）；任务匹配时模型读取 SKILL.md 并遵循；模型可能没加载相关技能，需要强制时用 /skill:name，其后的参数会作为用户请求附加到加载的指令后（如 /skill:pdf-tools extract report.pdf）。用户技能在 <agent-dir>/skills/，项目技能在 .pi/skills/（需项目信任）。