1. 从一次「Agent 又忘了规矩」说起如果你已经在用 Agent 写代码、整理文档、跑数据流大概率遇到过这种场面同一个项目昨天它按团队规范输出了带验收标准的 PRD今天换个会话它又开始自由发挥章节缺一半、边界不写、异常流程直接跳过。你不得不把上周那段三百字的提示词再贴一遍贴完还得补一句「记得按我们公司的模板来」。问题不在于模型不够聪明而在于做事方法没有被固化下来。Prompt 是「这一次要做什么」Tool 是「它能动手做什么」而 Skill 回答的是「这类任务通常应该怎么做」。三者分工不同缺了 Skill 这一层Agent 每次都在重新猜你的规矩。这篇就围绕SKILL.md这个配置骨架展开它是什么、目录怎么摆、front matter 怎么写、Agent 怎么发现并渐进加载它最后给一份可复制的骨架配一套统一的 Key/API 通道配置再跑一次本地调用验证让你把团队方法真正交到 Agent 手里。适合已经理解 Agent 和 MCP、想把模板与检查规则沉淀下来的读者。2. Skill 是什么和 Prompt、Tool 的边界先把两句话记住。Skill 是一组可复用的任务说明和配套文件用来教 Agent 遇到某类任务时应该怎样做。Tool 让 Agent 有能力执行动作Skill 让 Agent 更有章法地使用能力。举个具体例子。一个 Agent 已经能读写 Markdown 文件这是 Tool 能力但它未必知道你们公司的 PRD 必须包含哪些章节、如何确认范围边界、验收标准要写成什么样。prd-assistant这个 Skill 就能把这套方法交给它。三者的分工可以这样对照概念回答的问题例子Prompt这一次要模型做什么「评审这份 PRD」Skill这类任务通常应该怎样做PRD 评审步骤、标准、模板ToolAgent 能执行什么动作读文件、查接口、写文档MCPTool/Resource 如何标准化连接连接知识库或采购系统Agent谁在目标驱动下选择并执行步骤产品 Agent、数据流 Agent关键点Skill 不替代 Tool。你写一万字「如何查询采购单」但没有查询工具Agent 依然拿不到真实数据。反过来只有工具没有 SkillAgent 会查但不会按你的规矩查。Skill 的价值不在于文件夹多标准而在于把隐性经验变成可执行、可复用、可测试的工作方法。团队经验在 Skill 里的承载方式是分层的什么时候用写在description按什么步骤做写在SKILL.md正文详细业务规则放references/可重复处理交给scripts/模板素材放assets/。3. TaoToken 前置统一 Key 与 API 通道在写 Skill 之前先把 Agent 的模型通道理顺。很多人的痛点是Skill 写好了但每个 Agent 客户端各配一套 Key、各写一份 base_url换环境就崩。用 TaoToken 做统一入口可以只维护一份 Key 和一份 API 地址。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个地址不加 UTM 参数直接填进配置即可。你需要先拿到 Key去控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 然后在 API Keys 页面生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。生成后复制那串sk-开头的字符串后面配置里会用到。注意Key 只放在环境变量或本地配置文件里绝对不要写进SKILL.md或references/。Skill 是会被 Agent 读取甚至分享的文件包凭据进去就等于泄露。如果你打算长期跑编码类 Agent 或做 Agent 编排可以顺带看下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合高频、长会话的场景。接入细节和字段说明统一看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。4. 可复制配置SKILL.md 骨架 settings.json 片段4.1 标准目录一个 Skill 至少是一个包含SKILL.md的目录。目录名要和 front matter 里的name一致。prd-assistant/ ├── SKILL.md ├── references/ │ ├── prd-standard.md │ └── acceptance-rules.md ├── scripts/ │ └── validate_prd.js └── assets/ └── prd-template.md各部分职责SKILL.md必需承载元数据、触发说明和核心流程references/可选是需要时再读取的详细知识scripts/可选放确定性处理assets/可选放模板、Schema 等交付素材。4.2 最小 SKILL.mdSKILL.md由 YAML front matter 和 Markdown 正文两部分组成。下面这份可以直接复制改--- name: prd-assistant description: 梳理业务需求并输出结构化 PRD。用于需求访谈、业务规则整理、范围界定、异常机制设计和验收标准编写。 --- # PRD Assistant ## Workflow 1. 确认用户、问题、业务价值和成功指标。 2. 梳理主流程、分支流程、异常流程和权限边界。 3. 区分本期范围、后续范围和明确不做的内容。 4. 输出 PRD并逐项检查验收标准是否可测试。 ## Required Output - 背景与目标 - 用户与场景 - 范围与边界 - 业务流程与规则 - 异常机制 - 验收标准 - 风险、依赖和下一步front matter 只有两个必填字段。name要求 1 到 64 个字符只用小写字母、数字和连字符不以连字符开头或结尾不含连续两个连字符且与父目录名一致。description不只是展示文案它通常是 Agent 判断是否加载这个 Skill 的主要线索所以要同时写清「能做什么」和「何时触发」。对比一下差与好# 差的写法 description: 帮助写文档。 # 更好的写法 description: 评审 PRD 的场景完整性、范围边界、业务规则、异常机制、数据接口和验收标准。用于用户提出 PRD 评审、需求挑刺或研发可落地性检查时。可选字段有license、compatibility、metadata、allowed-tools其中allowed-tools属于实验字段各 Agent 支持程度不同。不要因为可选就全填元数据越多维护成本越高。4.3 settings.json 片段把模型通道统一到 TaoToken配置文件里这样写。不同客户端字段名略有差异核心是base_url和api_key两项{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key粘贴在这里, ANTHROPIC_MODEL: claude-sonnet-4-5 }, skills: { enabled: true, paths: [./skills] } }如果你用的是走 OpenAI 兼容协议的客户端把字段换成对应的OPENAI_BASE_URL和OPENAI_API_KEY地址同样填https://taotoken.net/api。Key 建议通过环境变量注入而不是硬编码在文件里export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的Key4.4 正文怎么写才可执行Skill 正文要像给一名可靠同事的工作规程不是宣传文章。推荐结构是目标与适用范围 → 输入要求 → 工作步骤 → 决策规则 → 输出标准 → 异常与边界 → 验证方法 → 需要时读取的参考文件。三个要点。第一用可观察动作代替模糊表述。「深入理解需求并输出高质量文档」没法执行「先列出目标用户、触发条件、主流程、异常流程、数据变化和权限角色缺少任一项时在起草前补齐或标记为待确认」就能执行。第二写出停止条件。Agent 需要知道何时完成而不是无限补充。比如所有必填章节已完成每条需求至少有一个可测试验收标准所有待确认项都有责任人或决策点无真实密钥和个人隐私。第三把选择规则写出来。例如「若任务只涉及只读查询优先设计只读 Tool若操作会修改业务状态必须补充权限、幂等、审计和人工确认若用户目标仍有歧义不直接虚构规则先列出关键决策项」。这比「根据实际情况处理」有用得多。5. 验证请求跑一次本地调用配置写完别急着上生产先做一次最小验证确认通道通、Skill 能被识别。第一步确认环境变量生效echo $ANTHROPIC_BASE_URL echo ${ANTHROPIC_AUTH_TOKEN:0:6}第二条只打印 Key 前 6 位避免整串泄露到终端历史。第二步用 curl 打一次模型对话接口确认 Key 和地址可用curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_AUTH_TOKEN \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 128, messages: [{role: user, content: 只回复两个字通了}] }返回里能看到content字段带出「通了」说明 Key 和 API 通道没问题。想更直观地验证模型可以直接用模型对话页面https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。第三步验证 Skill 触发。在 Agent 里输入一句会命中description的话比如「帮我评审这份 PRD 的异常机制」。观察它是否读取了SKILL.md并按Required Output的章节输出。如果它没触发八成是description写得太宽或太窄。第四步验证脚本。scripts/validate_prd.js这类检查脚本要能独立跑node scripts/validate_prd.js ./output/prd.md预期输出是逐项列出「背景与目标通过」「验收标准缺失」这类结果。脚本报错信息要清晰说明依赖且默认不做破坏性操作。6. 本篇常见错排查Skill 不触发。先看description是否同时写了「做什么」和「何时用」。只写「帮助写文档」会跟一堆 Skill 冲突只写触发词不写能力Agent 又不知道它能干什么。改完重启会话再试。触发了但输出不对。多半是正文只有原则没有步骤。检查Workflow是不是可观察动作有没有停止条件。把「专业、严谨、全面」这类词换成具体顺序和分支。上下文被撑爆。常见于把几万字知识全塞进SKILL.md。正确做法是主文件保持精炼详细内容拆到references/执行中按需读取。这也是渐进加载的意义目录层先看名称和描述成本很低触发后读完整SKILL.md需要时再读参考资料和脚本。多个 Skill 互相覆盖。两个 Skill 都规定不同输出格式时Agent 难以选择。要定义优先级、组合方式和所有权边界别让「处理所有产品工作」这种宽描述存在。Key 报 401 或 403。先确认ANTHROPIC_AUTH_TOKEN是不是完整的sk-串有没有多余空格或换行再确认base_url填的是https://taotoken.net/api而不是带路径的完整接口地址。改完用第 5 节的 curl 复测一次。脚本执行失败。检查 Node 版本和依赖是否声明清楚路径是相对SKILL.md还是相对工作目录。脚本要避免默认执行删除、上传这类高影响动作。安全审查没过。安装第三方 Skill 前检查SKILL.md是否要求读取无关文件、脚本是否上传数据或执行删除、是否请求不必要的网络权限、参考文件里有没有提示词注入。凭据一律通过环境注入不进 Skill 文件。7. 把方法交出去把通道收回来Skill 的本质是 Agent 的可复用工作方法包最少一个SKILL.md按需带参考知识、脚本和模板。一份好 Skill 要做到容易被准确发现、步骤可执行、边界清楚、结果可验证、知识可维护、安全可审查。落地时我的习惯是先用最小骨架跑通触发再逐步往references/和scripts/里加东西每加一条规则就补一个测试样例。测试至少覆盖五类——应触发、不应触发、信息缺失、规则冲突、敏感数据输入。优化时一次只改少量规则保留前后对比别靠「感觉更好了」。通道这层则尽量收拢到一处。统一用 TaoToken 的 Key 和 API 地址Agent 客户端换环境时只改环境变量Skill 文件本身不动。需要长期跑编码或 Agent 编排的走 Coding Plan 更省心接入字段和排障细节以文档为准。把方法交给 Agent把通道收回来自己管这套组合跑起来会稳很多。