很多人拿到 Claude 之后第一反应是把它当成一个更聪明的聊天框丢一段代码进去让它改扔一篇文章进去让它总结。但用久了你会发现真正拉开效率差距的不是“问得好不好”而是 Claude 能不能在无人盯着的状态下自己完成一整条任务链。Claude Skills 就是干这个的——它不只是一个提示词模板而是一套把“技能”固化成文件、参数和脚本的运行机制让模型在需要的时候自动加载对应能力像给 AI 接上了手和工具。这篇指南我打算完全按实操来写不绕理论。我会从 Skills 的文件结构、运行机制讲起带你自己写一个能跑的 Skill然后重点讲调试思路和进阶优化。适合的人群是已经用过 Claude 但觉得“每次都要重新解释任务”很烦的开发者想把 AI 放进自动化流水线的效率党以及刚开始接触 Agent 机制、想搞清楚 Skills 和普通提示词到底有什么区别的同学。1. 先搞清楚 Skills 到底是什么文件、触发机制和三种工作模式我在刚接触 Skills 的时候犯过一个典型错误以为它就是把一段精心写好的提示词保存下来下次直接调用。实际上完全不是。Skills 是一套包含元信息、指令说明和可执行文件的完整单元Claude 会根据当前对话的上下文决定要不要加载这个 Skill、什么时候加载、加载之后怎么执行。1.1 一个 Skill 的基本构成SKILL.md 才是灵魂每个 Skill 本质上是一个目录里面至少有一个SKILL.md文件。这个文件用的是 Markdown 格式但它的作用不是给人看的文档而是给模型读的“操作手册”。模型在对话中被触发到相关场景时会主动去扫这个文件然后按照里面的步骤和约定来执行任务。目录结构大概长这样my-skill/ ├── SKILL.md ├── scripts/ │ └── process.py └── assets/ └── template.mdSKILL.md的开头有一段 YAML 格式的 frontmatter用来声明技能名、描述、适用场景。描述部分特别重要因为模型是靠描述来判断“当前这个任务要不要调用这个技能”的。描述写得越具体误触发的概率就越低。一个标准的SKILL.md长这样--- name: meeting_minutes description: 将会议录音转写文本整理为结构化会议纪要提取待办事项、决策结论和风险点。适用于含多人对话的会议记录场景。 metadata: version: 1.0.0 author: self tags: [meeting, minutes, productivity] ---后面的正文部分就是给模型的操作指令包括输入格式、处理步骤、输出模板。模型会严格按这个顺序执行。1.2 触发机制不是手动调用而是“按需加载”这是 Skills 最反直觉的地方你不需要告诉 Claude “现在请使用某某技能”。当你把 Skill 放进配置目录后Claude 会在每次对话中自己判断当前任务是否命中某个技能的描述如果命中就自动加载对应的SKILL.md并据此调整行为。我测试过一个很有意思的场景我在技能库里放了一个“代码审查”Skill然后故意用很口语的方式说“帮我看看这段代码有没有问题”。Claude 没有直接把代码读完就回答而是先加载了代码审查 Skill然后按照里面定义的检查清单一项一项过。输出结构明显更严谨而且给出的改进意见覆盖了安全性、可读性、性能三个维度——这三类正是我在 Skill 里写的检查项。这个机制的代价是模型每次都要做一次“要不要用技能”的判断。所以description字段写得好不好直接决定了判断准确率。写得太宽泛无关任务也会被套上技能模板写得太窄真正用得上的场景反而触发不了。1.3 三种类型Agent Skills、Workflow Skills 和 Person Skills官方对技能做了分类我实际用下来的体感差异非常明显类型核心定位典型场景运行特点Agent Skills给 Agent 扩充单项能力格式转换、特定格式抽取、调用内部脚本按需加载用完即走Workflow Skills串起整条流程“扫描收件箱→提取待办→写入任务清单→生成周报”多步骤编排状态流转Person Skills固定人设和输出风格法律文书审核、学术写作润色、客服回复风格化长期跟随对话影响整体语气Workflow Skills 是我个人最推荐优先试水的类型因为它的收益见效最快。比如我写过一个人力资源周报 Skill它能把一周里分散在邮件、聊天记录、文档评注里的零散更新自动汇总成一份有结构、有重点、有风险标注的周报草稿。以前这件事每周要花我四十分钟现在把材料丢进去五分钟出初稿我只需要做删改和确认。2. 手写第一个 Skill从会议纪要场景跑通全链路光说不练没有意义这一段我带你把一个真实的 Skill 从零写出来。选“会议纪要整理”这个场景因为它足够简单不需要接外部 API也不需要复杂的流程编排但又能完整展示 SKILL.md 编写、脚本编写和参数传递的全过程。2.1 先设计输入输出明确边界才能让模型不乱来写 Skill 之前我会先在一张纸上画清楚三件事输入是什么、输出是什么、处理步骤有几步。这个习惯帮我避免了很多回头改文件的麻烦。对于会议纪要这个场景我的设计是输入一段会议对话的原始转写文本通常含有多位说话人、口误、重复表达和插入语。输出一份 Markdown 格式的结构化纪要包含会议主题、时间、参会人、讨论要点、决策结论、待办事项清单。核心处理步骤清洗文本 → 区分发言人与话题 → 提取关键结论 → 归类待办 → 套用输出模板。这里有个很关键的设计决定我选择把“清洗文本”和“结构化抽取”交给模型完成而不是写一个 Python 脚本去处理。原因很简单——对话文本的非结构化程度太高靠正则和规则去抽“谁说了什么”很容易翻车而模型天然擅长这件事。脚本只负责最后的格式化输出和文件保存。2.2 SKILL.md 的正文怎么写才管用很多人以为 SKILL.md 的正文写得越详细越好其实不是。模型对超长指令的执行效果会衰减尤其是当指令里混入“背景说明”“原理讲解”“步骤定义”多层内容时模型容易抓不住重点。我的写法是四段式# 会议纪要整理 ## 你现在的任务 将用户提供的会议转写文本整理为结构化会议纪要。必须严格遵循下面的处理流程与输出格式禁止在未完成信息抽取前直接输出模板。 ## 处理步骤 1. 清理文本去除语气词、重复语句、打断性插入语。 2. 区分发言人为每个主要观点标注发言人代号。 3. 抽取关键信息用列表记录讨论主题、明确决策、遗留风险和所有待办项。 4. 按输出模板生成纪要保存为 Markdown 文件。 ## 输出格式 严格按照以下模板输出缺失信息填写“待确认” ...关键在于第 2 部分我用了显式顺序指令。研究发现模型对带编号的步骤执行准确率显著高于对非结构化描述的遵守程度。你让模型“先做什么再做什么”时尽量用数字序号把顺序锁死而不是用“然后”“接着”这种模糊连接词。2.3 用 Python 脚本兜底格式化让输出稳定可用模型自由发挥的 Markdown 格式每跑一次可能都不一样——有时用表格有时用列表有时待办事项不带 checkbox。为了让纪要能直接对接下游工具我在 Skill 目录里放了一个format.py专门负责把模型生成的原始 JSON 转成固定格式的文件。脚本大概长这样#!/usr/bin/env python3 Convert meeting data JSON to formatted markdown. import json import sys from datetime import datetime from pathlib import Path def main(): raw sys.stdin.read() data json.loads(raw) lines [] lines.append(f# 会议纪要{data.get(topic, 待确认)}) lines.append() lines.append(f- 时间{data.get(date, 待确认)}) lines.append(f- 参会人{, .join(data.get(attendees, [待确认]))}) lines.append() lines.append(## 讨论要点) for point in data.get(discussion, []): lines.append(f- [{point.get(speaker, 未知)}] {point.get(content, )}) lines.append(## 决策结论) for dec in data.get(decisions, []): lines.append(f- {dec}) lines.append(## 待办事项) for todo in data.get(todos, []): owner todo.get(owner, 未指定) desc todo.get(task, ) due todo.get(due, 未指定) lines.append(f- [ ] {desc}负责人{owner}截止{due}) output_path Path(_output) / fmeeting_minutes_{datetime.now():%Y%m%d_%H%M}.md output_path.parent.mkdir(exist_okTrue) output_path.write_text(\n.join(lines), encodingutf-8) print(output_path) if __name__ __main__: main()脚本读 stdin 的 JSON输出格式化 Markdown 文件。这样一来不管模型在中间步骤生成什么风格的内容最终落到磁盘上的纪要格式永远是统一的。2.4 端到端测试跑通一条完整输入链写完 Skill 之后我建议一定做一次完整的端到端测试不要只测脚本本身。把一段真实的会议转写文本丢给 Claude观察它是否自动加载了技能、有没有忠实地按步骤执行、最终文件格式是否符合预期。我测试用的转写文本故意注入了一些干扰项比如中途的寒暄、发言被打断后换话题、一个人说了半句被另一个人接走。第一次跑下来发现 Claude 把“待确认”项填成了“未知”而且有两条决议内容是从讨论要点里抄的没有真正判断“这是不是决议”。问题出在 SKILL.md 里“决策结论”的判定标准写得不够明确。我修改了描述加了一句判定规则“只有与会者明确达成一致、或主持人明确拍板的内容才归入决策结论其余归入讨论要点。”之后重新测试输出就符合预期了。3. 调试与避坑我踩过的那些让人抓狂的坑Skills 刚上手的时候最容易让人心态爆炸的不是写文件而是“明明文件写得很完整跑出来结果完全不是那么回事”。这里我把踩过的坑按类别整理出来每一条都附带排查思路希望能帮你少走弯路。3.1 坑一脚本路径问题——工作目录不是你想象的目录第一次写带脚本的 Skill 时我在SKILL.md里写了一句“运行 scripts/format.py”。结果 Claude 执行的时候报错找不到文件。排查了半天才发现模型执行命令时的当前工作目录可能不是你放 Skill 的那个目录而是项目根目录或者其他默认目录。解决方案有两个一是在脚本里用绝对路径定位自身位置二是SKILL.md里明确写清楚脚本路径的解析方式。我推荐前者因为更稳from pathlib import Path SCRIPT_DIR Path(__file__).resolve().parent这样无论从哪个目录调用脚本都能自己找到scripts/目录下的辅助文件。3.2 坑二输出格式描述太虚模型自由发挥一开始我在 SKILL.md 里写“请用清晰的格式输出”结果每次跑出来的东西风格都不一样有时候是表格有时候是分点列表。后来我学乖了直接把期望输出的 Markdown 模板写死并且让脚本去解析结构化的中间数据而不是让模型直接输出最终文件。模型只负责填 JSON 字段脚本负责渲染成 Markdown。这样既保住了模型的语言理解优势又锁死了最终格式。3.3 坑三模型把“技能”当“知识库”用有一次我写了一个包含大量背景资料的技能本意是希望 Claude 在回答该领域问题时引用这些资料。结果发现 Claude 加载技能后直接把资料内容复述给用户而没有做任何加工。原因是我在description里只写了“包含XX领域资料”没有写“这个技能的目标是辅助分析而非输出原始资料”。所以description 里必须写清楚调用边界description: 基于内置领域规范对用户提供的文本进行合规审查并输出风险清单。禁止脱离输入文本直接输出规范原文。3.4 完整排查链路一个“半截 JSON”的问题现场分享一次比较典型的排查过程。现象是Claude 读了我的 Skill 之后输出到一半停止了屏幕上出现了不完整的 JSON。我第一反应是“是不是上下文长度超限了”但缩短输入之后问题依旧。后面我做了一次分步验证。先在对话里直接问 Claude“你刚才执行这个技能的时候走到哪一步了”它给出的回答让我意识到问题不在上下文长度而是在第 2 步——它尝试把一段特别长的历史信息全部塞进 JSON 的“背景”字段然后把输出长度算错了最后决定截断。我当时的处置是修改 JSON schema给“背景”字段加上最大长度限制并让处理步骤先压缩文本再填入 JSON。改完之后同样长度的输入下之前的问题就消失了。这个排查过程让我认识到一个规律遇到问题不要盯着最后输出看先问模型“你执行到哪一步了”把那一步的动作抽出来看问题往往一目了然。3.5 调试工具与验证策略Debug Skills 时我常用的工具就三样Claude 的自解释能力直接问、一个inspect_logs.py脚本记录每次调用的入参和出参、以及一组固定输入测试用例。固定输入测试用例特别管用。我会准备 5 到 8 段不同特点的输入比如超短输入一句话、超长输入几千字、包含特殊字符、完全空输入、输入格式错误、内容涉敏感字等。每次改完 SKILL.md 或脚本就把这组用例整体跑一遍确认没有回归。4. 让几个 Skill 协作构建一个个人工作流系统单一 Skill 的威力有限真正改变效率的是把多个 Skill 组合成一个能自动流转的工作流。比如我可以把“会议纪要 Skill”“待办清单 Skill”“周报生成 Skill”串起来先整理会议纪要再自动提取待办到周五把这周的待办汇总成周报。每个环节各自是一个 Skill互不干扰又能互相输送数据。4.1 用统一的输出目录做笨办法的数据传递Skill 之间传递数据我见过最优雅的方案是某种“共享叙事记忆”机制但当前版本下我直接用文件系统来传每个 Skill 都往_output目录写入标准格式的文件下游 Skill 从同一个目录读取。笨但足够稳而且方便人工检查。我目前的技能库目录结构是这样的skills/ ├── meeting_minutes/ ├── todo_extractor/ ├── weekly_report/ └── _output/todo_extractor会自动扫描_output目录里的.md文件寻找含- [ ]的行然后汇总到当天日期的待办清单里。weekly_report再定时读取这一周的待办文件按项目分类生成周报。4.2 Skill 之间的描述约束避免互相踩踏多个 Skill 放在一起后模型可能会在同一个任务里同时加载好几个相关技能结果行为互相干扰。规避办法是在每个 Skill 的 description 里明确“本技能不负责什么”。这句话看起来多余实际上能大幅减少错误触发。例如会议纪要 Skill 的 description 我改成了description: 整理会议转写文本为结构化纪要。适用于会议记录场景不负责提取个人待办任务那是todo_extractor的职责。改完之后模型在两个技能边界上的判断明显稳了。4.3 用日志机制给工作流装上“黑匣子”几个 Skill 串起来跑的时候最怕的是中间某一步出了问题还不知道是哪一步。我的做法是每个脚本在运行后自动写一行日志到run.log包含时间戳、调用技能名、入参摘要、出参状态。这样每次跑完整条链只需看一遍日志就能快速定位断点。附上日志记录的简单实现import logging logging.basicConfig(filenamerun.log, levellogging.INFO, format%(asctime)s %(name)s %(levelname)s: %(message)s) logger logging.getLogger(todo_extractor) logger.info(开始扫描待办来源目录%s, output_dir)用这个方案维护几十个 Skill 的协作运行维护成本依然可以接受。核心体会是日志不用写得多复杂能定位到“哪个技能、哪一步、看到了什么输入、产出了什么输出”就完全够用。5. 进阶把 Skill 变成测试驱动的稳定工具以及它的边界在哪Skill 跑通容易跑稳很难。要让它稳定复现我建议引入一套简单的“测试驱动维护法”把每个 Skill 的预期输出样例保存为测试用例每次修改 SKILL.md 或脚本都跑一遍全部用例。这不复杂但能挡住九成以上的暗改回归。5.1 测试用例怎么写才有保护力测试用例不能只覆盖“正常输入”还得覆盖边界。以会议纪要 Skill 为例我的测试用例集至少包含用例输入预期输出正常会议多发言人有明确决议纪要包含决议项无决议会议全程讨论但未达成一致决策结论为“待确认”单句输入“今天到此为止”模板字段大部分为“待确认”超长输入3万字会议记录脚本正常输出文件不截断特殊字符含 emoji、乱码、多语言混排Markdown 渲染无错误我只花了半天时间把常用 10 个 Skill 的测试套件建好之后每次改动只需要跑一遍python -m pytest心里就有底。5.2 什么时候不要用 SkillSkill 不是银弹它擅长处理的是“有明确输入输出结构、有稳定流程、能写成文本指令”的任务。碰到下面几类情况就建议换思路需要实时访问外部 URL、API且返回数据格式动态变化 → 接 MCP 更合适Skills 不擅长处理高动态的实时数据流。需要和外部 GUI 程序交互、点按钮、读弹窗 → 目前指望不上 Skill。任务本身只是一次性问答不具备复用价值 → 写 Skill 属于过度设计。把适合 Skill 的场景和不适合的场景分清楚才能避免把时间花在“给一次性任务建永久管道”这种事上。5.3 一个重要取舍描述越精确触发越可靠但泛化能力越弱这是我很长一段时间没想通的点。早期我为了让 Skill 触发更稳把 description 写得非常精确结果发现稍微换一种说法模型就不认了。后来我做了个折中在描述里同时放“典型触发场景”和“边界排除场景”既能兜住常见说法又能挡住误触。举一个实例公文校对 Skill 的描述最初是description: 校对公文格式。改后为description: 对党政机关公文、通知、请示等文档进行格式与用语校对。典型输入包括红头文件、正式通知、申请文书等日常聊天、博客文章草稿不需要加载本技能。改完后同类任务的触发率明显上升同时聊闲天时不再频繁误加载。5.4 模型版本的差异Skill 能不能跑成很大程度上取决于模型的“读指令”能力同样的 SKILL.md放在不同模型上执行结果差别很大。性能强劲的模型能严格遵循多步骤指令而轻量模型经常会跳过步骤、简化输出。所以我现在的习惯是稍微复杂一点的 Skill只用强推理能力模型来跑简单格式转换类 Skill才考虑给轻量模型用。这一点也直接影响到工作流的选型思路——如果某个流程经常跑挂先别急着改 Skill先试试换一个更强的模型可能问题就自动消失了。说到底Claude Skills 的最佳实践没有太多玄学无非是把流程说清楚、把边界划清楚、把输出锁死。我在实际维护这套技能库的过程中最深的感受是每花一小时打磨描述和脚本都是在给自己省下来一周里无数个“重新解释一遍需求”的瞬间。这套机制真正的价值是让 AI 从“每次重新认识你”的聊天对象慢慢变成“越来越懂你习惯”的稳定协作者。