Pi Mono Agent 的 SKILL.md 走的是按需加载模型通道这一层可以单独换走 TaoToken。先在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号并创建 Key然后把 Base URL 指向 https://taotoken.net/apiAgent 侧的 skill 机制完全不用改。这篇文章只解决一件事让 Pi Mono Agent 的提示语与技能在正确的加载边界上工作同时把模型请求接到 TaoToken 通道上。很多人第一次配 Pi 的时候会把注意力全放在 SKILL.md 怎么写上结果写完发现启动上下文还是很大、skill 也没有被触发回头一看才发现两处问题一是长文档仍然躺在 AGENTS.md 里二是模型通道根本没配通Agent 连一次完整请求都发不出去。本文按配置顺序拆开讲先理清文件职责再给可复制的通道配置最后用一个 skill:knowledge-base 的触发过程验证按需加载是否真的成立。一、问题不在提示语在 AGENTS.md 和 SKILL.md 的加载边界Pi Mono Agent 里常被提到的几类文件职责其实差别很大。SYSTEM.md 是替换默认系统提示词一般不写APPEND_SYSTEM.md 是在默认系统提示词后面追加规则适合补系统级约束AGENTS.md 是项目级行为规范启动时就会被拼接进上下文而且会从当前工作目录一路向上遍历到 git 根目录命中几个就拼几个skills/*/SKILL.md 是技能说明与操作手册启动时只把 name 和 description 放进上下文真正匹配到任务之后才读取完整内容prompts/*.md 是可复用的任务模板只在被显式展开时使用。真正的痛点出在 AGENTS.md。它是最推荐写、也最容易被写爆的文件。安装步骤、依赖清单、大段 API 参数说明、低频脚本调用方式一旦塞进 AGENTS.md就变成了每一轮对话都要背的常驻成本。启动上下文被这些内容撑大之后模型在真正需要推理的地方反而变迟钝你还会误以为是模型能力问题。正确的划分只有一句话AGENTS.md 只放必须时刻遵守的规则SKILL.md 放任务触发后才需要的详细操作说明。判断标准也很直接问自己一句「这条内容如果这次对话没用到会不会导致 Agent 行为出错」。会就留在 AGENTS.md不会就搬进 SKILL.md。角色边界、回答风格、引用格式、禁止执行的命令、提交规范这些属于常驻检索流程、索引重建命令、脚本参数表、输出 JSON 结构这些属于按需。这里还有一个容易被忽略的点SKILL.md 的 description 不是摘要而是触发开关。Pi 之所以能做到渐进式加载靠的就是启动时只用 name 和 description 做匹配决策。description 写得含糊模型就不知道该不该加载完整内容description 写得过细又等于把一部分常驻成本提前搬回了上下文。一个可用的 description 要同时回答「这个技能做什么」和「什么情况下用它」并且明确写出不该用的场景。把边界划清之后原文提到的四类文件就形成了一条链路APPEND_SYSTEM.md 补系统级约束AGENTS.md 定项目规则prompts 封装常见问法SKILL.md 承载按需手册。链路本身没问题缺的是让这条链路跑起来的模型通道。二、模型通道前置TaoToken 建 Key 与 Base URL 的确定原文在第 3、4 节把 AGENTS.md 和 SKILL.md 的放置位置、frontmatter 字段、目录结构、触发方式都讲到了但没有写 Agent 调用模型时从哪里取 Key。这一步不补上SKILL.md 写得再标准也只是磁盘上的几段文字不会被执行。接入过程分两步。第一步在 TaoToken 注册并创建 Key入口是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建完成后会得到一串 Key本文统一写作 YOUR_API_KEY不要把它提交进仓库也不要写进 AGENTS.md 这类会被拼接进上下文的文件里泄露风险很高。第二步确定 Base URL固定使用 https://taotoken.net/api 注意这个地址后面不加 /v1也不要在末尾补斜杠OpenAI 兼容客户端通常在拼接请求路径时会自己补。Key 的存放位置建议按作用域选。只在本机用放进 shell 环境变量或 ~/.pi/ 下的用户级配置团队共享项目放在项目根目录的 .env 或本地配置里并确保它已经在 .gitignore 中。Pi Mono Agent 的配置来源一般包括用户级目录和项目级目录两者同时存在时以更近的一层为准所以调试阶段建议先用用户级把通道打通确认无误后再落到项目级。需要强调的是TaoToken 在这里的角色只是模型通道。它不参与 SKILL.md 的加载决策也不改变 AGENTS.md 的拼接逻辑。你不需要为了接入它去重写任何技能文件需要改的只有「请求发往哪里、用哪把 Key、用哪个模型 ID」这三件事。三、可复制配置Pi Mono Agent 接 TaoToken 的完整写法先把目录放对。按项目级组织最小可用结构如下my-project/ ├── AGENTS.md ├── .pi/ │ ├── 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 ├── docs/ └── knowledge/通道配置用环境变量注入最省事也最不容易和项目配置冲突。如果 Pi 走的是 OpenAI 兼容协议export OPENAI_API_KEYYOUR_API_KEY export OPENAI_BASE_URLhttps://taotoken.net/api如果走的是另一套协议族就换成对应的变量名值保持一致export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_BASE_URLhttps://taotoken.net/api如果更习惯写配置文件可以在用户级配置里声明一个 provider示意结构如下具体字段名以本机 Pi 版本为准{ model: YOUR_MODEL_ID, provider: { name: taotoken, type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: YOUR_API_KEY } }模型 ID 不要凭记忆填去控制台里看当前可用的列表填错会直接返回模型不存在的错误而不是 Key 错误很容易误判方向。再看 AGENTS.md 应该长什么样。它的职责是规则不是手册。下面这段只保留常驻部分# Project Rules ## Role 你是本项目的知识库与工程协作助手优先基于项目文档回答不编造。 ## Commands - 代码改动后运行 npm run check完整输出不要截断。 - 未经明确指示不执行 npm run dev、npm run build。 - 未经明确指示不提交任何代码。 ## Knowledge Base - 回答知识库问题时先使用 skill:knowledge-base 检索。 - 每个关键结论附来源格式为 [Source: file-path]。 - 知识库没有覆盖时再考虑外部检索并单独标注来源类型。 ## Response Style 简洁、结构化、直接给结论技术描述避免口语化。SKILL.md 则把重活接过去。frontmatter 两个字段必须写全name 要和目录名一致description 控制在 1024 字符以内写清用途和触发条件--- name: knowledge-base description: 本项目知识库的检索与文档摄取手册。当用户询问项目文档、接口说明、部署流程或要求把新文档加入索引时使用。泛化的编程提问、与项目文档无关的闲聊不要触发。 --- # knowledge-base ## 首次使用 bash cd {baseDir} pip install -r requirements.txt检索python3 {baseDir}/scripts/search.py 查询词 --top-k 5重建索引python3 {baseDir}/scripts/ingest.py /path/to/docs --format markdown输出格式{ results: [ {source: docs/api-guide.md, score: 0.0, content: ...} ] }适用与不适用适用项目文档问答、知识库检索、文档入库。 不适用通用编程问题、与项目文档无关的外部信息查询。这样配置之后AGENTS.md 的体量被压到很小启动上下文主要留给真正的规则详细命令和参数表只在 skill 被触发时才进入上下文。 ## 四、验证 skill:knowledge-base 是否按需展开且请求从 TaoToken 走通 配置写完不要只看配置文件要跑一次真实触发。验证分两个层面加载行为是否正确请求通道是否走通。 第一步验证通道。用一个不需要 skill 的问题先确认模型能正常响应比如问一句项目结构相关的问题。如果通道没通这一步就会暴露 401 或连接失败不用等到 skill 环节再排查。 第二步验证按需加载。先问一个不相关的问题例如让它解释一段与知识库无关的代码。此时观察日志或调试输出不应该出现读取 .pi/skills/knowledge-base/SKILL.md 完整内容的记录说明启动阶段只加载了 name 和 description。 第三步触发技能。输入类似「根据知识库说明这个接口的分页参数」这样的问题Agent 应当先基于 description 判断该技能匹配再去读取完整 SKILL.md然后按里面的命令执行检索脚本。观察点有三个SKILL.md 是否在这次请求中才被读取检索脚本是否真的被调用返回结果里是否带有 [Source: ...] 引用。三点都成立说明按需加载链路正常。 第四步确认请求来源。在 TaoToken 控制台的用量或请求记录里应该能看到刚才这一次调用。如果本地模型响应正常但控制台没有记录说明请求走了别的通道多半是环境变量没生效或者项目级配置覆盖了用户级配置。 为了减少干扰验证阶段可以把 APPEND_SYSTEM.md 暂时留空只保留 AGENTS.md 和这一个 skill。变量越少定位越快。 ## 五、本篇常见错排查 第一个高频错误是把 Base URL 写成 https://taotoken.net/api/v1。地址本身只用 https://taotoken.net/api 多写一段路径会导致请求拼出重复的版本段表现为 404 而不是 401很容易被误判成 Key 问题。 第二个是 Key 放错字段。有的客户端读 apiKey有的读 authToken字段名用错会一直报鉴权失败。排查方式是先确认变量名与协议族匹配再看错误信息里是「缺少凭证」还是「凭证无效」前者是字段问题后者才是 Key 本身的问题。 第三个是模型 ID 写错。表现是鉴权通过、请求也发出去了但返回模型不存在。这类错误不要怀疑 Key直接去控制台核对可用模型列表。 第四个是 SKILL.md 不触发。常见原因有四个frontmatter 里的 name 与目录名不一致description 写得太笼统模型无法判断匹配disable-model-invocation 被设成了 true只能手动调用YAML 头部的缩进或折叠符写错导致解析直接失败。排查顺序就按这四条走先看解析再看命名最后看描述质量。 第五个是 AGENTS.md 体积没有降下来。如果已经把长手册搬进 SKILL.md但启动上下文依然很大通常是 AGENTS.md 里还留着大段示例代码或参数表或者 skill 的 description 写成了半页说明。常驻内容和按需内容的边界要再检查一遍。 第六个是把 SKILL.md 写成了 TaoToken 的说明文档。这是方向性错误。通道配置属于环境层写在环境变量或配置文件里SKILL.md 描述的是任务如何执行。两者混在一起既会污染技能描述也会让 description 失去触发判断的价值。 第七个是本地配置与项目配置冲突。用户级配置写了一套 Base URL项目级又写了一套旧的最终生效的是更近的一层。排查时先用一个干净的目录跑最小配置确认通道本身可用再逐层加回项目配置。 ## 六、下一步先建 Key再补 .pi/skills 如果你的 Pi Mono Agent 已经按原文把 SYSTEM.md、APPEND_SYSTEM.md、AGENTS.md、skills 和 prompts 分好了那剩下要做的只有两步。 先在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 创建 Key把 Base URL 填成 https://taotoken.net/api 并把 Key 放进环境变量或本地配置不要写进 AGENTS.md。返回结果和请求错误码的细节对照接入文档更省时间https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。 然后回到项目的 .pi/skills 目录按本文的 frontmatter 规则和目录结构补 SKILL.md。写完之后用第四节的四步验证跑一遍不相关问题不读完整 SKILL.md相关问题才展开脚本被真实调用控制台能查到这次请求。 整个过程里SKILL.md 的按需加载逻辑不需要为 TaoToken 做任何改动它只负责在正确的时间被读取通道层的事交给环境变量和 Base URL。两者各归其位启动上下文才能压得住技能触发也才能稳定。