1. 从一次真实的踩坑经历说起上个月我帮一个做跨境电商的朋友搭自动化工作流需求很明确让模型每天自动抓取竞品价格、生成对比表格、写一段分析文案最后推送到他的飞书群。我第一反应是用 MCP 来做毕竟过去大半年 MCP 生态铺天盖地各种 server 满天飞看起来是标准答案。结果折腾了整整两天光是让模型稳定地按顺序调用三个工具就调到我怀疑人生——它要么跳过中间步骤要么把参数传错要么在该不该调用工具这件事上反复横跳。后来我换了个思路把整个流程拆成一个Agent Skill用一份SKILL.md把触发条件、执行步骤、输出格式全部写清楚再配上几个脚本文件。同样的模型同样的任务一次跑通连续跑了三天没出岔子。那一刻我才真正理解为什么最近圈子里开始有人说Agent Skills 可能比 MCP 更值得学。这篇文章不是要踩 MCP 捧 Skills两者根本不是替代关系。我想做的是把 Agent Skills 这个东西从概念到落地讲透它到底是什么、和 MCP 的本质区别在哪、SKILL.md怎么写、实际项目里怎么组织文件、踩过哪些坑。如果你正在用 Claude Code、Claude Desktop 或者任何支持 Skills 的客户端又或者你被 MCP 的工具调用稳定性折磨过这篇应该能帮你省下不少时间。2. Agent Skills 到底是什么把做事的方法打包给模型2.1 一句话定义与核心直觉Agent Skills 的本质是把一套可复用的工作方法以文件系统的形式打包给模型。一个 Skill 就是一个文件夹里面至少有一个SKILL.md可以再附带脚本、模板、参考资料、示例数据。模型在需要的时候读取这个文件夹按照里面的说明去执行任务。你可以把它理解成给模型发了一本操作手册。以前你要让模型做一件复杂的事得在对话里一步步教它或者写一大段 system prompt。现在你把这套方法写成文档放进文件夹模型自己会去翻。更关键的是这本手册是按需加载的——模型只在判断需要时才读取不占用平时的上下文。这里有个很重要的直觉大模型本身很聪明但它缺的是你们公司/你这个项目具体该怎么做事的私有知识。Agent Skills 就是把这部分知识外化、结构化、可版本管理的载体。2.2 一个 Skill 文件夹长什么样我拿自己实际在用的一个周报生成Skill 举例目录结构是这样的weekly-report/ ├── SKILL.md # 核心说明文件必须有 ├── scripts/ │ ├── fetch_git_log.py # 拉取本周提交记录 │ └── format_table.py # 格式化输出 ├── templates/ │ └── report.md # 周报模板 └── reference/ └── style-guide.md # 写作风格参考SKILL.md是整个 Skill 的入口里面用自然语言描述这个 Skill 是干什么的、什么时候该用、具体怎么执行。其他文件都是它的弹药库。这种设计的妙处在于说明和执行分离。说明用自然语言写模型能读懂执行交给脚本稳定可靠。2.3 为什么是文件系统这个形态很多人第一次接触会问为什么不直接写个插件、写个 API答案在于渐进式披露progressive disclosure这个设计哲学。模型的上下文窗口是稀缺资源。如果你把所有能力都塞进 system prompt几轮对话下来上下文就爆了。Agent Skills 的做法是平时只让模型知道有这么个 Skill 存在等真正需要时才把SKILL.md读进来读完执行完就释放。这就像你电脑里的软件不是全部常驻内存而是用到才加载。这个机制直接决定了 Skills 特别适合流程复杂、步骤多、但不需要每轮都触发的任务。比如季度财报分析合同审查特定格式的数据清洗这些事你可能一周才做一次但每次都很繁琐。3. Agent Skills 和 MCP 到底差在哪不是替代是分工3.1 用一张表把区别说清楚网上关于Skills vs MCP的争论很多但大部分都停留在概念层面。我按自己的理解整理了一张对比表从实际使用角度出发维度Agent SkillsMCP本质打包的工作方法/知识标准化的工具/资源接口载体文件系统文件夹 Markdown协议JSON-RPC 服务加载方式按需读取渐进式披露启动时注册工具列表常驻适合场景多步骤流程、私有方法论、格式规范连接外部系统、实时数据、原子操作编写门槛会写文档 会写脚本即可需要理解协议、写 server稳定性流程由文档约束模型自主性可控依赖模型正确选择工具和参数调试难度改文档即可所见即所得需要看协议日志、排查连接生态成熟度较新正在快速铺开相对成熟server 数量多看这张表你会发现两者解决的是不同层次的问题。MCP 解决的是模型怎么和外部世界对话Skills 解决的是模型怎么按一套方法把事做对。3.2 为什么 MCP 在复杂流程里容易翻车我用 MCP 踩过的坑核心都指向同一个问题MCP 把该做什么的决策权完全交给了模型。举个例子一个典型的 MCP 工作流可能是先调用search工具查数据再调用filter工具筛选最后调用format工具输出。模型看到三个工具它得自己判断现在该调哪个参数传什么调完一个之后下一步干嘛工具多了之后这个决策空间是指数级膨胀的。模型稍微走神流程就断了。而 Agent Skills 的思路完全不同。SKILL.md里我直接写死第一步执行fetch_git_log.py第二步读取templates/report.md第三步按style-guide.md的风格生成内容。模型不需要做流程决策它只需要照着做。决策被前置到了文档编写阶段由人来完成。这就是为什么同样的任务Skills 的稳定性明显更高。3.3 两者其实可以配合我现在的做法是用 Skills 管流程用 MCP 管连接。比如那个跨境电商的项目抓竞品价格这一步需要访问外部 API我就用 MCP 挂一个数据源但整个抓取→对比→分析→推送的流程用 Skill 来编排。Skill 的文档里明确写调用 MCP 的 xxx 工具获取数据模型照做即可。这样既享受了 MCP 连接外部系统的便利又用 Skill 把流程锁死了。提示不要陷入二选一的思维。真正高效的方案往往是 Skills 做骨架、MCP 做接口各司其职。4. SKILL.md 怎么写从零到能跑通的完整拆解4.1 一份合格 SKILL.md 的四个必备部分我写了几十个 Skill 之后总结出一个稳定的结构。一份能跑通的SKILL.md至少要包含这四块第一块是元信息用 YAML frontmatter 写包括nameSkill 名称和description一句话描述。这个 description 极其关键模型就是靠它判断当前任务要不要用这个 Skill。写得太模糊模型该用的时候不用写得太宽泛模型不该用的时候乱用。第二块是触发条件明确告诉模型什么情况下该激活这个 Skill。我一般会写正例和反例比如当用户要求生成周报时使用当用户只是问某个提交记录时不要使用。第三块是执行步骤这是核心。按顺序列出每一步做什么涉及脚本的要写清楚脚本路径、参数、预期输出。第四块是输出规范规定最终结果长什么样。格式、长度、语气、必须包含的字段全部写死。4.2 一个可以直接抄的模板下面是我实际在用的周报 Skill 的SKILL.md你可以直接改成自己的场景--- name: weekly-report description: 根据本周 Git 提交记录生成结构化周报适用于需要定期汇报开发进度的场景 --- # 周报生成 Skill ## 何时使用 - 用户明确要求生成周报写本周总结 - 用户提供了时间范围并希望汇总开发工作 ## 何时不要使用 - 用户只是查询某一条提交记录 - 用户要求的是代码审查而非进度汇总 ## 执行步骤 1. 运行 scripts/fetch_git_log.py参数为本周起止日期获取提交记录 JSON 2. 读取 templates/report.md 作为输出骨架 3. 参考 reference/style-guide.md 的写作风格 4. 将提交记录按功能开发/问题修复/文档更新三类归纳 5. 每类下用简洁的条目描述避免直接粘贴 commit message ## 输出规范 - 使用 Markdown 格式 - 总长度控制在 400-600 字 - 必须包含本周完成下周计划风险与阻塞三个小节 - 语气客观不使用夸张词汇这份文档不到 40 行但它把整个流程锁得死死的。模型读完就知道该干嘛几乎不会跑偏。4.3 description 的写法决定成败我要单独强调description这一行因为它是最容易被写废的地方。我见过太多人把 description 写成这是一个很有用的 Skill或者帮助处理数据。这种写法等于没写。模型判断要不要用某个 Skill靠的就是这一句话的语义匹配。好的 description 应该包含动作 对象 场景三要素。对比一下差的写法处理销售数据好的写法根据月度销售 CSV 生成同比环比分析报告适用于需要定期输出经营分析的业务场景后者明确告诉模型输入是 CSV、输出是分析报告、场景是经营分析。模型一看就知道该不该用。注意description 不要超过两句话。太长反而会稀释关键信息模型抓不住重点。5. 实操从零搭一个能用的 Skill5.1 环境准备与目录初始化假设你已经装好了 Claude Code 或者任意支持 Skills 的客户端。第一步是找到 Skills 的存放目录。不同客户端路径不一样Claude Code 一般放在项目根目录的.claude/skills/下Claude Desktop 则在用户配置目录里。具体路径以你所用客户端的文档为准。我建议按项目组织而不是全局堆在一起。因为不同项目的 Skill 往往依赖不同的脚本和模板混在一起容易乱。初始化命令很简单mkdir -p .claude/skills/my-first-skill/{scripts,templates,reference} touch .claude/skills/my-first-skill/SKILL.md目录建好之后先别急着写复杂逻辑。我的经验是从最小可用版本开始先写一个只有SKILL.md、没有任何脚本的 Skill把流程用纯文字描述清楚跑通一次再逐步加脚本。5.2 用纯文档版 Skill 验证流程最小版本长这样--- name: meeting-notes description: 将会议录音转写文本整理成结构化会议纪要适用于需要归档会议内容的场景 --- # 会议纪要整理 Skill ## 执行步骤 1. 读取用户提供的会议转写文本 2. 识别参会人、议题、结论、待办四类信息 3. 按议题分组每个议题下写清讨论要点和结论 4. 待办事项单独成节标注负责人和截止时间 ## 输出规范 - Markdown 格式 - 待办事项用 checkbox 列表 - 未明确负责人的待办标注待认领这个版本没有任何脚本全靠模型理解。跑几次之后你会发现哪些步骤模型容易理解偏差哪些地方需要更明确的约束。这个过程本身就是最好的需求梳理。等你把文档打磨到模型稳定执行了再考虑把重复性高的步骤抽成脚本。5.3 加入脚本把不稳定环节固化纯文档版跑顺之后下一步是把模型容易做错但逻辑确定的环节抽成脚本。比如会议纪要里从转写文本提取待办这一步如果格式比较固定完全可以用正则或者简单 NLP 脚本处理比模型判断稳定得多。脚本写好后在SKILL.md里这样引用## 执行步骤 1. 运行 scripts/extract_todos.py输入为转写文本路径输出为待办 JSON 2. 读取待办 JSON结合上下文补全负责人和截止时间 3. 其余内容由模型归纳整理这里的关键是明确脚本的输入输出契约。模型不需要知道脚本内部怎么实现它只需要知道传什么进去、拿什么出来。这种黑盒式的分工让整个流程既稳定又灵活。5.4 参数计算与选择以超时和重试为例脚本调用涉及外部 API 时超时和重试参数必须显式设定不能靠默认值。我的经验参数是这样的超时时间单次请求设 10-30 秒。太短容易误判失败太长会拖垮整个流程。如果是批量任务按单次超时 × 最大重试次数 × 任务数估算总耗时确保在可接受范围内。重试次数一般设 2-3 次。超过 3 次说明不是偶发问题重试也是浪费。重试间隔用指数退避第一次等 1 秒第二次 2 秒第三次 4 秒。避免瞬间打爆对方接口。这些参数我会直接写在脚本里并在SKILL.md的步骤说明中注明脚本已内置重试逻辑无需模型干预。这样模型就不会自作主张地重复调用。6. 常见问题与排查技巧实录6.1 模型不触发 Skill 怎么办这是最高频的问题。你辛辛苦苦写了个 Skill结果模型压根不用。排查顺序是这样的先查 description。90% 的情况是 description 写得太模糊模型匹配不上。把用户可能的说法列出来确保 description 里覆盖了这些关键词。再查触发条件。如果你在SKILL.md里写了何时不要使用检查是不是写得太宽泛把正常场景也排除了。最后查客户端配置。确认 Skill 目录路径正确、文件命名规范必须是SKILL.md大小写敏感、frontmatter 格式没写错。6.2 模型触发了但执行跑偏如果 Skill 被激活了但模型没按步骤走通常是这几个原因步骤描述有歧义。比如处理数据这种说法模型不知道具体怎么处理。改成读取 CSV按日期列排序输出前 100 行。步骤之间缺少衔接。模型做完第一步不知道下一步干嘛。每步结尾明确写完成后进入下一步。输出规范不够具体。只说输出报告模型就自由发挥。要写清楚格式、长度、必含字段。我一般会在SKILL.md末尾加一句严格按上述步骤执行不要自行增减步骤能显著降低跑偏概率。6.3 脚本报错的排查思路脚本报错时先看错误类型错误类型常见原因排查方向文件找不到路径写错、相对路径基准不对用绝对路径或基于 Skill 根目录的路径权限拒绝脚本没有执行权限chmod x加执行权限依赖缺失环境没装对应库在 Skill 里附requirements.txt并注明参数错误模型传参格式不对在 SKILL.md 里明确参数格式和示例超时外部接口慢或网络问题加超时和重试或改用异步提示脚本里一定要加清晰的错误输出。模型看到具体错误信息往往能自己修正。如果只报执行失败模型就懵了。6.4 独家避坑技巧分享几个我踩坑换来的经验技巧一Skill 名称用英文短横线。中文名或者带空格的名称在某些客户端会出问题用weekly-report这种格式最稳。技巧二脚本输出用 JSON。JSON 结构清晰模型解析起来不容易出错。避免输出大段自然语言让模型去猜。技巧三给 Skill 写一个自检步骤。在流程最后加一步检查输出是否满足规范不满足则重新生成能大幅提升最终质量。技巧四版本管理。Skill 文件夹直接纳入 Git 管理每次改动都有记录。团队协作时谁改了什么一目了然。技巧五先手动跑一遍脚本。写进SKILL.md之前自己在终端把脚本跑通确认输入输出符合预期。别让模型当你的第一个测试员。7. 什么场景该用 Skills什么场景别硬上7.1 最适合 Skills 的三类场景第一类是流程固定的重复性任务。周报、月报、数据清洗、格式转换这些事步骤明确、每次差不多用 Skill 封装一次之后一劳永逸。第二类是私有方法论。比如你们团队特有的代码审查清单、内容审核标准、客户沟通话术。这些知识模型本身没有写成 Skill 就能复用。第三类是多步骤编排。需要按顺序做几件事、中间有依赖关系的任务用 Skill 把流程锁死比让模型自由发挥稳定得多。7.2 不适合 Skills 的情况实时性要求极高的场景。Skill 是文件加载有读取开销。如果是毫秒级响应的需求直接调 API 更合适。纯原子操作。如果任务就是查一下天气这种单步操作写个 Skill 反而累赘直接用 MCP 工具或者函数调用就行。需要频繁动态变化的逻辑。Skill 的流程是写死的如果业务规则天天变维护成本会很高。这种情况更适合把变化部分抽成配置或外部服务。7.3 我的实际组合策略现在我的项目里通常是这么分工的底层用 MCP 连接各种外部系统数据库、API、文件服务中层用 Skills 编排业务流程上层用对话处理临时性、探索性的需求。三层各司其职既稳定又灵活。这套组合跑了大半年最大的感受是别指望一个技术解决所有问题。MCP 火的时候一窝蜂上 MCPSkills 火了又一窝蜂上 Skills最后发现真正好用的方案都是混搭的。理解每个工具擅长什么、不擅长什么比追热点重要得多。8. 关于学习优先级的一点个人看法回到标题那个问题Agent Skills 是不是比 MCP 更值得学我的答案是如果你时间有限先学 Skills。原因很实在——Skills 的门槛低得多会写文档、会写点脚本就能上手而且它直接解决的是怎么让模型稳定干活这个最痛的问题。MCP 涉及协议、服务端开发、连接管理学习曲线更陡而且很多时候你并不需要自己写 MCP server用现成的就行。但先学不等于只学。等你用 Skills 把流程跑顺了自然会遇到需要连接外部系统的场景那时候再补 MCP 的知识带着具体问题去学效率高得多。我自己就是这么过来的先用 Skills 解决了流程稳定性被逼着去研究 MCP 怎么接数据源反而理解得更深。最后分享一个我最近在用的练习方法每当你发现自己在对话里重复教模型同一件事超过两次就停下来把它写成一个 Skill。坚持一个月你会攒下一套完全属于自己的能力库。这比收藏一百篇教程都管用。 Agent Skills 实战指南：用 SKILL.md 让模型稳定执行复杂工作流
1. 从一次真实的踩坑经历说起上个月我帮一个做跨境电商的朋友搭自动化工作流需求很明确让模型每天自动抓取竞品价格、生成对比表格、写一段分析文案最后推送到他的飞书群。我第一反应是用 MCP 来做毕竟过去大半年 MCP 生态铺天盖地各种 server 满天飞看起来是标准答案。结果折腾了整整两天光是让模型稳定地按顺序调用三个工具就调到我怀疑人生——它要么跳过中间步骤要么把参数传错要么在该不该调用工具这件事上反复横跳。后来我换了个思路把整个流程拆成一个Agent Skill用一份SKILL.md把触发条件、执行步骤、输出格式全部写清楚再配上几个脚本文件。同样的模型同样的任务一次跑通连续跑了三天没出岔子。那一刻我才真正理解为什么最近圈子里开始有人说Agent Skills 可能比 MCP 更值得学。这篇文章不是要踩 MCP 捧 Skills两者根本不是替代关系。我想做的是把 Agent Skills 这个东西从概念到落地讲透它到底是什么、和 MCP 的本质区别在哪、SKILL.md怎么写、实际项目里怎么组织文件、踩过哪些坑。如果你正在用 Claude Code、Claude Desktop 或者任何支持 Skills 的客户端又或者你被 MCP 的工具调用稳定性折磨过这篇应该能帮你省下不少时间。2. Agent Skills 到底是什么把做事的方法打包给模型2.1 一句话定义与核心直觉Agent Skills 的本质是把一套可复用的工作方法以文件系统的形式打包给模型。一个 Skill 就是一个文件夹里面至少有一个SKILL.md可以再附带脚本、模板、参考资料、示例数据。模型在需要的时候读取这个文件夹按照里面的说明去执行任务。你可以把它理解成给模型发了一本操作手册。以前你要让模型做一件复杂的事得在对话里一步步教它或者写一大段 system prompt。现在你把这套方法写成文档放进文件夹模型自己会去翻。更关键的是这本手册是按需加载的——模型只在判断需要时才读取不占用平时的上下文。这里有个很重要的直觉大模型本身很聪明但它缺的是你们公司/你这个项目具体该怎么做事的私有知识。Agent Skills 就是把这部分知识外化、结构化、可版本管理的载体。2.2 一个 Skill 文件夹长什么样我拿自己实际在用的一个周报生成Skill 举例目录结构是这样的weekly-report/ ├── SKILL.md # 核心说明文件必须有 ├── scripts/ │ ├── fetch_git_log.py # 拉取本周提交记录 │ └── format_table.py # 格式化输出 ├── templates/ │ └── report.md # 周报模板 └── reference/ └── style-guide.md # 写作风格参考SKILL.md是整个 Skill 的入口里面用自然语言描述这个 Skill 是干什么的、什么时候该用、具体怎么执行。其他文件都是它的弹药库。这种设计的妙处在于说明和执行分离。说明用自然语言写模型能读懂执行交给脚本稳定可靠。2.3 为什么是文件系统这个形态很多人第一次接触会问为什么不直接写个插件、写个 API答案在于渐进式披露progressive disclosure这个设计哲学。模型的上下文窗口是稀缺资源。如果你把所有能力都塞进 system prompt几轮对话下来上下文就爆了。Agent Skills 的做法是平时只让模型知道有这么个 Skill 存在等真正需要时才把SKILL.md读进来读完执行完就释放。这就像你电脑里的软件不是全部常驻内存而是用到才加载。这个机制直接决定了 Skills 特别适合流程复杂、步骤多、但不需要每轮都触发的任务。比如季度财报分析合同审查特定格式的数据清洗这些事你可能一周才做一次但每次都很繁琐。3. Agent Skills 和 MCP 到底差在哪不是替代是分工3.1 用一张表把区别说清楚网上关于Skills vs MCP的争论很多但大部分都停留在概念层面。我按自己的理解整理了一张对比表从实际使用角度出发维度Agent SkillsMCP本质打包的工作方法/知识标准化的工具/资源接口载体文件系统文件夹 Markdown协议JSON-RPC 服务加载方式按需读取渐进式披露启动时注册工具列表常驻适合场景多步骤流程、私有方法论、格式规范连接外部系统、实时数据、原子操作编写门槛会写文档 会写脚本即可需要理解协议、写 server稳定性流程由文档约束模型自主性可控依赖模型正确选择工具和参数调试难度改文档即可所见即所得需要看协议日志、排查连接生态成熟度较新正在快速铺开相对成熟server 数量多看这张表你会发现两者解决的是不同层次的问题。MCP 解决的是模型怎么和外部世界对话Skills 解决的是模型怎么按一套方法把事做对。3.2 为什么 MCP 在复杂流程里容易翻车我用 MCP 踩过的坑核心都指向同一个问题MCP 把该做什么的决策权完全交给了模型。举个例子一个典型的 MCP 工作流可能是先调用search工具查数据再调用filter工具筛选最后调用format工具输出。模型看到三个工具它得自己判断现在该调哪个参数传什么调完一个之后下一步干嘛工具多了之后这个决策空间是指数级膨胀的。模型稍微走神流程就断了。而 Agent Skills 的思路完全不同。SKILL.md里我直接写死第一步执行fetch_git_log.py第二步读取templates/report.md第三步按style-guide.md的风格生成内容。模型不需要做流程决策它只需要照着做。决策被前置到了文档编写阶段由人来完成。这就是为什么同样的任务Skills 的稳定性明显更高。3.3 两者其实可以配合我现在的做法是用 Skills 管流程用 MCP 管连接。比如那个跨境电商的项目抓竞品价格这一步需要访问外部 API我就用 MCP 挂一个数据源但整个抓取→对比→分析→推送的流程用 Skill 来编排。Skill 的文档里明确写调用 MCP 的 xxx 工具获取数据模型照做即可。这样既享受了 MCP 连接外部系统的便利又用 Skill 把流程锁死了。提示不要陷入二选一的思维。真正高效的方案往往是 Skills 做骨架、MCP 做接口各司其职。4. SKILL.md 怎么写从零到能跑通的完整拆解4.1 一份合格 SKILL.md 的四个必备部分我写了几十个 Skill 之后总结出一个稳定的结构。一份能跑通的SKILL.md至少要包含这四块第一块是元信息用 YAML frontmatter 写包括nameSkill 名称和description一句话描述。这个 description 极其关键模型就是靠它判断当前任务要不要用这个 Skill。写得太模糊模型该用的时候不用写得太宽泛模型不该用的时候乱用。第二块是触发条件明确告诉模型什么情况下该激活这个 Skill。我一般会写正例和反例比如当用户要求生成周报时使用当用户只是问某个提交记录时不要使用。第三块是执行步骤这是核心。按顺序列出每一步做什么涉及脚本的要写清楚脚本路径、参数、预期输出。第四块是输出规范规定最终结果长什么样。格式、长度、语气、必须包含的字段全部写死。4.2 一个可以直接抄的模板下面是我实际在用的周报 Skill 的SKILL.md你可以直接改成自己的场景--- name: weekly-report description: 根据本周 Git 提交记录生成结构化周报适用于需要定期汇报开发进度的场景 --- # 周报生成 Skill ## 何时使用 - 用户明确要求生成周报写本周总结 - 用户提供了时间范围并希望汇总开发工作 ## 何时不要使用 - 用户只是查询某一条提交记录 - 用户要求的是代码审查而非进度汇总 ## 执行步骤 1. 运行 scripts/fetch_git_log.py参数为本周起止日期获取提交记录 JSON 2. 读取 templates/report.md 作为输出骨架 3. 参考 reference/style-guide.md 的写作风格 4. 将提交记录按功能开发/问题修复/文档更新三类归纳 5. 每类下用简洁的条目描述避免直接粘贴 commit message ## 输出规范 - 使用 Markdown 格式 - 总长度控制在 400-600 字 - 必须包含本周完成下周计划风险与阻塞三个小节 - 语气客观不使用夸张词汇这份文档不到 40 行但它把整个流程锁得死死的。模型读完就知道该干嘛几乎不会跑偏。4.3 description 的写法决定成败我要单独强调description这一行因为它是最容易被写废的地方。我见过太多人把 description 写成这是一个很有用的 Skill或者帮助处理数据。这种写法等于没写。模型判断要不要用某个 Skill靠的就是这一句话的语义匹配。好的 description 应该包含动作 对象 场景三要素。对比一下差的写法处理销售数据好的写法根据月度销售 CSV 生成同比环比分析报告适用于需要定期输出经营分析的业务场景后者明确告诉模型输入是 CSV、输出是分析报告、场景是经营分析。模型一看就知道该不该用。注意description 不要超过两句话。太长反而会稀释关键信息模型抓不住重点。5. 实操从零搭一个能用的 Skill5.1 环境准备与目录初始化假设你已经装好了 Claude Code 或者任意支持 Skills 的客户端。第一步是找到 Skills 的存放目录。不同客户端路径不一样Claude Code 一般放在项目根目录的.claude/skills/下Claude Desktop 则在用户配置目录里。具体路径以你所用客户端的文档为准。我建议按项目组织而不是全局堆在一起。因为不同项目的 Skill 往往依赖不同的脚本和模板混在一起容易乱。初始化命令很简单mkdir -p .claude/skills/my-first-skill/{scripts,templates,reference} touch .claude/skills/my-first-skill/SKILL.md目录建好之后先别急着写复杂逻辑。我的经验是从最小可用版本开始先写一个只有SKILL.md、没有任何脚本的 Skill把流程用纯文字描述清楚跑通一次再逐步加脚本。5.2 用纯文档版 Skill 验证流程最小版本长这样--- name: meeting-notes description: 将会议录音转写文本整理成结构化会议纪要适用于需要归档会议内容的场景 --- # 会议纪要整理 Skill ## 执行步骤 1. 读取用户提供的会议转写文本 2. 识别参会人、议题、结论、待办四类信息 3. 按议题分组每个议题下写清讨论要点和结论 4. 待办事项单独成节标注负责人和截止时间 ## 输出规范 - Markdown 格式 - 待办事项用 checkbox 列表 - 未明确负责人的待办标注待认领这个版本没有任何脚本全靠模型理解。跑几次之后你会发现哪些步骤模型容易理解偏差哪些地方需要更明确的约束。这个过程本身就是最好的需求梳理。等你把文档打磨到模型稳定执行了再考虑把重复性高的步骤抽成脚本。5.3 加入脚本把不稳定环节固化纯文档版跑顺之后下一步是把模型容易做错但逻辑确定的环节抽成脚本。比如会议纪要里从转写文本提取待办这一步如果格式比较固定完全可以用正则或者简单 NLP 脚本处理比模型判断稳定得多。脚本写好后在SKILL.md里这样引用## 执行步骤 1. 运行 scripts/extract_todos.py输入为转写文本路径输出为待办 JSON 2. 读取待办 JSON结合上下文补全负责人和截止时间 3. 其余内容由模型归纳整理这里的关键是明确脚本的输入输出契约。模型不需要知道脚本内部怎么实现它只需要知道传什么进去、拿什么出来。这种黑盒式的分工让整个流程既稳定又灵活。5.4 参数计算与选择以超时和重试为例脚本调用涉及外部 API 时超时和重试参数必须显式设定不能靠默认值。我的经验参数是这样的超时时间单次请求设 10-30 秒。太短容易误判失败太长会拖垮整个流程。如果是批量任务按单次超时 × 最大重试次数 × 任务数估算总耗时确保在可接受范围内。重试次数一般设 2-3 次。超过 3 次说明不是偶发问题重试也是浪费。重试间隔用指数退避第一次等 1 秒第二次 2 秒第三次 4 秒。避免瞬间打爆对方接口。这些参数我会直接写在脚本里并在SKILL.md的步骤说明中注明脚本已内置重试逻辑无需模型干预。这样模型就不会自作主张地重复调用。6. 常见问题与排查技巧实录6.1 模型不触发 Skill 怎么办这是最高频的问题。你辛辛苦苦写了个 Skill结果模型压根不用。排查顺序是这样的先查 description。90% 的情况是 description 写得太模糊模型匹配不上。把用户可能的说法列出来确保 description 里覆盖了这些关键词。再查触发条件。如果你在SKILL.md里写了何时不要使用检查是不是写得太宽泛把正常场景也排除了。最后查客户端配置。确认 Skill 目录路径正确、文件命名规范必须是SKILL.md大小写敏感、frontmatter 格式没写错。6.2 模型触发了但执行跑偏如果 Skill 被激活了但模型没按步骤走通常是这几个原因步骤描述有歧义。比如处理数据这种说法模型不知道具体怎么处理。改成读取 CSV按日期列排序输出前 100 行。步骤之间缺少衔接。模型做完第一步不知道下一步干嘛。每步结尾明确写完成后进入下一步。输出规范不够具体。只说输出报告模型就自由发挥。要写清楚格式、长度、必含字段。我一般会在SKILL.md末尾加一句严格按上述步骤执行不要自行增减步骤能显著降低跑偏概率。6.3 脚本报错的排查思路脚本报错时先看错误类型错误类型常见原因排查方向文件找不到路径写错、相对路径基准不对用绝对路径或基于 Skill 根目录的路径权限拒绝脚本没有执行权限chmod x加执行权限依赖缺失环境没装对应库在 Skill 里附requirements.txt并注明参数错误模型传参格式不对在 SKILL.md 里明确参数格式和示例超时外部接口慢或网络问题加超时和重试或改用异步提示脚本里一定要加清晰的错误输出。模型看到具体错误信息往往能自己修正。如果只报执行失败模型就懵了。6.4 独家避坑技巧分享几个我踩坑换来的经验技巧一Skill 名称用英文短横线。中文名或者带空格的名称在某些客户端会出问题用weekly-report这种格式最稳。技巧二脚本输出用 JSON。JSON 结构清晰模型解析起来不容易出错。避免输出大段自然语言让模型去猜。技巧三给 Skill 写一个自检步骤。在流程最后加一步检查输出是否满足规范不满足则重新生成能大幅提升最终质量。技巧四版本管理。Skill 文件夹直接纳入 Git 管理每次改动都有记录。团队协作时谁改了什么一目了然。技巧五先手动跑一遍脚本。写进SKILL.md之前自己在终端把脚本跑通确认输入输出符合预期。别让模型当你的第一个测试员。7. 什么场景该用 Skills什么场景别硬上7.1 最适合 Skills 的三类场景第一类是流程固定的重复性任务。周报、月报、数据清洗、格式转换这些事步骤明确、每次差不多用 Skill 封装一次之后一劳永逸。第二类是私有方法论。比如你们团队特有的代码审查清单、内容审核标准、客户沟通话术。这些知识模型本身没有写成 Skill 就能复用。第三类是多步骤编排。需要按顺序做几件事、中间有依赖关系的任务用 Skill 把流程锁死比让模型自由发挥稳定得多。7.2 不适合 Skills 的情况实时性要求极高的场景。Skill 是文件加载有读取开销。如果是毫秒级响应的需求直接调 API 更合适。纯原子操作。如果任务就是查一下天气这种单步操作写个 Skill 反而累赘直接用 MCP 工具或者函数调用就行。需要频繁动态变化的逻辑。Skill 的流程是写死的如果业务规则天天变维护成本会很高。这种情况更适合把变化部分抽成配置或外部服务。7.3 我的实际组合策略现在我的项目里通常是这么分工的底层用 MCP 连接各种外部系统数据库、API、文件服务中层用 Skills 编排业务流程上层用对话处理临时性、探索性的需求。三层各司其职既稳定又灵活。这套组合跑了大半年最大的感受是别指望一个技术解决所有问题。MCP 火的时候一窝蜂上 MCPSkills 火了又一窝蜂上 Skills最后发现真正好用的方案都是混搭的。理解每个工具擅长什么、不擅长什么比追热点重要得多。8. 关于学习优先级的一点个人看法回到标题那个问题Agent Skills 是不是比 MCP 更值得学我的答案是如果你时间有限先学 Skills。原因很实在——Skills 的门槛低得多会写文档、会写点脚本就能上手而且它直接解决的是怎么让模型稳定干活这个最痛的问题。MCP 涉及协议、服务端开发、连接管理学习曲线更陡而且很多时候你并不需要自己写 MCP server用现成的就行。但先学不等于只学。等你用 Skills 把流程跑顺了自然会遇到需要连接外部系统的场景那时候再补 MCP 的知识带着具体问题去学效率高得多。我自己就是这么过来的先用 Skills 解决了流程稳定性被逼着去研究 MCP 怎么接数据源反而理解得更深。最后分享一个我最近在用的练习方法每当你发现自己在对话里重复教模型同一件事超过两次就停下来把它写成一个 Skill。坚持一个月你会攒下一套完全属于自己的能力库。这比收藏一百篇教程都管用。