★ FEATURED ARTICLE 你肯定也遇到过这种情况同一个需求让 Claude 连着干两次一次结果是教科书级别一次是四不像。问它为什么输出不稳定它还会一本正经地告诉你我的回答基于概率分布。这其实就是大语言模型的本性——你说的话它能听懂但怎么做这件事它全靠临场发挥。Claude Skills 就是冲着这个问题来的。这篇文章不讲概念直接带你从零建一个技能包从目录结构、SKILL.md 写法、脚本封装到踩坑排查把让 AI 像专业助手一样精准干活这件事一步步落地。1. 你写的提示词为什么总是时灵时不灵——Skills 要解决的痛点1.1 一段真实对话同一个需求两种截然不同的结果我之前在做一个数据分析项目每天要让 Claude 写 SQL 查询。需求很简单从订单表里查最近 30 天各渠道的 GMV排除退款订单。第一次问它它给出了一条 70 行的 JOIN 查询还补了窗口函数做环比第二次问它直接SELECT *出来让用户自己 Excel 里筛选。同一个模型差了一个次元。问题不在模型笨在于每次对话时Claude 都在重新猜你要什么。它记得上下文但工作方式、输出格式、质量标准这些约定俗称的规矩它每次都靠推断。你可以在提示词里写清楚但写一次管一次下个会话又从零开始。用提示词模板解决这个问题本质上还是在赌模型的理解力。1.2 提示词工程的边际效应已经到头了过去一年大家都在卷提示词工程角色设定、few-shot、思维链、自洽性……我自己也写过一整套万能提示词框架开头固定、要求固定、输出格式固定刚用的时候确实效果提升明显。但用久了发现一个天花板提示词是指导性的它告诉模型要这样做却没办法把一套完整的执行流程稳定装进模型的脑子里。打个比方你招了个实习生提示词就是你在工位上贴了一张便利贴认真做事注意质量。有用吗有一点。但如果你把一个标准作业手册交给他里面有操作步骤、检查清单、输出模板他每次干活就都有章法。Claude Skills 就是那本手册——不是靠对话碰运气而是把技能稳定地挂载给模型。1.3 Skills 到底改变了什么从碰运气到按流程办事说准确一点Skills 是一组描述文件加配套脚本和资源的集合。它告诉 Claude 三件事第一什么时候该用这个技能第二这个领域的活儿具体该怎么做流程是什么第三做完之后要符合什么标准。你可以理解为给 AI 装了一本岗位说明书和一套工具箱。以前你让 Claude扮演 SQL 专家它凭记忆里的通用经验干活现在你给它挂一个 SQL 审查技能它会照着技能文件里写的步骤来先理解 schema再逐条检查高危写法输出固定格式的审查报告。输出不再看心情而是走了制度流程。这就是标题里说的精准干活的关键——不是让模型更聪明而是让它有章可循。2. Skills 的本质目录里的一份说明书加一套工具箱2.1 一份 SKILL.md 决定会不会干一堆 scripts 决定干不干得动Skills 的核心是目录结构。所有技能都放在一个统一目录下每个技能是其中一个子目录子目录里至少要有一个SKILL.md文件。skills/ └── sql-reviewer/ ├── SKILL.md ├── assets/ │ └── sql_style_guide.md └── scripts/ └── check_sql.pySKILL.md是技能的大脑用 Markdown 写前面有一小段 YAML 元数据后面是正文。元数据部分就叫 frontmatter里面name是技能名description是给 Claude 判断什么时候该用这个技能的说明。正文部分写工作流程、规则、质量标准这些实际操作层面的东西。目录里assets/是辅助资料比如行业规范、风格指南Claude 用到时再读scripts/是可执行脚本比如解析工具、校验程序Claude 需要的时候会调用。如果技能不需要脚本和资料SKILL.md 一个文件就够了。一个技能包本质上就是操作手册参考资料工具脚本的组合跟一个新员工工位上的配置差不多。2.2 和 MCP、插件、长上下文提示词的区别容易混淆的是 Claude Skills 和 MCP模型上下文协议。一句话区分MCP 是给 AI 装手的让它能触达外部数据系统和工具Skills 是给 AI 装大脑模块的让它知道某类任务该怎么做。对比维度Claude SkillsMCP长篇提示词模板解决什么问题让模型掌握特定任务的流程和规范让模型能连接外部系统/API给模型临时性的指导意见生命周期长期挂载跨会话生效按会话/进程挂载仅在当前上下文有效是否含代码可选可含脚本和资源文件必需含服务端实现一般不含触发方式模型根据描述自动判断工具显式调用用户每次粘贴维护成本一次编写持续复用需维护服务端每会话一次易失配长上下文提示词的问题前面说过了每次会话重新生效容易超出上下文窗口MCP 适合需要实时数据交互的场景Skills 则介于两者之间适合任务知识密集但不需要外部实时数据的场景。当然它们可以组合用增强技能内部调用 MCP 工具完全可行后面进阶部分再展开。2.3 Claude 什么时候会想起这个技能触发机制新接触 Skills 的人一个最常见的疑问是我装了技能包Claude 怎么知道什么时候用它不是靠你每次手动点名而是靠SKILL.mdfrontmatter 里的description字段自动判断的。当你给 Claude 派一个任务模型会先做一个隐式的意图识别把这个任务和所有已挂载技能的描述匹配。匹配上了它就会去读对应技能文件把里面的流程加载进本轮上下文按照技能写的步骤干活。所以description的写法非常关键——它决定了 AI 能不能在你需要的时候想起这个技能。举个例子如果你的描述只写了SQL 相关那用户说帮我优化一下报表时它可能想不起来如果写成审查和优化 SQL 查询当用户要求检查查询性能、定位慢查询、重写低效 SQL 或评估查询安全性时使用那触发精准度就会高很多。后面第 4 节我会专门讲 description 的写法技巧。3. 上手第一个 Skill从建目录到跑通完整流程3.1 环境准备找对全局和项目级目录动手之前先把环境理清楚。Skills 有全局和项目两个存放位置全局的放在用户主目录下~/.claude/skills/对所有项目生效项目级的放在.claude/skills/目录里只对当前项目生效适合随仓库分发。我实际使用中建议通用型技能放全局比如代码审查、文档规范、总结模板项目专用技能放项目级比如某业务的建表规范、数据口径说明。全局目录结构mkdir -p ~/.claude/skills ls ~/.claude/skills桌面端和移动端在聊天界面直接就能横向管理技能开关命令行环境则通过文件目录系统加载。我第一次用的时候就犯过错把技能文件直接扔在了~/.claude/下面而不是~/.claude/skills/里结果怎么都识别不到排查了半天。记住技能必须放在skills/下的独立子目录里子目录内是SKILL.md文件。3.2 写一个SQL 审查员Skill 的完整实操用我前面提到的 SQL 审查需求来演示一个完整技能包。先建立目录结构mkdir -p ~/.claude/skills/sql-reviewer/{assets,scripts}然后创建SKILL.md--- name: sql-reviewer description: 审查 SQL 查询的质量、性能和安全性。当用户要求检查或优化 SQL、定位慢查询、评估查询风险、重写低效查询时使用。也用于为业务团队提供新查询的上线前评审。 --- # SQL 审查专家 ## 适用场景 - 用户提交 SQL 希望检查是否有性能隐患 - 用户要求重写低效查询或优化已有查询 - 依据团队规范对查询做上线前评审 ## 工作流程 1. 理解数据库 schema确认涉及的表、字段、索引情况 2. 逐条核对检查清单见 assets/sql_style_guide.md 3. 执行 scripts/check_sql.py 做静态扫描 4. 按标准报告模板输出审查结果 ## 输出格式 ### 审查报告 - 查询概述一句话说明查询目标 - 风险等级高 / 中 / 低 - 问题清单编号 问题描述 涉及行号 修改建议 - 重写建议如有必要给出优化后的 SQL 缩写 - 结论是否建议上线 ## 质量红线 - 禁止输出裸的 SELECT *除非用户明确确认 - 禁止忽略 WHERE 条件的去全表扫描提示 - 报告必须给出可执行的修改建议不得只说有问题 ## 示例 用户问题检查这段查询有没有性能问题 sql SELECT * FROM orders WHERE status paid;正确响应先标注风险等级「中」指出 SELECT * 和缺索引可能输出重写建议。这个文件里的关键是工作流程和输出格式。工作流程规定了 AI 接手任务后的操作顺序输出格式规定了交付物的长相。这样一来无论用户问得多模糊AI 都会被拉到这套流程里来。 ### 3.3 验证与调试怎么确认 AI 真的在按流程执行 写完技能后要做一次冒烟测试。用几类典型请求分别测试明确的帮我审查这条 SQL、模糊的这查询能用吗、边缘的给我写个 SQL。看 Claude 是否主动加载技能以及输出是否遵循了报告模板。 一个实用的调试技巧是在 SKILL.md 正文里明确写上你需要先阅读并理解这个文件的全部内容再开始工作。这会促使 Claude 把技能流程纳入当前会话。还有一个方法是问它一句你的工作流程是什么看它能不能复述出技能里写的步骤。如果它答不上来大概率是技能文件没被正确加载。 我踩过的另一个坑是 YAML frontmatter 格式错误。description 里的冒号必须是半角换行不能乱缩进否则解析会失败。写完文件后建议先手动检查一遍 frontmatter 部分的格式是否正确再上线使用。 ## 4. 让 AI精准干活的三层封装触发、产出、自检 ### 4.1 触发层description 要写成人话让模型一眼看懂 很多人的技能描述写得像产品说明书抽象且没有场景感。比如SQL 相关操作、用于数据分析。这类描述在模型做意图匹配时基本是失效的。我的经验是描述要覆盖三类信息技能解决什么问题、什么情况下触发、什么情况下不要用。 markdown description: 审查和优化 SQL 查询定位性能瓶颈重写低效 SQL。当用户要求检查查询质量、评估上线风险、排查慢查询或在代码评审中看到可疑 SQL 时使用。不用于直接生成业务报表除非要求附带审查意见。写了不用于这个负向边界能显著减少误触发。什么都不约束的时候AI 可能随手就给日常问答挂上专家审查的帽子输出反而变得笨重。描述写得越具体触发越精准这是整篇文章里性价比最高的一行字。4.2 产出层流程、模板、质量标准写进 body触发只是第一步真正的精准体现在产出环节。这部分要写清楚三件事。第一操作流程。别只写检查 SQL 质量要像标准作业手册一样写步骤理解 schema → 逐条核对检查清单 → 静态扫描 → 输出报告。AI 是序列模型给它一个有顺序的流程它就会按序执行流程含糊它就自由发挥。第二输出模板。交给 AI 的文档类任务最烦的就是每次格式不统一。SKILL.md 里直接给它长什么样的样板。上面那个审查报告模板就是直接嵌在技能文件里的。输出模板一固定AI 生成的内容就像同一套模具压出来的后面的自动化解析也就有了基础。第三质量红线。这相当于给 AI 设不可为清单。比如审查 SQL 时禁止忽略全表扫描风险写周报时禁止把数据直接复制粘贴而不做解读生成营销文案时禁止编造数据。模型没有价值观层面的红线意识但它会遵守指令里的显式禁止项前提是你写得够明确。4.3 自检层让 AI 做完活自己验收一遍精准干活的最后一公里是自检。很多技能文件只写了怎么做没写怎么确认没做错。实际上我们可以在流程最后加一个自查步骤让 Claude 输出前用第二遍视角检查自己的成果。拿上面的 SQL 审查技能来举例在 SKILL.md 流程末尾加一段完成审查报告后自查以下内容是否覆盖了所有检查清单项是否给出了可执行的重写建议风险等级是否与问题清单匹配确认无误后再输出。实测下来自查步骤能明显减少漏检查项的情况。这个思路跟开发里的 code review 很像。AI 做 review 的时候review 一下自己的 review质量就稳住了。虽然没有真正的另一个 AI在把关但让模型在生成完报告后用清单逐项核对本身就能触发更审慎的生成模式。5. 实测踩坑AI无视技能的时候问题出在哪5.1 目录放错、描述太抽象、没有示例的典型翻车案例前阵子我帮同事调一个会议纪要生成技能症状是明明装好了技能但 Claude 每次都是即兴表演用自己的通用能力生成纪要完全不按技能文件里的模板来。我排查下来发现三个问题叠在一起。第一个目录层级错了。它把SKILL.md直接放进了~/.claude/skills/的根目录正确做法是放进~/.claude/skills/meeting-minutes/SKILL.md。第二个description 写的是生成会议纪要没有任何触发场景线索。当用户没说按模板这类词时模型压根没把任务跟这个技能关联起来。第三个SKILL.md 里没有给任何示例。模型不确定这个技能和普通回答有什么区别索性走老路。三个问题里描述和示例是最容易被忽视的。很多人的直觉是技能装上了就该自动生效但从模型的运行机制看它其实是看到你给的活对照技能描述决定要不要读技能文件。描述是门牌号示例是效果图缺了任何一样技能都可能沦为摆设。5.2 排查链路从加载日志到 token 观察遇到技能失效别慌按链路排查。第一步确认目录结构用tree ~/.claude/skills/看一眼有没有把 SKILL.md 放错层级。第二步确认 frontmatter 格式合法name和description都在三条横线之间且没有英文标点缺失。第三步看模型的响应风格——如果它完全不提技能里的概念比如审查报告模式、检查清单这些词说明就没加载。更高级的排查法是看 token 使用情况。加载技能文件时模型会读入大量文本所以明显会觉得回答更有章法、背景信息更丰富。如果回答又短又通用多半是没触发。有个土办法是直接在对话里问它你当前有哪些技能可用根据什么选的它能说出来就说明挂载成功说不出来就是触发链路有洞。还有个容易被忽略的坑多个技能描述里如果用了相似的关键词比如生成 SQL和审查 SQL任务稍微模糊一点模型就可能只见其一。我在实际中就把SQL 生成和SQL 审查合并成了一个技能的两个工作模式彻底断了混淆的路。5.3 规则冲突多个 Skill 抢着干活怎么办技能多了以后还会遇到抢活的问题。比如我同时挂了日报生成和数据分析师两个技能用户说帮我出今天的日报两个技能的描述都命中了模型选了哪个纯看当时上下文输出风格就时好时坏。解决思路是在描述里加排除条件。日报生成的 description 里写明用于汇总当日工作进展和个人计划不用于数据处理分析数据分析师的描述里写明用于数据提取、统计和可视化不用于个人工作日报。用负向清单把边界划清楚后误触发概率大幅降低。如果项目里技能特别多另一个做法是建一个总入口技能它本身不做具体工作只负责意图路由。用户提出需求后总入口技能根据关键词判断该调用哪个子技能整个体系变成路由器 多个执行器的架构。这个模式维护成本略高适合 5 个以上技能的场景。6. 进阶玩法多 Skill 协同与测试驱动开发6.1 把日常高频任务拆成一组技能包技能这东西用多了就能感觉到一种新的工作方式——不是想一个功能做一个技能而是把一条工作流切成几个有边界的技能包组合起来完成复杂任务。比如我现在的数据分析日常拆成了四个技能技能名职能边界触发条件schema-explorer理解并解释数据库结构用户提到表名、字段、关联关系sql-reviewer审查和优化 SQL用户提交查询或要求评审report-formatter按模板输出业务报表用户要周报、月报、专题分析insight-extractor从数据结果提炼业务结论用户给出数据要求解读每个技能只干一件事但组合起来就是一条完整链路explorer 查结构reviewer 保证查询质量formatter 统一交付格式extractor 做最后的价值提炼。这就是第 4 节说的分层封装在更大尺度上的复用。6.2 给 Skills 建用例测试集跑回归技能包也会随着业务调整而演化改一版 SKILL.md 会不会影响已有功能的稳定性我的做法是建一个技能测试集——把一个技能最典型的 10 到 20 个用户请求存成一个 Markdown 文件每次改完技能跑一遍看看响应是否还符合预期。这个测试集可以是单独的对话脚本也可以写个小脚本把测试用例分批丢给 Claude然后人工抽查质量。重点不是自动化而是回归意识——不要以为改了几行字就完事了模型行为是概率性的改一处可能牵动十处。有了固定用例集你就能对比修改前后的输出质量做出有依据的取舍。我在更新 sql-reviewer 技能时就吃过亏加了一条禁止输出 SELECT * 的报告规则结果所有输出都变成了先警告一句再给重写连明确的SELECT id, name这种安全查询也被警告了。因为描述写的是禁止输出裸的 SELECT *模型把它理解成了报告中要提这个风险。后来改成仅在风险等级为高时提及 SELECT * 问题回归用例才通过。用例测试集帮我在上线前发现并修正了这类语义偏差。6.3 和版本控制配合让技能包随项目一起演进技能文件本质上是文本天然适合纳入版本控制。我把全局技能里跟项目相关的部分也做了符号链接到项目仓库里和代码一起提交。每次业务迭代SKILL.md 跟着更新整个团队拉下来就能用同一套规则。团队协作时建议在 SKILL.md 里写明本技能的适用范围和最后更新日期避免一个人改了规则其他人还在用旧逻辑。另外 assets 目录里的参考资料也要一并纳入版本管理比如业务口径文档、SQL 风格指南这些是技能的知识库和代码一样需要持续维护。一个人维护技能包的时候很容易陷入写完就忘的状态。我的习惯是每个月花半小时过一遍所有技能哪些描述还管用、哪些流程已经不符合现状、哪些用例建议重写。技能包不是一锤子买卖它是跟着你的工作节奏一起长出来的。这套东西用顺了你会发现自己跟 AI 的协作方式完全变了——不再是一个问题配一段提示词而是一套标准流程一次配置长久受益。最后分享一个我个人的小经验一开始不要贪多选一个你每周都做的重复性任务把它做成第一个技能包用两周时间打磨 description、流程、模板和自检。试过一两轮你自然就能体会到给 AI 装岗位说明书和临场写提示词之间的差距了。等技能包积累五六个你会明显感觉到 AI 的交付稳定性和复用性上了一整个台阶。
阅读完成 · 觉得有帮助？
