做了这么多年的Agent应用我慢慢发现一个很尴尬的事情真正让AI干活效率翻倍的往往不是那个大模型本身有多聪明而是你往它手里塞了多少“趁手的工具”和“清晰的作业指导书”。这两年我反复折腾下来最核心的复用单元早就不再是某段代码或者某个Prompt模板而是一个叫“Skill”的东西——把提示词、脚本、校验逻辑、依赖关系打包成一个黑盒让模型拿到就能用。这篇文章我就把自己从零搭建和沉淀Skill体系的过程、踩过的坑、以及最后摸索出来的一套标准化写法完整拆开讲一讲。如果你正在做Agent开发、智能工作流或者只是想把自己常用的AI会话模板升级成可复用的能力包这篇应该能帮你省下不少弯路。1. Skills的本质不是Prompt而是给模型的“作业规程”先说一个很多人没绕过来的弯Skill不是一段写得更好的Prompt。Prompt是给模型的一句话、一段指令Skill是一个完整的工作包里面装着这个任务被拆解后的全部执行要素——怎么做、按什么顺序做、做错了怎么兜底、做到什么标准才算完。类比一下Prompt相当于你口头跟实习生说“帮我把这堆资料整理成报告”而Skill则是你把公司的报告模板、排版规范、数据来源名单、历史案例、交叉核对流程全部打包成一个文件夹交给他。哪个产出更稳定不用我多说。1.1 为什么传统Prompt工程会失灵接触过Agent开发的朋友应该都有体会同一个Prompt换个模型换套表现同一个需求稍微加两句描述输出结构就可能飘了。原因在于Prompt本质上是在模型的高度不确定空间里“捞”答案你只能约束它怎么回答很难约束它怎么思考、调什么工具、按什么顺序处理。我早期做自动化内容整理时用一套精心调过的长Prompt让模型帮我做资料汇总测试时效果惊艳一上真实数据就翻车。后来排查了半天发现问题出在Prompt里要求的步骤模型偶尔会跳过让它调用的工具函数它有时候会“忘记”传参格式对输出格式的约束模型可能在前半段遵守、后半段放飞。这不是模型蠢而是Prompt这种形式本身就缺乏结构约束力。1.2 Skill补上了“结构化执行”这块短板Skill的核心思路是把任务执行从“一段文字描述”升级为“信息架构脚本逻辑校验反馈”的组合。在这个体系里模型角色的定位也从“被自然语言指挥的生成器”变成了“按照既定规范调用资源、执行步骤的操作员”。模型的自由度被刻意收敛换来的是执行结果的稳定性。我自己搭的Agents-for-Dev框架里每个Skill文件夹都包含SKILL.md给模型看的“作业规程”写清楚任务目标、执行步骤、注意事项scripts/可调用的工具脚本模型遇到具体计算、文本处理时直接调用不靠想象assets/参考资料模板比如报告样例、代码片段库tests/验证脚本用于在模型执行前校验参数格式执行后校验输出完整性。这个结构的好处是把“想”和“做”分开。模型负责根据SKILL.md规划执行路径脚本负责具体且确定性高的计算校验逻辑负责确保每一步没有偏离轨道。这个思路后来我看了Anthropic的官方Agent Skills文档发现方向是完全一致的——业界在往同一个范式收敛。2. 拆开一个Skill看内部结构2.1 目录规范是地基建议照抄我前后重构了四轮Skill目录结构踩了不少Layout的坑最后沉淀下来的这版是最稳的强烈建议新项目直接照这套来my-skill/ ├── SKILL.md # 核心指令文件模型必读 ├── scripts/ # 工具脚本存放目录Python/Shell/JS均可 │ ├── preprocess.py # 执行前置处理 │ ├── calculator.py # 计算逻辑 │ └── verify_output.py # 结果校验 ├── assets/ # 静态资源参考样例、模板 │ ├── sample_report.md │ └── style_guide.txt ├── requirements.txt # Python依赖清单若有 └── tests/ └── test_skill.py # 离线自测脚本说几个关键点SKILL.md必须是技能目录下的说明书Agent运行时会自动读取脚本目录建议全部用相对路径引用避免部署到不同环境时路径漂移requirements.txt要写全别让模型自己猜“缺哪个装哪个”——一个不自包含的Skill换个机器就废了一半。2.2 SKILL.md的正确写法结构化指令的五个要素SKILL.md不是写作文它更像一份操作SOP。我根据实际效果总结了五个必须写清楚的部分任务边界这个Skill负责什么、不负责什么。不用写“你可以做”而写“你只做”。前置条件调用前需要哪些输入、输入大概长什么样。要有示例Model照葫芦画瓢最稳。执行步骤按编号列出处理流程。尽量控制在3~7步超过7步说明拆得不够细模型容易在中途丢失目标。校验与纠错执行完怎么自查哪种情况需要回滚重试。把这个写清楚能省掉你大量排错时间。输出格式给出明确的模板或结构能给出JSON Schema就绝不写“自由发挥”。我自己踩过的坑是早期写SKILL.md只写步骤不写校验结果模型在脚本执行失败时“硬编”一个结果回来数据错得离谱但表面看不出问题。后来在SKILL.md里显式加了一条“若任何脚本返回非零退出码必须停止执行并报告错误”这种幻觉倾向立刻被压住了。2.3 脚本逻辑模型负责规划脚本负责精确在Skill体系里脚本承担的角色是“确定性执行器”。凡是涉及精确计算、文本切割、数据格式转换的都要靠脚本不能指望模型做这些事。核心原则是模型负责在模糊的环境里做决策脚本负责在明确的边界里做执行。举一个我在会议纪要场景里真实用过的例子模型读完一小时会议录音的转写文本需要生成结构化纪要。第一步我不能让模型直接“凭感觉”总结重点——而是先由脚本做文本分句、去重、分段并统计每段时间跨度第二步模型拿到预处理后的结构化文本再按SKILL.md里的模板生成纪要素材第三步另一个脚本检查输出中是否包含“行动项”“负责人”“截止日期”三个必填区块缺了就自动打回重试。这个过程里模型做的事是理解和表达脚本做的事是处理和校验。各干各擅长的错误率直接下降一个量级。3. Skill的核心设计方法论让模型“想对”再“做对”3.1 三层解耦意图识别、执行规划、工具调用我自己在实践中悟出的Skill设计核心是三层职责必须解耦清楚意图识别层模型判断输入数据属于哪类任务对应哪个Skill。这层可以理解为“路由”。执行规划层模型根据SKILL.md规划先做什么、后做什么、每一步需要哪些脚本。工具调用层脚本真正执行产生确定性的输出再交回模型做后续步骤。很多效果不稳的Agent问题恰恰出在这三层搅在一起。比如模型在判断完意图后直接“想当然”地自己生成结果而不是走规划好的脚本通道。我在每个SKILL.md里都会显式注明注意如果本技能包含scripts目录则核心数据处理必须调用对应脚本执行不得由模型直接计算或推测。这行字看似普通实际是我调了无数次之后才加上的——模型的“过度自信”是排第一位的效果杀手。3.2 任务拆解把大任务拆成“感知-执行-验证”循环一个完整Skill的内在执行循环应当是这个模式感知读取输入解析关键字段判断输入的完整性执行调用脚本或执行步骤生成中间结果验证校验中间结果是否合规若不合规则回到执行环节修正输出全部验证通过后生成最终交付物。这个循环至少要在SKILL.md里写清楚“感知什么”“怎么执行”“验证标准是什么”。标准不能模棱两可比如“验证报告是否完整”就不合格要写成“验证报告是否包含摘要、分析、结论三个章节且每章节不少于200字”。3.3 状态与记忆给多轮任务搭好上下文传递如果Skill应对的是多阶段任务要注意状态管理。我通常会在assets/下放一个state_store.json模板每个阶段执行完后脚本把关键中间结果和当前状态写入这个文件。Agent从文件中读取进度决定下一阶段怎么走。这里有个很反直觉的经验不要试图在模型对话上下文里维护状态。模型上下文是概率性的第一步输出的信息第二步可能就被“稀释”了。把状态交给文件系统或内存对象去维护模型只负责按状态执行下一步稳定性会大幅提升。4. 实操从零构建一个“会议纪要处理”Skill4.1 先写执行流程设计再写代码直接写代码必翻车。我一般先拿纸笔画出执行流程明确每一步的输入输出。以会议纪要Skill为例核心流程是原始转写文本 → 脚本preprocess.py分句、去重、分段、时间戳清洗 → 模型根据段落内容提炼议题、结论、行动项 → 脚本format_md.py按模板生成Markdown纪要 → 脚本verify_output.py检查必填区块 → 输出完整会议纪要如果你刚接触我特别建议把这个流程做成注释写在SKILL.md的开头让模型每次“开场”前先看到流程图。虽然模型不具备真正的视觉理解但文本流程图能帮它建立执行顺序。4.2 SKILL.md的完整示例下面是一个我反复打磨过的SKILL.md骨架你可以直接抄去改--- name: meeting_minutes description: 根据会议转写文本生成结构化会议纪要包含议题、结论、行动项。 version: 1.2.0 --- # 会议纪要Skill ## 任务边界 本Skill仅处理会议转写文本txt不处理视频/音频文件。 ## 输入要求 - 输入为单段文本长度不少于500字 - 如果输入内容为空或明显与会议无关直接回复“输入无效”。 ## 执行步骤 1. 调用 scripts/preprocess.py 对输入文本进行清洗与分段 2. 基于清洗后的分段结果提取议题、讨论要点、结论 3. 调用 scripts/format_md.py将提取结果按模板输出为Markdown 4. 调用 scripts/verify_output.py 对输出进行校验 5. 若校验失败回到步骤2重新生成最多重试2次。 ## 输出格式 严格按以下Markdown结构输出 ### 议题 - 议题1 - 议题2 ### 结论 - 结论1 ### 行动项 - 行动项描述负责人截止日期4.3 关键脚本preprocess与verify预处理脚本的核心目的是把模型从“读脏文本”的负担中解放出来。比如转写文本里常见的“嗯”“啊”垫词、重复片段、时间戳脚本先过滤掉模型拿到的就是相对干净的段落它的概括质量自然更高。示例preprocess.py核心逻辑import re import sys def clean_transcript(raw_text: str) - str: lines raw_text.splitlines() cleaned [] prev for line in lines: # 去掉常见垫词和无意义符号 line re.sub(r\[.*?\], , line) line re.sub(r\b(嗯|啊|呃|然后)\b, , line) line line.strip() # 去重连续相同内容只留一条 if line and line ! prev: cleaned.append(line) prev line return \n.join(cleaned) if __name__ __main__: input_text sys.stdin.read() print(clean_transcript(input_text))校验脚本则用来“把关”。我会在verify_output.py里写好三个核心区块的检查是否存在“议题”“结论”“行动项”行动项是否含负责人和日期输出总长度是否合理。一旦校验不过返回非零退出码模型就能立刻感知到处理失败并触发重试逻辑。4.4 调用效果实测我用一套包含12个结构不同的会议转写测试集跑了一遍在加入完整Skill体系前模型直接总结的结果格式漂移率约40%按Skill流程跑完后格式合规率几乎100%内容漏项率从25%降到大概2%。这里的数据差别主要来自验证脚本的强约束——它能在输出发布前抓住系统性错误而不是等用户看完才发现问题。5. 生态与分发让Skill像乐高块一样可复用5.1 社区生态现状现在社区里已经出现了一些专门的Skills仓库和分享平台比如Anthropic官方维护的开源Skills示例库以及OpenSkills这类社区驱动仓库里面覆盖了PPT生成、Excel分析、自动化测试、报告撰写等高频场景。这些仓库最大的价值不是让你“下载后直接能用”——而是通过阅读别人设计的SKILL.md能快速提升自己的设计感觉。我的建议是先精读5~8个高质量Skill总结它们的步骤拆解、校验设计、输出模板规律然后照着框架自己重构一两个。直接搬过来的Skill往往水土不服因为你手头的Agent框架、模型能力基线、数据形态都不一样。但结构框架是通用的这才是社区仓库最值钱的部分。5.2 自建Skill的版本管理做了一段时间后你会发现Skill也和代码一样需要版本管理。我目前用一套轻量方案每个Skill目录在Git仓库里独立子目录维护修改SKILL.md时同步更新版本号我用的是version字段如v1.2.0每改一版都要跑一次内置test_skill.py把回归数据都过一遍确保改动不引入新问题。这个习惯帮我挡掉了好多次“改了A坏了B”的意外比靠脑子记住哪里改过靠谱得多。6. 常见问题与排查技巧实录6.1 模型不按SKILL.md执行怎么办这是最高频的问题。通常原因不是模型笨而是SKILL.md写得不够“强制”。排查路径检查SKILL.md开头是否清楚定义了任务边界和唯一目标别让模型产生多条执行路径的选择空间检查有没有“若……则……”的强分支要求模型倾向走阻力最小的路径因此要写明“必须”而不是“可以”确认Agent框架是否开启了“强制读取SKILL.md”的选项有些框架默认只在系统提示词里轻描淡写带一句效果约等于没写。6.2 脚本调用的路径或参数总出错大概率是路径和参数规范问题。我早期在Skill里调用脚本时直接写死“python3 scripts/preprocess.py”换一台部署机器就崩。后来统一改为SKILL_ROOT$(cd $(dirname ${BASH_SOURCE[0]}) pwd) python3 $SKILL_ROOT/scripts/preprocess.py此外所有命令行参数必须在SKILL.md里以参数表形式写清默认值、类型、含义三个字段缺一不可。模型读懂了参数表调用成功率会显著提升。6.3 模型的“幻觉式”输出可能无法被脚本识别如果模型生成了看似合理、实则错误的内容并且校验脚本没有捕获这通常是校验规则设计过于宽松。解决办法是给校验逻辑加“反幻觉钩子”比如在所有输出必须引用输入段落的原始文本作为依据生成结果里凡是输入中不存在的事实信息一律标记为“需人工确认”而不是默认正确。这类约束写进SKILL.md后模型会从“自由发挥模式”切换为“忠实转述标注模式”幻觉大幅减少。6.4 多Skill并发使用时的依赖冲突一个Agent项目往往同时加载多个SkillSkill之间可能存在依赖冲突。比如两个Skill都要用requests库的相同路径、或者对同一输入格式有相反假设。解决思路是做隔离给每个Skill配备独立的Python虚拟环境venv或者用容器化跑脚本至少也要在目录里注明“兼容的环境版本”避免Agent随机选一个导致运行崩溃。我自己的习惯是给每个Skill配requirements.txt且锁版本号避免“A Skill要requests 2.28B Skill要requests 2.31”的冲突。6.5 一个特别隐蔽的坑SKILL.md被模型当成输出内容你以为模型读Skill文档是“获取指令”实际有些模型会把这套文档当成“参考素材”甚至在输出时直接抄SKILL.md里的原文。应对方法是在指令开头写明“本文件为操作手册所有内容仅用于指导操作不得出现在最终输出中”。这行字不起眼但能干掉一大类格式漂移问题。7. 谈一点个人沉淀心得做Skill体系到现在最大的体会是真正值钱的不是那几行脚本而是你对任务流程的理解被“固化”成了可复用的规范。脚本谁都会写但能把“怎么做、按什么顺序、如何自查、如何兜底”完整沉淀成一个人机都能读懂的执行包这件事本身就很有门槛。我也犯过很多错误——早期把SKILL.md写成超长说明书结果模型抓不住重点后来写成过于精简的流程图又丢失了校验反馈细节。最终找到的平衡点是结构固定、段落精炼、验证规则显式写死、示例跟着每个关键步骤走。一句话总结就是“让模型把你当项目经理而不是当搜索引擎”。最后再分享一个实际技巧每次给Skill增加新能力时一定要顺手补一条回归测试用例哪怕只是跑一个最小样例。看似多花五分钟却在长期维护中帮你避免无数个“昨天还能用今天突然挂了”的尴尬。Skill体系的威力恰恰是在一次次的增量迭代和稳健维护中慢慢积累出来的。