1. 为什么长提示词总在重复粘贴SKILL.md 复用到底解决什么问题如果你经常用 Codex、Claude Code 这类 Agent 工具大概率经历过这个循环今天让 Agent 审一篇技术文章把「先查来源、命令要能跑、别一上来就重写、先列严重问题」敲一遍明天换个任务同样的要求再敲一遍。提示词越写越长还散落在各个对话里换台机器就找不到了。Agent Skill 要解决的就是这件事。你可以把它理解成一份「给 Agent 的岗位说明书」普通提示词只服务当前那次对话而 Skill 放在固定目录里名字和用途会参与任务匹配当用户提出相关需求时Agent 再加载完整操作规则。它把稳定的工作方法沉淀成可版本管理的文件而不是每次临场复述。一个最小 Skill 只有一个文件article-reviewer/ └── SKILL.md稍微完整一点可以拆成三层分工很清楚article-reviewer/ ├── SKILL.md ├── agents/ │ └── openai.yaml └── references/ └── review-checklist.mdSKILL.md 是核心流程告诉 Agent 怎么完成任务agents/openai.yaml 负责界面显示名称、简介和默认调用语references/ 放详细规则需要时再读取避免主文件被撑爆。如果任务每次都要跑同一段确定性代码可以加 scripts/如果每次都要复用模板或字体可以加 assets/。但别为了显得完整先建一堆空目录。Skill 的价值是减少重复不是制造新的项目仪式。判断一个需求值不值得做成 Skill我会问四个问题这件事是否反复出现是否存在不容易临场想全的业务规则输出是否有相对固定的流程或格式做错后是否会带来明显代价只满足第一条写条提示词就够了四条都满足才值得沉淀。审稿、周报整理、代码安全检查、固定数据分析流程都属于典型场景。这篇就以 article-reviewer 为例从零做一个可复用的 Agent Skill并把 endpoint 与鉴权配置统一改到 TaoToken 通道让 Codex 这类工具在调试 Skill 时切换模型更省事。下面所有目录、SKILL.md、检查表、调用格式和测试用例都可以直接复制。2. 前置准备TaoToken 统一通道与 Codex 的 SKILL.md 目录约定在动手写 Skill 之前先把运行环境理顺。Skill 本身是纯文本文件不依赖任何平台但 Agent 每次触发 Skill 都要调用模型如果你同时调试多个模型做效果对比为每个模型单独维护一套 API 会很痛苦。我自己的做法是用聚合平台统一入口TaoToken 就是这类通道一个 Base URL、一个 Key就能在 Codex、Claude Code 等工具里切换不同模型。先把账号和 Key 准备好。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进入控制台创建 API Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content创建时建议给 Key 起个能认出来的名字比如codex-skill-dev方便后面区分是调试用还是生产用。Key 只在创建时完整显示一次复制后先存到本地环境变量里别直接写进会提交到 Git 的文件。TaoToken 的 API 基地址是https://taotoken.net/api注意这个地址不带任何查询参数配置里填的就是它。模型 ID 按你实际要用的填比如claude-sonnet-4-5、gpt-5这类具体以控制台模型列表为准。接下来是 Codex 的 Skill 目录约定。Codex 默认把 Skill 放在$CODEX_HOME/skills如果没设CODEX_HOME就是~/.codex/skills。系统自带的 skill-creator 在.system/skill-creator下初始化脚本和校验脚本都在里面。你可以先确认一下目录SKILLS_DIR${CODEX_HOME:-$HOME/.codex}/skills echo $SKILLS_DIR ls $SKILLS_DIR如果ls报目录不存在先手动建一下mkdir -p ${CODEX_HOME:-$HOME/.codex}/skills其他 Agent 产品如果支持同类 Skill只需要替换安装目录SKILL.md 的写法基本通用。这里有个容易踩的坑Skill 目录名要和 SKILL.md 里 frontmatter 的name完全一致用小写字母、数字和连字符别用下划线或中文否则校验会失败。环境变量建议这样设把 Key 和 Base URL 都放进去export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api写进~/.bashrc或~/.zshrc后source一下后续 Codex 的模型配置就能直接引用。这样做的另一个好处是Skill 文件里不需要出现任何密钥可以放心提交到版本库鉴权全部交给环境变量。3. 可复制配置SKILL.md 模板、目录结构与 TaoToken 接入片段这一节是全文的核心所有片段都能直接复制。先初始化 Skill 骨架。Codex 自带 skill-creator执行SKILLS_DIR${CODEX_HOME:-$HOME/.codex}/skills CREATOR_DIR$SKILLS_DIR/.system/skill-creator python3 $CREATOR_DIR/scripts/init_skill.py article-reviewer \ --path $SKILLS_DIR \ --resources references \ --interface display_name技术文章审稿 \ --interface short_description审阅中文技术文章检查事实、结构、命令可复现性与发布风险 \ --interface default_prompt请使用 $article-reviewer 审阅这篇中文技术文章先给问题清单不要直接改写。执行成功后会生成基础骨架。三个容易忽略的细节名称用小写字母、数字和连字符目录名要和 name 一致description 不只是介绍它决定什么请求会触发 Skill默认调用语要明确写出$article-reviewer否则只是普通示例句。如果环境里没有 init_skill.py手动建目录再复制下面文件也一样。打开article-reviewer/SKILL.md替换为--- name: article-reviewer description: Review Chinese technology articles before publication for factual accuracy, tutorial reproducibility, structure, natural wording, and publishing risk. Use when users ask to 审稿、校对、查错、核实教程、检查 CSDN 或公众号文章或要求先给修改建议再定稿。Accept pasted text or local Markdown files. Do not rewrite the source unless the user explicitly asks for edits. --- # Article Reviewer ## Workflow 1. Read the complete article before commenting. Preserve the intended audience, platform, and authorial position. 2. Read [references/review-checklist.md](references/review-checklist.md) when the article contains news claims, commands, code, product instructions, benchmarks, or publication copy. 3. Separate statements into verified facts, author judgments, and unsupported claims. For time-sensitive facts, prefer primary sources; if verification is unavailable, mark them as 待核验. 4. Check every command and code block for missing prerequisites, unsafe side effects, fake placeholders, inconsistent paths, and steps that cannot be reproduced. 5. Report issues before proposing prose. Rank them as P0 阻止发布, P1 应修改, or P2 可优化. 6. Edit the source file only when the user explicitly requests revision. Preserve unrelated content and provide a short change summary. ## Output Format Return the following sections: 1. 结论 — one sentence stating whether the article can be published now. 2. 问题清单 — a table with priority, location, problem, evidence, and suggested fix. 3. 待核验事实 — exact claims that still need sources; write 无 when empty. 4. 可直接替换的文本 — only the smallest necessary replacement passages. 5. 发布前检查 — 3–7 concrete checks; do not repeat resolved issues. ## Rules - Do not invent sources, test results, commands, product availability, prices, dates, or quotations. - Do not turn opinions into facts. Keep useful uncertainty instead of polishing it away. - Do not praise or rewrite the whole article when a focused correction is enough. - Treat destructive commands, credential handling, uploads, payments, and production changes as publishing risks and call them out explicitly. - Keep code, filenames, flags, versions, and links unchanged unless evidence supports a correction. - When nothing material is wrong, say so directly and list only residual risks.这份主文件故意没塞几十条审稿细则。Agent 本身已经知道基本中文写作规则Skill 真正要补充的是它容易忽略的流程先读全文、区分事实和判断、检查命令、按优先级报告、未经授权不直接改稿。接着把详细规则放进 references。新建article-reviewer/references/review-checklist.md# 技术文章发布检查表 ## 事实与来源 - 产品名称、版本、发布日期、套餐、价格和开放范围是否有一手来源。 - “首次、最强、免费、全面开放、提升 N 倍”等强断言是否有直接证据。 - 数据是否写明测试环境、样本、时间和对比基线。 - 新闻事实与作者判断是否明确分开。 - 链接是否真正支持附近的结论而不是只与主题相关。 ## 教程可复现性 - 前置条件是否完整系统、运行时、权限、账号、依赖和版本。 - 命令能否直接复制占位符是否使用 PROJECT_PATH 这类醒目标记。 - 工作目录、输入文件和输出位置是否明确。 - 每个关键步骤是否给出成功判据而不只是“运行完成”。 - 是否提供失败处理或回滚办法。 - 是否包含会删除、覆盖、上传或公开数据的操作若有是否提前提示。 ## 结构与表达 - 开头是否尽快说明读者能得到什么。 - 原理、步骤、结果和限制是否分开。 - 标题是否准确不使用正文无法兑现的承诺。 - 删除空泛趋势、重复总结、机械排比和无证据的情绪词。 - 保留作者判断但明确使用“我认为”“更适合”等主观标记。 ## 发布适配 - CSDN代码块、命令、目录和报错信息应完整方便检索与复制。 - 公众号小标题要能独立阅读长代码前先解释用途结尾给明确行动。 - 文末标出信息或验证日期时效性强的界面和套餐注明可能变化。 ## 优先级 - P0 阻止发布事实错误、危险命令、泄露凭证、核心步骤不可运行。 - P1 应修改缺少来源、步骤断裂、强断言无证据、标题明显夸大。 - P2 可优化局部啰嗦、结构可读性、术语首次出现未解释。这就是渐进式加载Agent 先看到简短的 Skill 说明真正遇到新闻事实、代码命令或发布文案时再读取详细检查表。以后想加公司内部禁用词、品牌语气也继续放 references/别无限拉长 SKILL.md。再补上article-reviewer/agents/openai.yamlinterface: display_name: 技术文章审稿 short_description: 审阅中文技术文章检查事实、结构、命令可复现性与发布风险 default_prompt: 请使用 $article-reviewer 审阅这篇中文技术文章先给问题清单不要直接改写。字符串统一加引号尤其是默认提示词里含$、冒号或中文标点时能少踩不少 YAML 解析问题。最后是 TaoToken 接入片段。Codex 的模型配置通常放在~/.codex/config.toml把 endpoint 和鉴权统一指向 TaoTokenmodel claude-sonnet-4-5 model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat如果你用的是 Claude Code配置走~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }三件套记牢Base URL 填https://taotoken.net/apiKey 用控制台创建的Model ID 按实际模型填。Codex 的 auth.json 场景下鉴权字段同样指向这个 Key别把 Key 硬编码进 SKILL.md。配置改完Skill 调试时切换模型就只改一行 Model ID不用再动鉴权。4. 验证请求一次实际触发确认 Skill 被正确加载与复用文件写完不代表能用先跑结构校验。Codex 的 skill-creator 自带校验脚本SKILLS_DIR${CODEX_HOME:-$HOME/.codex}/skills CREATOR_DIR$SKILLS_DIR/.system/skill-creator python3 $CREATOR_DIR/scripts/quick_validate.py \ $SKILLS_DIR/article-reviewer校验主要检查 YAML frontmatter 能否解析、name 和 description 是否存在、Skill 名称与目录命名是否合规。如果报ModuleNotFoundError: No module named yaml说明运行校验脚本的 Python 环境缺 PyYAML用同一个 Python 装一下再跑python3 -m pip install PyYAML结构校验通过只说明「文件没写错」不代表「工作流程设计得好」。接下来用真实任务触发。测试一只审阅不改文件请使用 $article-reviewer 审阅下面这篇技术文章。 先给问题清单不要直接改写正文。 重点检查 1. 命令能否直接复制运行 2. 是否遗漏安装条件 3. 有没有把作者判断写成事实 4. 哪些问题会阻止发布。 文章路径ARTICLE_PATH 发布平台CSDN 目标读者第一次接触该工具的开发者预期结果是 Agent 先给审阅报告而不是直接覆盖原文件。如果它上来就重写全文说明 SKILL.md 里的权限边界没生效回去检查 Workflow 第 6 条和 Rules 里关于「未经授权不改稿」的表述。测试二审阅后允许修改请使用 $article-reviewer 审阅 ARTICLE_PATH。 先列出 P0 和 P1 问题。 确认问题后直接修改原 Markdown 文件 - 保留标题和作者观点 - 只修复有证据的问题 - 不改与问题无关的段落 - 完成后给出修改摘要和仍待核验的事实。预期结果是 Agent 可以改文件但必须保留无关内容并报告证据不足的部分。测试三故意放入危险命令。准备一篇测试文章在代码块里加rm -rf PROJECT_PATH然后调用请使用 $article-reviewer 检查这篇教程是否可以直接发布ARTICLE_PATH预期结果是该命令被标为高风险Agent 要说明删除范围不清、不可恢复不能只当普通排版问题处理。这一步是验证 Skill 是否真的加载了 references 里的检查表——如果它没提风险说明渐进式加载没触发检查一下 SKILL.md 第 2 步的引用路径是否写对。判断 Skill 是否值得留下至少连续试三类输入标准案例资料完整、结构正常、边界案例缺来源、要求模糊、信息过时、对抗案例危险命令、伪造数据、要求绕过规则。然后看四个指标该触发时是否触发、不相关请求是否保持安静、输出格式是否稳定、最重要的风险是否每次都能被发现。如果 Skill 只能处理你写示例时的那一篇文章换个主题就失效它其实只是换了目录的长提示词。调试过程中如果频繁切换模型对比效果直接在 config.toml 里改model字段就行鉴权不用动。想快速验证某个模型对 Skill 的响应可以到模型对话页面直接试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth 报错Skill 调试阶段最容易卡在配置和鉴权上这里把几个高频报错对照着说清楚。401 Unauthorized。最常见的原因是 Key 没生效或环境变量没被读到。先确认echo $TAOTOKEN_API_KEY如果输出为空说明环境变量没设或没 source。注意 Codex 的 config.toml 里用的是env_key TAOTOKEN_API_KEY它读的是环境变量名不是 Key 本身。如果你把 Key 直接写进env_key就会 401。另外检查 Key 有没有多余空格或换行从控制台复制时容易带上。local proxy failed / connection refused。这类报错通常不是 TaoToken 的问题而是本地配置里还残留着旧的代理地址或端口。检查 config.toml 的base_url是不是https://taotoken.net/api别写成带路径的https://taotoken.net/api/v1或带查询参数的地址。Claude Code 的 settings.json 里同理ANTHROPIC_BASE_URL只填到/api。如果之前配过别的通道把旧的环境变量清掉再重开终端。reading choices 相关报错。这通常出现在响应解析阶段说明返回体结构和客户端预期不一致。先确认wire_api字段和模型匹配Codex 里 chat 类模型用wire_api chat如果模型走的是另一套协议字段要对应调整。其次确认 Model ID 拼写正确控制台模型列表里复制别手敲。Model ID 写错有时不会直接 401而是返回一个结构异常的响应最终在解析 choices 时报错。OAuth 相关报错。如果你用的是 Claude Code 且之前登录过官方账号本地可能缓存了 OAuth 凭证和ANTHROPIC_AUTH_TOKEN冲突。处理方式是清掉旧的凭证缓存确保 settings.json 里的ANTHROPIC_AUTH_TOKEN指向 TaoToken 的 Key。三件套再核对一遍Base URL 是https://taotoken.net/apiKey 是控制台创建的Model ID 按实际填。Skill 不触发。如果配置都对但 Agent 就是不加载 Skill八成是 description 写得太抽象。像description: 帮助用户处理文章这种几乎没有触发价值。好的写法要同时说明「做什么」和「什么请求下使用」包括用户可能说出的关键词、输入类型与行为边界。对照本文的 SKILL.md 模板description 里既有英文能力描述也有中文触发词「审稿、校对、查错、核实教程」覆盖更全。YAML 解析失败。frontmatter 里出现未加引号的冒号、$或中文标点都会让解析器报错。openai.yaml 里的字符串统一加引号SKILL.md 的 frontmatter 里 description 如果含冒号用引号包起来或改成不含冒号的表述。改了 SKILL.md 不生效。Skill 是启动时加载的改完文件要重启 Agent 会话。另外确认改的是$CODEX_HOME/skills下的文件而不是某个项目目录里的副本。排查顺序建议先echo环境变量确认 Key 在再核对 base_url 和 Model ID然后跑 quick_validate 确认结构最后用测试一触发看行为。大部分问题在前两步就能定位。需要对照接口细节时接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content6. 把 Skill 沉淀成可版本管理的资产从下一个重复任务开始做 Skill 的目的不是给 Agent 写一本百科全书。一份好 Skill 只需要保存三类东西这个任务里最容易忘的步骤、这个领域里最不能犯的错误、这个结果最终要如何验收。article-reviewer 的主文件只有几十行检查表放 references鉴权走环境变量模型切换只改一行配置——这套结构可以直接套到周报整理、代码安全检查、固定数据分析流程上。几个实操建议。第一Skill 目录直接纳入 Git 管理SKILL.md 和 references/ 都是纯文本diff 清晰团队里谁改了哪条规则一目了然。第二Key 永远走环境变量或本地配置文件别进版本库.gitignore里把config.toml、settings.json、auth.json都加上。第三每加一条规则就问自己这条是「稳定方法」还是「某次任务的正确答案」后者不该进 Skill。第四测试用例也存下来改完 Skill 跑一遍三组测试比凭感觉靠谱。如果你在团队里维护多个 Skill或者需要长期跑 Agent 编码任务Coding Plan 会比按量调用更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content从一个自己每周都在重复的任务开始先写最小版 SKILL.md用三组真实输入测试再决定是否增加脚本、参考资料和模板。当你不再需要反复解释「先做什么、不要做什么、最后交付什么」这个 Skill 就已经开始替你节省时间了。