1. 为什么你的第一个 Skill 总是跑不起来很多人第一次接触 Skill 这个概念是被各种演示视频带进来的Agent 自己写一个技能存下来下次遇到同类任务直接复用看起来像变魔术。但真到自己动手问题立刻冒出来——SKILL.md 写完了Agent 压根不调用调用了步骤又跑偏步骤对了结果没法验收。折腾一晚上文件夹建了三个一个能稳定复用的都没有。我试过最笨的办法把一段精心打磨的提示词直接塞进 SKILL.md结果 Agent 每次触发时机都不一样同一个请求今天走这个流程明天走那个流程。后来才想明白问题不在提示词写得好不好而在于整条调用链路是断的——Skill 文件写好了但 Agent 运行时根本不知道去哪里找模型、用哪个 Key、走哪条 API 通道。这篇要解决的就是这条链路。目标很具体今晚你跟着做完手里会有一个能反复调用的 SKILL.md、一份能跑通的 settings.json 配置、一次本地验证成功的记录。全程不需要你懂 MCP 协议细节也不需要你搭任何服务端只需要一个统一的 API Key 把模型调用打通。适合谁看写过几段提示词、想让它们变成可复用资产的人正在用 Claude Code 或类似 Agent 工具、想接入自定义技能的人被各种 Key 管理、环境变量、base_url 配置绕晕的零基础开发者。热词里提到的 Skill、AI技能、Agent、SKILL.md、MCP这篇都会落到具体文件和命令上不空谈概念。核心检索词先摆出来Skill 是什么——它是一份教 AI 干活的说明书最小形态就是一个文件夹加一份 SKILL.md能做什么——把一类重复任务的做法固化下来反复调用、进 Git 管理、分享给同事适合谁——任何想让 AI 稳定执行特定流程的人。下面从零开始。2. 前置准备用 TaoToken 统一 Key 打通调用链路在写 SKILL.md 之前先把模型调用这条线接通。否则你写完技能文件Agent 触发时找不到可用的模型通道验证环节一定卡住。TaoToken 在这里扮演的角色是统一入口一个 Key、一个 API 地址兼容主流模型调用格式。你不需要为每个模型单独申请账号、单独配环境变量也不用在多个 base_url 之间来回切换。对写 Skill 这件事来说这意味着 SKILL.md 里描述的工作方法可以稳定地跑在同一个通道上验证结果可复现。先拿到 Key。访问控制台页面登录后进入 API Keys 管理https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_first_agent在页面里创建一个新的 Key复制保存。注意两点Key 只在创建时完整显示一次关掉页面就看不到了不要把它写进任何会进 Git 的文件包括 SKILL.md。API 的基础地址是https://taotoken.net/api这个地址不加任何 UTM 参数直接作为 base_url 使用。如果你用的是 OpenAI 兼容格式的客户端配置里通常需要三项api_key、base_url、model。model 填你实际要调用的模型名称具体可用列表在模型对话页面能看到https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_first_agent如果你打算长期用 Agent 做编码类任务比如让 Skill 自动跑测试、改配置、生成代码可以了解一下 Coding Plan它针对高频编码场景做了额度优化https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_first_agent接入文档在这里遇到参数格式问题可以对照查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_first_agent这一步做完你手里应该有一个 Key 和一个 base_url。接下来把它们放进配置文件让 Agent 运行时能读到。3. 可复制配置settings.json 与 SKILL.md 骨架3.1 settings.json 配置片段不同 Agent 工具的配置文件位置不一样。Claude Code 的用户级配置通常在~/.claude/settings.json项目级在项目根目录的.claude/settings.json。如果你用的是其他支持自定义模型通道的工具找它对应的配置文件即可字段名可能略有差异但核心三项不变。下面是一份可直接复制的配置片段把sk-你的Key替换成上一步创建的真实 Key{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key }, model: claude-sonnet-4-20250514 }如果你用的工具走 OpenAI 兼容格式配置长这样{ api_key: sk-你的Key, base_url: https://taotoken.net/api, model: gpt-4o }注意base_url后面不要加/v1之类的路径具体以接入文档为准。写完后保存先别急着测 Skill用一条最简单的请求确认通道是通的。3.2 SKILL.md 最小骨架现在建目录。假设你的技能叫weekly-report放在用户级技能目录下mkdir -p ~/.claude/skills/weekly-report touch ~/.claude/skills/weekly-report/SKILL.mdSKILL.md 分两截顶部 YAML 登记名称和描述下面正文写做事方法。最小可用版本如下直接复制--- name: weekly-report description: 根据项目记录生成项目周报或状态简报。当用户要求整理本周进展、汇总风险、生成周报时使用。只生成草稿不发送消息不修改项目系统。 --- # 工作步骤 1. 读取用户指定的本周项目记录。 2. 分成已完成、进行中、风险、下周计划和待确认五类。 3. 只把有记录支持的内容写成事实。 4. 信息不足时列入待确认不要补写。 5. 按模板生成简报草稿。 # 完成条件 - 每项进展能找到对应记录 - 风险包含负责人和下一步没有信息时明确留空 - 输出是草稿不执行发送或系统写入。这份骨架里description是最关键的一行。Agent 判断要不要调用一个 Skill依据几乎全在这句话上。写成帮助处理项目内容等于没写写成生成项目周报、整理本周进展、汇总风险才是用户嘴里的原话。把用户可能说的几种说法都塞进去触发率会明显提升。正文部分只回答五个问题什么样的请求会唤起它、要读哪些资料、步骤按什么顺序走、什么动作被禁止、干到什么程度算完。第一版不需要脚本不需要 references 目录一行代码都不用加。3.3 目录结构预留等技能用上几个月正文会越滚越长。这时候再拆目录不用一开始就建全。预留结构长这样weekly-report/ ├── SKILL.md ├── references/ │ └── status-policy.md ├── scripts/ │ └── validate_brief.py ├── assets/ │ └── status-template.md └── evals/ └── evals.jsonreferences/放业务制度、字段说明、长案例assets/放输出模板、图片scripts/放格式校验、数据转换这类确定性操作evals/放测试请求与预期结果。主文件里要写清何时读哪份比如生成周报前先读取 references/status-policy.md 判断项目状态。 输出时使用 assets/status-template.md。 草稿完成后运行 scripts/validate_brief.py校验失败时修正草稿不要跳过错误。官方建议 SKILL.md 控制在 500 行以内。逼近这条线多半意味着执行路线、参考资料和样例已经搅在一起了该拆了。4. 验证请求一次本地跑通的全过程配置写完必须验证。验证分两步先确认模型通道通再确认 Skill 能被正确触发。4.1 通道验证用 curl 发一条最小请求确认 Key 和 base_url 能正常返回curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回复通道正常}] }如果返回里包含正常的文本内容说明通道通了。如果报 401检查 Key 是否复制完整报 404检查 base_url 路径是否多了或少了/v1报模型不存在去模型对话页面确认可用模型名。4.2 Skill 触发验证打开你的 Agent 工具在项目目录下发起对话。准备三条测试请求覆盖正常、边界、禁止三类场景1. 根据本周记录写一份项目状态更新。 → 应该触发读取规定来源生成草稿。 2. 记录不完整帮我写得积极一点。 → 应该触发但不能补造进度缺失内容进入待确认。 3. 整理完直接发到管理群。 → 可以生成草稿不能自动发送。第一条锚定正常场景第二条处理信息残缺第三条守住高风险动作的边界。三条都跑一遍观察 Agent 是否按 SKILL.md 里的步骤走。再补两条长得像但不该触发的请求比如帮我修改 Jira 状态给客户起草一份说明邮件。如果它到处抢活把 description 收窄该出场时找不到它就把用户的真实说法补进描述。4.3 成功结果长什么样一次成功的验证输出应该满足每项进展能找到对应记录风险包含负责人和下一步没有信息时明确留空输出是草稿不执行发送或系统写入。如果 Agent 在记录不完整时补造了进度说明正文里不要补写这条约束没生效回去把完成条件写得更硬。到这里最小版本成立调用得上、按步骤走、结果可验收。今晚的目标达成。5. 本篇常见错排查5.1 Skill 压根不触发最常见的原因是 description 写得太泛。Agent 只看到名称和描述描述里没有用户会说的关键词它就找不到。解决办法把用户真实说过的几种说法都写进 description比如周报本周进展状态简报汇总风险。第二个原因是目录位置不对。Claude Code 的用户级技能在~/.claude/skills/skill-name/SKILL.md项目级在.claude/skills/skill-name/SKILL.md。放错层级Agent 扫描不到。5.2 触发了但步骤跑偏检查正文里的步骤是不是可执行。写成整理项目信息这种模糊描述模型只能自由发挥。改成读取用户指定的本周项目记录分成已完成、进行中、风险、下周计划和待确认五类路径就清晰了。如果规则读了还做错补一个真实示例或者把确定规则移交脚本。判断一段风险描述写没写清楚交给模型核对日期格式、文件名、必填字段脚本更可靠。5.3 工具报错、连接失败先查通道用 4.1 的 curl 命令确认 Key 和 base_url 没问题。再查权限Skill 里声明只读并不能把一个可写 Token 变成只读真正决定 Agent 能碰什么的是运行时权限配置。最后查参数MCP 或 API 调用的参数格式是否和文档一致。密钥在任何情况下都不写进 Skill。MCP 的地址、认证与权限交给宿主或 Agent 配置去落实。5.4 多个 Skill 抢活每个名称和描述都参与发现竞争数量越多、描述越接近选错的概率越大。收窄描述或者重新分组。拆不拆看四个指标触发请求是否高度重叠、产出物是否同构、权限是否同级、业务是否同一个负责人。四项大体重合就留着有一项明显分岔就拆。5.5 上下文被挤爆Claude Code 当前在自动压缩后每个重新挂载的 Skill 最多保留前 5000 tokens全部重新挂载的 Skills 共享 25000 tokens。内容过长或连续调用太多较早的 Skill 会被丢掉。这是 Claude Code 的实现细节别外推成所有平台的通用限制但它说明上下文预算会实际左右执行。把长资料放进 references/ 按需读取别全堆在主文件里。6. 把 Key 和 Skill 一起用起来链路打通之后接下来就是让它跑在真实任务上。你现在手里有三样东西一个能用的 SKILL.md、一份 settings.json 配置、一次验证成功的记录。这三样构成了最小可复用单元。下一步的扩展路径很清晰规则膨胀了拆 references确定性操作交给 scripts需要外部数据再接 API 或 MCP。等它开始牵动多人、系统和数据权限、评测、版本、治理按需补齐。但顺序不能颠倒——先把一个能稳定复用的小 Skill 做出来能力再一项一项往上加。如果你在接入过程中遇到 Key 配置或通道问题回到 API Keys 页面重新生成一个 Key 试试https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_first_agent参数格式对不上查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_first_agent想先确认模型能不能正常对话去模型对话页面发一条消息https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_first_agent长期用 Agent 做编码任务Coding Plan 的额度更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentskill_first_agentSkill 的体量没有标准答案。它可以只是一段提示词也可以统辖知识库、工具和 Agent。归根结底只看一条AI 能不能靠它把一件具体的事做得更稳。今晚先跑通一个比研究三个月概念有用。