1. 为什么你的 Skill 总是不被触发从一次真实翻车说起先说结论Skill 能不能被 Agent 用起来90% 取决于 YAML Frontmatter 里的 description 写得对不对而不是你的 SKILL.md 正文有多详细。我见过太多人把 SKILL.md 写成三千字的技术手册结果 Agent 从头到尾压根没加载它——因为 description 只写了一句「A skill for processing documents」。这篇聚焦 Agent Skills 的工程化编写把 SKILL.md 目录结构、YAML Frontmatter 字段语义、description 触发词设计拆开讲最后给一份可直接复制的模板并演示怎么在 Agent 里验证 description 到底有没有命中。适合谁已经在用 Claude Code / Cline / Codex 这类工具、想把自己的重复工作沉淀成可复用能力单元的开发者。Skill 的本质是一个文件夹里面至少有一个 SKILL.md。这个文件是给模型看的说明书回答三件事什么时候该调用触发条件、怎么做步骤/模板/脚本、不该做什么边界与反模式。它和 prompt 的区别在于prompt 是一次性输入skill 是可复用、可版本化、可迭代评估的能力单元它和 tool 的区别在于tool 是模型直接调用的动作接口skill 是指导模型如何组合 tools 完成一类工作的知识包。理解一个核心设计哲学——渐进披露。Skill 的加载分三级L1 是元数据name description永远在上下文里约 100 词只承担触发决策L2 是 SKILL.md 正文被触发后才加载建议控制在 500 行以内承担核心工作流和路由L3 是附属文件references/、scripts/、assets/模型按需 Read深度不限。记住一句话L2 是路由不是百科全书。当 SKILL.md 快超过 500 行就该把细节剥到 references/正文只留一句「如果要做 X请阅读 references/x.md」。下面从物理结构开始一层层把可复制的配置给出来。2. SKILL.md 目录结构与 YAML Frontmatter 字段语义详解2.1 物理结构最小可用与完整形态官方推荐的结构长这样目录名建议 kebab-caseskill-name/ ├── SKILL.md # 必需YAML frontmatter Markdown 正文 ├── LICENSE.txt # 强烈建议公开发布时的免责与产权声明 ├── scripts/ # 可选确定性脚本Python/Node/Bash │ ├── main_tool.py │ └── utils.py ├── references/ # 可选按需加载的深度文档 │ ├── advanced.md │ └── schemas.md ├── assets/ # 可选产物中直接使用的静态资源 │ └── template.html ├── examples/ # 可选范例、样例输入输出 │ └── sample-input.md ├── templates/ # 可选起始模板HTML/JS 骨架 ├── agents/ # 可选子 agent 的 system prompt 片段 │ └── grader.md └── requirements.txt # 可选Python 依赖清单两条硬约定必须遵守。第一文件夹名、name frontmatter 字段、marketplace 中注册的 skill 名三者严格一致比如 pdf、docx、skill-creator。第二把 skill 视为「一个可移植的最小单元」不要在 SKILL.md 里引用文件夹外的路径否则打包移植必挂。各目录的职责边界用一张表对照最清楚目录/文件用途何时使用SKILL.md主入口含 frontmatter 正文必需LICENSE.txt完整 license 文本公开发布时推荐scripts/确定性代码模型黑箱调用有重复性/可自动化步骤时references/长参考文档按需读取单个 SKILL.md 装不下时assets/出现在最终产物里的资源需要打包到输出中examples/样例集正/反例类目繁多SKILL.md 只做路由templates/起始骨架输出遵循固定模板agents/子 agent 的 system promptskill 会 spawn subagent 时requirements.txtPython 依赖清单scripts/ 有外部依赖时2.2 YAML Frontmatter必填与可选字段SKILL.md 顶部必须以---分隔的 YAML 块开始。必填字段只有两个--- name: my-skill-name description: 一句/一段说明「这个 skill 做什么 什么时候应该被触发」。 这是 skill 唯一的触发信号务必写好。 ---可选字段里version 建议写语义化版本号当前各客户端尚未统一支持但有助于团队内版本管理license 用于指向 LICENSE.txt 或写 Proprietarycompatibility 用于声明依赖工具/环境较少使用。关于 name 的约束全小写、连字符分隔kebab-case、不与其他 skill 冲突建议先用 marketplace 检索、与目录名严格一致重命名时要同步.claude-plugin/marketplace.json。2.3 description唯一的触发信号模型是否加载这个 skill几乎完全由 description 决定。它既是「电梯陈述」也是「路由规则」。优质 description 有六个特征我按重要性排第一主动推销。skill 天然容易 undertrigger模型不主动使用写法上要略带 push 语气比如「Make sure to use this skill whenever the user mentions dashboards, data visualization, or wants to display any kind of company data — even if they dont explicitly ask for a dashboard.」第二列出触发词/触发场景把用户可能说的短语列出来例如 PRD / RFC / design doc / write a doc。第三列出应当跳过的场景用Do NOT trigger when …显式划边界。第四包含 TRIGGER / SKIP 路由头参考 claude-api 的写法TRIGGER — read BEFORE opening the target file … SKIP only when another provider is being worked on …。这把 description 从「元数据」升级为「路由器」。第五创作型 skill 加版权提醒比如 algorithmic-art / canvas-design 都会写「Create original … rather than copying existing artists work to avoid copyright violations.」第六保持完整语境不要写「Format PDF」而要写「Fill out interactive PDF forms, extract text/tables from PDFs, redact content, or convert to images. Trigger whenever a .pdf file is mentioned.」2.4 SKILL.md 正文的常见骨架正文没有强制结构但高价值模块反复出现可按需拼装。顶部放一张 Quick Reference 决策表让模型进入 skill 后第一眼就能路由## Quick Reference | 任务 | 用什么 | | --- | --- | | 填写可交互 PDF 表单 | 阅读 forms.md | | 从 PDF 中提取文本 | 使用 pdfplumber | | 生成新 PDF | 使用 reportlab |往下依次是 Overview / When to use3–5 行自我介绍、Workflow / Process编号阶段每阶段写清目的、动作、检查点、准入条件、Common Pitfalls / Anti-patterns显式列出过去失败过的写法价值极高、QA 自检 checklist让 QA 变成可执行动作、Reference Files 索引列出所有 L3 附属文件与何时读取。3. 可直接复制的 SKILL.md 模板与 Frontmatter 配置这一节给一份能直接落地的模板。假设你要做一个「把会议纪要整理成结构化周报」的 skill目录名weekly-report。3.1 完整 SKILL.md 模板--- name: weekly-report description: 把零散的会议纪要、聊天记录、任务清单整理成结构化周报。 Trigger whenever the user mentions 周报、weekly report、周总结、 会议纪要整理、把这几天的记录汇总一下, or wants to turn meeting notes into a structured summary — even if they dont say the word 周报. Do NOT trigger when the user only wants to translate a single message or format a one-off email. version: 1.0.0 license: Complete terms in LICENSE.txt --- # Weekly Report ## Overview 把非结构化的输入会议纪要、聊天记录、任务清单整理成固定结构的周报。 适用于需要周期性汇报的团队场景不适用于单条消息翻译或一次性邮件排版。 ## Quick Reference | 任务 | 用什么 | | --- | --- | | 输入是会议纪要 | 阅读 references/meeting-format.md | | 输入是聊天记录 | 阅读 references/chat-format.md | | 需要生成 Markdown 周报 | 运行 scripts/build_report.py | | 需要导出 HTML | 使用 templates/report.html | ## Workflow ### Step 1: 识别输入类型 判断输入是会议纪要、聊天记录还是任务清单路由到对应 reference。 ### Step 2: 抽取结构化字段 按 references/schema.md 抽取本周完成、进行中、阻塞项、下周计划。 ### Step 3: 生成周报 调用 python scripts/build_report.py --input file --out report.md。 ## Common Pitfalls - 把「进行中」的任务写进「本周完成」 - 严格按状态字段归类不确定时标注 [待确认] - 直接读 scripts/build_report.py 源码 - 先跑 python scripts/build_report.py --help ## Reference Files - references/meeting-format.md — 输入是会议纪要时读 - references/chat-format.md — 输入是聊天记录时读 - references/schema.md — 抽取字段定义3.2 测试用例配置evals.json写完模板配 2–3 条测试 prompt一半 should-trigger、一半 should-not-trigger{ skill_name: weekly-report, evals: [ { id: 1, prompt: 帮我把这周的会议纪要整理成周报, expected_output: 输出包含本周完成/进行中/阻塞项/下周计划四段 }, { id: 2, prompt: 把这几天的聊天记录汇总一下, expected_output: 触发 weekly-report按 schema 抽取字段 }, { id: 3, prompt: 帮我把这句话翻译成英文, expected_output: 不触发 weekly-report } ] }注意第 3 条should_not_trigger 必须是「貌似相关但其实不该触发」而不是显然无关的问题否则测试没有 signal。3.3 脚本的黄金规则scripts/ 目录有三条铁律。每个脚本都要有--help模型第一步永远是python scripts/foo.py --help默认黑箱调用不读源码SKILL.md 里要显式写「call as black-box; do not ingest source unless customization is required」脚本命名保持稳定重命名等于破坏使用者的记忆。在 SKILL.md 里给出可复制粘贴的完整命令python scripts/build_report.py --input notes.md --out report.md依赖用 requirements.txtPython或 package.jsonNode声明。references/ 里单文件超过 300 行时必须在文首放 TOC每个文件开头写一句「什么时候读这个文件」。4. 在 Agent 中加载并验证 description 命中效果模板写完了怎么确认 description 真的能命中这一节给可跟做的验证步骤。4.1 接入配置Base URL Key Model ID 三件套如果你用 Claude Code 或 Cline 这类支持自定义端点的 Agent需要配齐三件套。以 Claude Code 的 settings 为例配置文件路径是~/.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{ OPENAI_API_KEY: sk-你的Key, OPENAI_BASE_URL: https://taotoken.net/api }Cline 的 MCP 配置则在cline_mcp_settings.json里同样填 Base URL、Key、Model ID 三项。Key 在控制台的 API Keys 页面生成模型 ID 以你实际可用的为准。4.2 验证 description 命中的动作步骤第一步把 skill 目录放到 Agent 能扫描到的位置Claude Code 通常是项目下的.claude/skills/或用户级 skills 目录。第二步开一个新会话输入一条 should-trigger 的 prompt比如「帮我把这周的会议纪要整理成周报」。第三步观察 Agent 是否主动读取了 SKILL.md。如果命中了你会在工具调用里看到它 Read 了weekly-report/SKILL.md如果没命中它会直接开始瞎写。第四步再输入一条 should-not-trigger 的 prompt比如「帮我把这句话翻译成英文」确认它没有误触发。第五步如果 should-trigger 没命中回到 description 加触发词、加 push 语气如果 should-not-trigger 误触发加Do NOT trigger when …边界。4.3 用模型对话快速验证触发词不想每次都开 Agent 会话的话可以先用模型对话做一轮粗筛把 description 原文贴进去问「下面这些用户输入哪些应该触发这个 skill」让它逐条判断。这能快速暴露触发词覆盖不足的问题比直接跑 Agent 省时间。验证通过后再进 Agent 做端到端确认。5. 常见报错与排查401、local proxy failed、reading choices、OAuth配置和验证过程中下面几类报错出现频率最高逐个对照排查。401 Unauthorized。最常见的原因是 Key 没填对或没生效。检查三处settings.json 里的ANTHROPIC_API_KEY是否和 API Keys 页面生成的一致Key 前后有没有多余空格或换行环境变量是否被 shell 里的旧值覆盖。如果是 Codex检查auth.json的OPENAI_API_KEY字段名有没有写错。local proxy failed / connection refused。这类报错通常是 Base URL 写错或本地网络配置问题。确认ANTHROPIC_BASE_URL填的是https://taotoken.net/api注意结尾不要多加/v1或斜杠。如果之前配过其他端点检查有没有残留的代理环境变量干扰。reading choices of undefined。这是 OpenAI 兼容格式的响应解析错误通常意味着返回体不是预期的 chat completion 结构。排查方向Model ID 是否写错写了一个不存在的模型名Base URL 是否指向了正确的兼容端点请求是否被中间层改写。把 Model ID 换成确认可用的值再试。OAuth 相关报错。如果你用的是 Claude Code 的 OAuth 登录流程但同时又配了自定义 Base URL两者可能冲突。解决方式是明确走 API Key 模式清掉 OAuth 缓存只保留ANTHROPIC_BASE_URLANTHROPIC_API_KEY两项。skill 加载了但行为不对。这不是报错但更常见。排查顺序先看 description 是否命中见第 4 节再看 SKILL.md 是否超过 500 行导致重点被淹没最后看有没有 MUST/NEVER 泛滥导致模型死板。修法参考下一节的反模式表。报错最可能原因修法401 UnauthorizedKey 错误/空格/被覆盖核对 API Keys 页面清环境变量local proxy failedBase URL 写错确认https://taotoken.net/api去掉多余路径reading choices of undefinedModel ID 或端点错误换确认可用的 Model IDOAuth 冲突OAuth 与 API Key 混用清 OAuth 缓存只留 Key 模式skill 不触发description 太抽象加触发词、场景、push 语气6. 六种 Skill 形态与反模式速查写 skill 前先确定形态能省一半返工。Router 型如 internal-comms32 行适合一个大主题下多个并列子领域SKILL.md 极小永不撑爆 L2Reference 型如 claude-api578 行适合知识密集、模型反复查阅关键技巧是 description 带 TRIGGER/SKIP 路由头、显式 pin 版本Workflow 型如 skill-creator、mcp-builder适合多步骤有明确产出物用 Phase/Stage 编号每阶段有退出条件Creative/Philosophy 型如 algorithmic-art先写创作理念再写执行细节明确 FIXED vs VARIABLEHuman-in-the-loop 型如 theme-factory把「等待用户」作为流程合法节点Toolkit/Script-first 型如 docx、pdf、xlsx让脚本--help自解释明确要求不读源码。写作风格上用祈使句 说明「为什么」。反例是NEVER use requests library正例是Prefer httpx over requests because we need async support and requests is not maintained upstream。模型有 theory of mind理解原理后能举一反三纯命令只在原例上生效。只有真踩过多次坑、必须硬性阻止时才用全大写 NEVER/ALWAYS。/ 对照示例的 signal 比抽象规则强得多L2 到 L3 的路由要具体条件化比如「If you need to fill out a PDF form, readforms.md」避免「see references for more info」这种模糊写法。最后是反模式速查表写完 skill 对照一遍反模式症状修法description 过短或抽象skill 从不被触发加触发词、场景、push 语气一切写在 SKILL.md超 800 行重点淹没拆到 references/正文只留路由MUST/NEVER 泛滥模型死板无法泛化改为「因为 X所以 Y」抽象指令「Format properly」换成具体步骤 / 例子没有 Common Pitfalls常见坑反复被踩补一节反模式清单触发关键词太宽过度触发抢占其他 skill加Do NOT trigger when …脚本不带 --help模型强行读源码加 argparse 明确文档硬编码 skill 外路径打包/移植失败只用 skill 内相对路径如果你打算长期把 skill 用在编码和 Agent 场景建议配一个稳定的 Coding Plan把模型调用和 skill 迭代分开管理避免每次调 Key 打断思路。接入文档里有完整的 Base URL、Key、Model ID 配置说明照着填即可。