开始之前先说清楚这个skills到底是什么如果你最近在技术社区逛大概率会看到一堆人在聊skills。这个标签底下说的不是求职简历上写的那些技能而是2025年AI Agent圈子里最火的一种能力封装方式——Skills。简单讲它是给AI模型配技能包的标准做法一个文件夹里放一份指令说明SKILL.md 配套脚本、模板、参考文档让AI在需要的时候自动调用按预设流程完成具体任务而不是每次靠你临时写一大段提示词去教它。这门技术适合谁三类人第一类是重度使用AI写代码、写文档、做数据分析的人想让AI的输出更稳定、更可控第二类是正在做Agent类产品的开发者想把复杂业务流程沉淀成可复用的模块第三类是刚接触AI的新手哪怕不会写代码也能通过配置技能包让AI帮你做RSS摘要、周报汇总、PPT大纲这类重复劳动。下面我把自己折腾Skills这段时间的完整记录整理出来从设计思路到踩坑细节都有你可以直接照着抄作业。1. Skills的定位与核心设计逻辑1.1 为什么我们需要Skills从裸奔到套件的进化先说一个最直观的问题没有Skills的时候用AI做一件正经事是什么体验你打开对话框告诉它你是资深数据分析师请帮我看一下这个CSV注意处理空值异常值标注一下最后输出一个带结论的摘要。这就是裸奔式使用。一次两次还好一旦你要它每天固定做这件事麻烦就来了你得把同样一番话复制粘贴一遍稍微复杂一点的流程提示词写上大几百字上下文都被它挤占了换一个项目又要重新教没有沉淀。Skills的厉害之处就是把这些提示词配套工具模板打包成一个独立模块让AI按需加载。用得最多的是Claude生态里的Skills功能但思路是通用的你给AI一个技能包它接到任务时先自动读取技能包的说明书知道自己该按什么流程走、有哪些工具可以用、输出格式是怎样的然后一步步执行。我拿现实中的岗位对比一下。一家公司招一个内容运营不会把工作内容全都写在一张便利贴上贴在工位上而是给一份岗位说明书外加各种流程文档、工具权限。Skills就是给AI的岗位说明书工具箱。这个类比基本精确。1.2 Skills、MCP与Function Calling三者的分工刚接触这个领域的人容易把Skills和MCP、Function Calling搞混。我实际用下来的理解是这样Function Calling是让AI学会调用函数的底层机制解决的是怎么把AI的意图转成结构化调用MCPModel Context Protocol解决的是AI怎么接入外部数据源和工具生态的标准化协议相当于给AI开了很多条API通道Skills则更高一层它解决的是AI面对一个完整任务时如何知道该按什么流程走、用什么资源、产出什么格式。三者的关系我用一个例子说明白。如果你让AI帮我把今早的新闻汇总成简报Function Calling负责让AI调用抓取新闻这个函数MCP负责提供新闻源的数据通道Skills负责在AI一开始接到任务时告诉它先抓RSS然后去重按科技/财经/生活分类最后按模板输出简报超过50条要二次筛选。换句话说MCP和Function Calling管的是手和脚Skills管的是大脑的操作规范。它不替代另外两个而是和它们协作。实际上很多复杂Skills里既有MCP工具调用也有本地脚本执行。维度SkillsMCPFunction Calling核心职责任务流程与人设封装工具与数据源接入标准意图转函数调用粒度完整业务流程单个工具/服务能力单个函数典型载体SKILL.md 资源文件夹MCP ServerAPI接口定义类比岗位说明书后勤管道特种兵的手脚2. 一个标准技能包的文件结构与SKILL.md编写要点2.1 技能包的文件结构先看骨架再填肉一个标准的skill文件结构类似这样my-skill/ ├── SKILL.md # 技能包的主说明文件必填 ├── scripts/ # 可执行脚本或代码片段 │ ├── fetch_data.py │ └── analyze.py ├── templates/ # 输出模板让结果有稳定格式 │ └── report_template.md └── references/ # 参考资料、领域知识、标注规范 └── style_guide.md核心就是SKILL.md。AI接到任务后首先会读它然后根据里面的指引决定下一步动作。scripts、templates、references这三个目录不是必需品但实际工程中基本都会用到。我的建议是凡是有固定逻辑的操作尽量沉淀成脚本凡是输出频繁的内容尽量给模板这样AI的发挥空间被限定在填充数据而不是自由创作格式稳定性会高很多。2.2 SKILL.md的核心字段与写法细节一份合格的SKILL.md头部是YAML格式的frontmatter正文是执行指令。最基本的头部长这样--- name: rss_digest description: 当用户需要生成RSS新闻摘要、日报或资讯汇总时使用。支持多源抓取、按主题分类和自定义简报输出。 ---name字段别乱起建议和技能包目录名保持一致方便管理和追踪。description字段是整个技能包最容易被低估的部分——它决定了AI什么时候会想起来用这个技能。写得过于宽泛AI会在不合适的场景下乱触发写得过于具体该触发的时候又漏掉。一个比较好的写法是当用户需要XXX时使用然后补一句支持XXX、XXX作为能力边界。正文部分我踩过几个坑之后总结出比较可靠的写法框架说明目标用一两句话说清这个技能是干什么的达到什么效果定义输入明确任务启动时AI需要从用户那里获取哪些信息如果缺信息该怎么处理列出执行步骤这是核心按顺序写清流程。注意是步骤不是套路要写清楚每一步的输入输出和判定条件给出约束明确哪些事不能做、哪些数据不可信、哪些情况要停下来请示规定输出格式直接指向templates里的模板或给出输出结构示例一个容易被忽略的点是失败分支。很多人写SKILL.md只写顺路流程遇到异常情况AI就开始自由发挥。我会在指令里明确写第一步失败\u2192尝试备用方案备用方案失败\u2192停止并报告错误原因。这一步看似简单但能明显减少AI一本正经地瞎编的概率。2.3 编写SKILL.md的两种风格命令式与引导式我见过的SKILL.md写法大致分两派命令派和引导派。命令派的写法像操作规程第一步执行fetch_data.py第二步读JSON第三步按模板输出。 优点是执行路径清晰适合流程固定的场景比如定时任务、数据清洗、格式转换。缺点是不灵活用户需求稍微偏一点就容易翻车。引导派的写法像教练辅导根据用户提供的材料首先判断类型然后选择合适的分析方法注意结论必须有数据支撑。 优点是灵活适合内容创作、咨询、分析这类开放任务。缺点是稳定性差面对不同输入可能跑偏。我自己的习惯是混合式关键路径用命令锁定分支和判断部分用引导。比如RSS摘要技能里抓取→去重→分类→输出用命令式写死但哪些新闻重要、如何排序用引导式给几条原则让AI自己把握。3. 实操记录从零做一个人力资源周报自动生成Skill3.1 需求定稿与技能包规划先说背景。我每周要整理一份人力资源领域的行业周报包括政策动态、头部公司人事变动、招聘趋势、技术工具更新四个板块。以前是周五下午手动收集信息再写成文档每次折腾两三个小时。这个任务很适合做成Skill。目标是AI根据我指定的一批RSS源和相关网站链接拉取一周内的文章过滤掉无关内容按四个板块分类生成一份结构完整、带来源链接的周报Markdown。注意这里我不让AI写评论分析只要事实摘要和来源避免它脑补。技能包规划如下hr-weekly-digest/ ├── SKILL.md ├── scripts/ │ ├── fetch_feeds.py # 抓取RSS源并清洗数据 │ └── dedupe_cluster.py # 去重简单分类标签 ├── templates/ │ └── weekly_report.md # 周报输出模板 └── references/ └── source_list.md # 维护RSS源清单和权重其中source_list.md是我个人维护的记录了20多个HR相关的RSS源每个源配了主题标签和权重。这样AI在排序摘要的时候有据可依而不是全凭自己觉得哪个重要。3.2 手写SKILL.md关键路径写死口味判断靠引导我写完第一版后改了三次最终版长这样精简展示--- name: hr_weekly_digest description: 每周人力资源行业周报自动生成。根据用户指定的信息源列表抓取过去7天的更新按政策动态、企业人事、招聘趋势、HR工具四个板块整理摘要。适用于周报、行业观察、竞品情报收集。 --- # hr_weekly_digest 技能说明 ## 目标 生成一份按四板块分类、带来源链接、总长度不超过1500字的人力资源行业周报。 ## 输入 - 用户提供时间范围默认最近7天。 - 默认读取 references/source_list.md 获取信息源如需临时增加来源可让用户补充URL。 ## 执行步骤 1. 运行 python3 scripts/fetch_feeds.py --days 7 --sources references/source_list.md。 2. 脚本输出JSON到临时文件内容是每篇文章的标题、URL、摘要、发布时间、来源、主题标签。 3. 运行 python3 scripts/dedupe_cluster.py --input json --output json 去重、合并相似文章、按板块归类。 4. 如果某个板块文章数为0保留板块标题并标注“本周暂无重点内容”不要自行编造条目。 5. 使用 templates/weekly_report.md 作为输出格式填充每个板块的条目。 ## 约束 - 不写个人观点不做趋势预测。 - 每篇文章摘要不超过两句话直接使用原文摘要或手动改写不补充原文没有的信息。 - 按 source_list.md 中的优先级字段排序同板块内高权重来源排前面。 ## 输出格式 严格按照 templates/weekly_report.md 填充输出Markdown禁止输出TXT或纯文本。有几个细节我说一下为什么这么写。第一每个板块文章数为0要保留标题并标注不要编造这条约束是从第一次翻车中总结的。当时AI发现HR工具板块没内容居然自己写了三行近期HR工具领域没有重大突破——这种话看着像陈述其实就是瞎编。加了约束之后它只会老实标注。第二第2步明确脚本输出JSON到临时文件第3步再读。一开始我试图让脚本直接返回文本给AI绕一圈发现容易乱。让AI直面结构化JSON反而更好。AI读JSON做二次分类我去重比脚本里硬编码规则灵活得多。第三不写个人观点不做趋势预测听起来有点死板但这份周报的定位就是信息汇编事实摘要比华丽评述有价值。3.3 配套脚本怎么写实用优先别过度设计fetch_feeds.py的核心逻辑不复杂遍历source_list.md里的RSS源用feedparser去解析把每篇文章的时间、标题、链接、摘要取出来按天数过滤最后导出JSON。一个关键设计点脚本里不做深度分类。分类这种智能活留给AI脚本只做脏活——抓取、时间过滤、去重。原因很简单脚本规则再聪明也赶不上AI对语义的理解。所以dedupe_cluster.py我只做了两件事一是按标题编辑距离URL归一化去重二是打上粗粒度主题标签作为给AI的初步建议。另外提一句依赖管理。这个脚本用了feedparser和jieba两个第三方库我在SKILL.md的步骤1里加了一行说明如果运行失败提示缺少依赖先执行 pip install feedparser jieba。买保险永远不嫌多。templates/weekly_report.md的设计是每个技能包的脸面。模板我写成这样# 人力资源行业周报{week_range} ## 一、政策动态 {items} - **{title}**{summary}{source} | {link} ## 二、企业人事 ... ## 三、招聘趋势 ... ## 四、HR工具 ... --- 生成时间{date} | 信息源数量{source_count} | 文章总数{total_count}模板信息密度很高AI只需要往里填数据不会跑偏。括号里的变量是给AI看的占位符实际输出替换成具体内容。4. 调试思路与常见问题排查记录4.1 我测试技能包的五个步骤技能包写完不等于能直接用。我每次做新技能都会走一遍这五步第一步独立验证脚本。先不管SKILL.md单独在命令行跑脚本确认输出JSON格式没问题、字段都对。这一步排除了最大的隐性风险。第二步单发任务测试。把SKILL.md配置好给AI一个最小测试任务观察它是否识别出并使用了技能包。这里主要看两点description触没触发对执行顺序跑没跑偏。第三步设计刁钻输入测试。比如给一个没有内容的空源或者给一个突发新闻要求临时增加来源看看AI的异常处理逻辑是否生效。我通常会准备三个正常case、两个边界case一次性跑完。第四步观察上下文占用。同一段对话里连续跑多个任务看AI会不会把整个SKILL.md内容反复读取、挤占可用上下文。正常情况技能包只在任务开始时被读取一次。第五步回归测试。新版本改完旧功能别退化了。我会把之前测过的用例重新跑一遍。这个习惯救过我很多次改分类逻辑的时候把正常流程跑挂了是常有的事。4.2 高频问题与排查方案速查表问题可能原因排查与解决办法AI完全没有触发技能包description范围过窄或关键词不匹配打开SKILL.md检查description看用户原始输入是否命中触发条件扩大到周报、日报、汇总、信息整理等技能包触发了但执行顺序乱跳SKILL.md执行步骤写得不够强制把步骤编号改为第一步/第二步而这种强引导并在步骤间加上在上一步结果基础上继续的衔接句AI输出了模板外的格式没有在输出格式部分强调必须在输出格式开头写明严格使用templates下的模板字段顺序不可调整不缺项脚本报错但AI直接忽略指令中没有写错误处理分支补上脚本运行失败时输出错误截图并终止任务不要继续推测文章摘要出现原文没有的内容约束里没禁止补充加约束摘要必须源自原文不得自行扩展或推测技能包内容反复读取导致上下文爆炸指令冗余内容太多精简SKILL.md把长段落移到references目录正文只留执行要点4.3 排除过程中的一个典型案例一次跑hr_weekly_digestAI执行完第1步后没有直接去第3步而是自作主张开始分析最新政策方向输出了一段三百字的趋势评论。我排查发现是SKILL.md里目标描述里面有识别本周值得关注的变化这句话被AI理解成需要输出分析。解决方式是把关注变化改成将相关内容归类到对应板块并且把不评论不预测的约束提到了目标段落的前面。这类问题很值得拿出来多说一句SKILL.md里每一句话都可能被AI过度解读。写技能说明边界比引导重要禁止项比建议项重要。宁可让AI少做一点也别让它多做一点。5. 我对Skills的几点实操心得在断断续续折腾了三个月Skills之后几个体会比较深。第一技能包的维护成本比你想象得高。源清单要更新、脚本依赖要升级、模板要随业务调整SKILL.md要跟着一起改。把它当成一个真正的开源小项目来维护用git管理版本每一次修改都写清楚commit信息回头排查问题会省很多事。第二写SKILL.md时反向思考特别重要。别只写你要做什么更要写你不能做什么。AI的联想能力强到可怕你少写一个不它就能给你多发挥出来三个创意。这个教训我交了不止一次学费。第三设计技能包时优先考虑能不能让AI自己维护自己。最近我在实验一种做法在references目录里放一份技能包自检清单.md里面写清触发条件、输出标准、常见错误然后让AI每个月跑一次自检检查SKILL.md是否还能正常工作。AI自己指出的问题往往比人一眼扫过去更精准。第四任何在线的AI功能都可能更新换代但结构化技能包这件事的价值是长期的。你沉淀下来的流程、脚本、模板就算底层模型换了迁移成本也不高。这可能是这段折腾中性价比最高的部分。最后分享一个具体的小技巧在做SKILL.md的时候在references目录里存一份示例输出完整样例文件。不用多一个真实场景跑出来的优秀输出就够。AI在不确定的地方会参照示例的格式和语言风格比自己看模板猜要准得多。这也是目前我自己实践下来最能提升输出稳定性的一个不起眼但见效的动作。