1. 从 891 行缩到 150 行一个迭代 20 次的 Skill 到底长什么样先说我拆的这个 Skill 是干什么的把旧平台几百个文档页面导出再上传到新平台。单次迁移可能上千页、几百个空间、跑 4 个小时中途会断要兼容四种 AI 助手、两类用户、内网和公网两种网络密码不能出现在任何地方。听起来是个脚本活但它迭代了 20 次攒了 214 个测试用例SKILL.md 从 891 行缩到 150 行。如果你正在写 Skill或者准备把手上那坨「一段很长的 prompt」整理成能长期维护的东西这篇拆解就是给你看的。我会先给出可复制的目录骨架再逐层拆 SKILL.md、references、CHANGELOG 和 CI 校验最后用 TaoToken 统一 Key/API 通道跑通一次 Skill 加载验证。全程可跟做不需要你先理解什么高深概念。先说结论这个 Skill 根本不是「一段好 prompt」。它更像一套可维护的工程资产——有契约层、有按需加载层、有版本治理层、有 CI 守门层。prompt 是写给人看的一句话Skill 是写给 Agent 加载的一个文件系统。我先把它的目录骨架贴出来你可以直接复制成自己的起点confluence-to-cloud-docs/ ├── SKILL.md # 核心契约150 行每次对话必加载 ├── references/ # 按需加载的细节文档 │ ├── cli-flags.md # 命令行参数完整列表 │ ├── config-schema.md # 配置字段表与自动补全规则 │ ├── agent-output-contract.md # Agent 输出判定规则 │ ├── secure-config.md # 凭证安全规范 │ ├── confluence-export.md # 导出阶段说明 │ ├── cloud-docs-api.md # OpenAPI 签名与端点 │ └── legacy-paths.md # 已废弃的旧上传通道 ├── scripts/ # 20 Python 脚本 ├── tests/ # 214 个 pytest 用例 ├── CHANGELOG.md # 结构化版本记录 ├── STABILITY.md # 稳定版本基线 ├── VERSION # 当前版本号 └── README.md # 给人看的使用说明这个骨架里最容易被忽略的是references/和CHANGELOG.md。大多数人写 Skill 只写一个 SKILL.md把所有细节塞进去结果就是 891 行。891 行不是内容问题是 context 预算问题——Agent 每次对话都要全吞真正用得上的不到五分之一。references/的分层逻辑不是「按主题切」是按 Agent 什么时候需要读来切。cli-flags.md 是拼命令时读config-schema.md 是填参数时读agent-output-contract.md 是解读结果时读secure-config.md 是涉及凭证时读。90% 的对话只需要 150 行的 SKILL.md剩下 10% 的场景才按需拉取对应文件。CHANGELOG.md也不是流水账。它接近 300 行每个版本有五个固定段落Added、Changed、Fixed、Notes、Not in MVP。其中 Not in MVP 是最被低估的治理工具——它明确告诉所有人「这个缺位是选择不是遗漏」。v7.3.2 写了「Not in MVP: 完整断点续导 exportPhase 2 TODO」到 v7.4 就实现了。不做和暂时不做是两回事写清楚才能让下个版本有输入。所以这一节的核心就一句话Skill 的第一天就要建references/目录。问自己一个问题——这个内容 Agent 每次对话都需要还是偶尔某一步才需要前者放 SKILL.md后者放 references。这个判断做对了后面所有工程化才有地基。2. TaoToken 前置统一 Key/API 通道让 Skill 加载验证可复现拆完结构得先解决一个现实问题你要跑通一次 Skill 加载验证总得有个稳定的模型通道。我试过在多个平台之间来回切 Key每次换环境都要改配置验证结果根本不可复现。后来我把通道统一到 TaoToken 上Base URL、Key、Model ID 三件套固定下来Skill 的加载验证才有意义。TaoToken 在这里的角色是「统一 Key/API 通道」。官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置时直接用这个。你需要准备三样东西我把它叫「三件套」配置项值说明Base URLhttps://taotoken.net/api所有请求的根地址API Key在控制台生成形如sk-...只显示一次Model ID按需选择如claude-sonnet-4-5等获取 Key 的路径是控制台里的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentskill_engineeringutm_campaignrewrite 。生成后立刻复制页面刷新就看不到了。如果你用的是 Claude Code 这类编码工具接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentskill_engineeringutm_campaignrewrite 。文档里有针对不同工具的配置示例照着填三件套就行。这里要强调一点Skill 加载验证和普通对话不一样。普通对话你随便找个通道都能跑但 Skill 加载验证要求「同样的输入同样的加载路径同样的输出结构」。如果通道不稳定你根本分不清是 Skill 结构有问题还是通道抽风。统一通道之后变量就只剩 Skill 本身。我踩过的坑是一开始用不同平台的 Key 分别验证结果 A 平台能加载 referencesB 平台加载失败排查了半天发现是 B 平台的模型不支持长上下文。换成 TaoToken 统一通道后这个问题直接消失。所以前置这一步别省。三件套固定下来后面的配置和验证才有基准。你可以先把 Key 生成好放在一个临时环境变量里别写进代码export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api环境变量设好下一节直接进配置。3. 可复制配置SKILL.md 契约 settings.json CI 校验片段这一节给你三份可直接复制的配置SKILL.md 的 frontmatter 契约、编码工具的 settings 片段、以及 CI 校验脚本。三份都跟前面的目录骨架路径一致复制过去就能用。先看 SKILL.md 的 frontmatter。这是整个 Skill 的发现机制决定 Agent 什么时候加载你--- name: confluence-to-cloud-docs description: Migrate Confluence to cloud docs. Trigger: 导出文档、迁移空间、同步知识库、试运行、分批迁移 Hosts: WorkBuddy (--answers), Cursor/Codex (wizard or answers) Not: 其他内容平台、在线表格文档 ---description 里三个子字段各司其职。Trigger 是用户说哪些话时激活写了长尾关键词确保不同表述都能命中。Hosts 声明在哪些平台怎么启动不同平台入口路径不同。Not 明确声明不支持的场景一次排除比十次匹配省 context。然后是编码工具的 settings 片段。以 Claude Code 为例配置文件路径是~/.claude/settings.json内容如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }如果你用的是 Codex配置文件在~/.codex/auth.json结构类似{ base_url: https://taotoken.net/api, api_key: sk-你的key, model: claude-sonnet-4-5 }注意三件套必须写全Base URL、Key、Model ID。少任何一个都会报 401 或者模型找不到。我见过有人只填了 Base URL 和 Key忘了 Model ID结果请求发出去返回model not found排查半天。最后是 CI 校验脚本。这个脚本回答一个核心问题如何防止 SKILL.md 又从 150 行膨胀回 891 行答案是靠 CI 守门不靠人的纪律。# tests/test_skill_slim.py import os import re SKILL_PATH SKILL.md REFERENCES_DIR references MAX_LINES 200 def test_skill_md_line_limit(): with open(SKILL_PATH, encodingutf-8) as f: lines f.readlines() assert len(lines) MAX_LINES, fSKILL.md 超过 {MAX_LINES} 行当前 {len(lines)} 行 def test_references_complete(): required [ cli-flags.md, config-schema.md, agent-output-contract.md, secure-config.md, confluence-export.md, cloud-docs-api.md, legacy-paths.md, ] for name in required: path os.path.join(REFERENCES_DIR, name) assert os.path.exists(path), f缺少 references 文件: {name} def test_description_has_trigger(): with open(SKILL_PATH, encodingutf-8) as f: content f.read() assert Trigger: in content, description 缺少 Trigger 关键词 assert Not: in content, description 缺少 Not 排除声明三行断言比任何规范都有效。SKILL.md 行数红线、references 完整性、触发词存在性——新增内容之前必须决定放正文还是放 references否则 CI 红。把这三份配置放好你的 Skill 就有了契约层、通道层和守门层。下一节跑验证。4. 验证请求跑通一次 Skill 加载看到成功结果配置放好了现在跑一次真实的 Skill 加载验证。目标是确认三件事通道通、SKILL.md 能被正确解析、references 能按需加载。先验证通道。用 curl 发一个最小请求curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }成功的话你会看到类似这样的返回{ id: msg_xxx, type: message, role: assistant, content: [{type: text, text: OK}], stop_reason: end_turn }看到content里有文本、stop_reason是end_turn说明通道通了。如果返回 401说明 Key 有问题如果返回model not found说明 Model ID 写错了。通道通了之后验证 Skill 加载。把 SKILL.md 和 references 目录放到工作目录下然后让 Agent 加载cd /path/to/your-skill # 确认目录结构 ls -la # 应该看到 SKILL.md 和 references/ 目录然后发一个触发请求模拟用户说「帮我试运行一次迁移」curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 512, system: 你是一个 Skill 加载器。读取当前目录的 SKILL.md判断是否应该激活。, messages: [{role: user, content: 帮我试运行一次迁移}] }成功的结果是Agent 回复里提到「试运行」「trial-run」「4 个字段」这些关键词说明它读到了 SKILL.md 里的 Quick Start 和黄金命令。如果它回复「我不知道你在说什么」说明 SKILL.md 没被正确加载检查文件路径和 frontmatter 格式。再验证 references 按需加载。发一个涉及凭证的请求curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 512, system: 读取 SKILL.md如果涉及凭证操作按索引加载 references/secure-config.md。, messages: [{role: user, content: 密码应该填在哪里}] }成功的结果是Agent 回复里提到「掩码表单」「密码不出现在聊天」「临时 JSON 文件 0600」这些来自 secure-config.md 的内容。这说明 references 按需加载生效了。三个验证都过了你的 Skill 加载链路就通了。整个过程不超过 5 分钟这就是 trial-run 的价值——最小成本的可验证闭环。5. 常见报错排查401、local proxy failed、reading choices、OAuth验证过程中最容易撞上四类报错。我按真实报错信息逐个拆每个都给出定位方法和修复动作。401 Unauthorized。返回体通常是{error: {type: authentication_error, message: invalid x-api-key}}。原因有三个Key 没填、Key 填错、Key 过期。定位方法是打印环境变量确认echo $TAOTOKEN_API_KEY # 应该输出 sk- 开头的字符串如果输出为空说明环境变量没设。如果输出有值但还是 401去控制台重新生成一个 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentskill_engineeringutm_campaignrewrite 。注意 Key 只在生成时显示一次页面刷新就看不到了。local proxy failed。这个报错通常出现在编码工具里提示本地代理连接失败。原因是工具配置的 Base URL 指向了本地地址但本地没有代理服务在跑。修复方法是把 Base URL 改成https://taotoken.net/api不要用localhost或127.0.0.1。检查 settings.json 里的ANTHROPIC_BASE_URL字段确认是完整地址。reading choices。这个报错出现在解析模型返回时提示读取choices字段失败。原因是请求发到了 OpenAI 兼容格式的端点但返回的是 Anthropic 格式字段名对不上。Anthropic 格式的返回是content数组OpenAI 格式才是choices数组。修复方法是确认你的请求路径和返回格式匹配。如果用/v1/messages就按content解析如果用/v1/chat/completions才按choices解析。OAuth 相关报错。提示OAuth token expired或invalid_grant。原因是工具走了 OAuth 流程而不是 API Key 流程。修复方法是强制使用 API Key 模式在配置里显式指定 Key不要依赖 OAuth 自动获取。以 Claude Code 为例确认 settings.json 里有ANTHROPIC_API_KEY字段并且没有启用 OAuth 相关的开关。排查顺序建议这样先确认三件套写全Base URL Key Model ID再确认请求路径和返回格式匹配最后确认没有混用 OAuth 和 API Key。90% 的报错都出在前两步。如果排查完还是不通去接入文档对照配置https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentskill_engineeringutm_campaignrewrite 。文档里有针对不同工具的完整配置示例。6. 把 Skill 当工程资产从 CHANGELOG 到 CI 的长期维护验证跑通只是开始。真正让这个 Skill 迭代 20 次没乱掉的是版本治理和 CI 守门。这一节说清楚怎么把 Skill 当工程资产维护。CHANGELOG 的写法是关键。不要写「修了个 bug」「加了新功能」这种流水账。每个版本五个固定段落Added、Changed、Fixed、Notes、Not in MVP。其中 Not in MVP 最重要——它记录「刻意没做什么」。v7.3.2 写了「Not in MVP: 完整断点续导 exportPhase 2 TODO」到 v7.4 就实现了。不做和暂时不做是两回事写清楚才能让下个版本有输入。任务编号体系也要有。每个变更带编号比如 V742-001、V745-004。不是「改了一个上传问题」而是「V743-001: upload_done 时 progress.json 的 pages_done 与 result.json 一致」。跨版本讨论时可以精确到单条不用翻聊天记录。每次迭代配测试。v7.3.4 做限流配 test_throttling.pyv7.4.2 做试运行配 test_trial_run.py7 项v7.4.5 做分批配 test_v745_patch.py≥15 项。测试不是「测了什么」的清单是「这个版本新增了什么保证」的证据。CI 守门就是前面那份 test_skill_slim.py。三行断言SKILL.md 行数 ≤ 200、7 个 references 文件全部存在、description 包含 Trigger 关键词。新增内容之前必须决定放正文还是放 references否则 CI 红。没有测试的规范迟早退化。长期维护还要注意一点references 文件会随版本增加。每次新增一个 references同步更新 SKILL.md 里的索引同步更新 CI 校验里的 required 列表。三处保持一致否则 Agent 加载时会找不到文件。如果你要把这套 Skill 用在长期编码或 Agent 场景可以考虑 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentskill_engineeringutm_campaignrewrite 。它适合需要稳定通道、长期跑 Agent 任务的场景。最后回到开头那句话这个 Skill 不是「一段好 prompt」。它是在做产品——有用户分层、有激活漏斗、有安全 IO 契约、有可观测性、有版本治理、有文档架构、有 CI 守门、有 214 个测试。你手上的 Skill 也可以这样。从建references/目录开始从写第一份结构化 CHANGELOG 开始从加三行 CI 断言开始。