最近一个月“skills” 这个词在我关注的 AI 圈子里几乎刷屏了。GitHub 上各种 agent skills 仓库层出不穷Claude 和 Codex 也开始把技能能力提升到与工具同等重要的位置。跟很多朋友聊天大家已经从“怎么问大模型”切换到了“怎么给大模型配一套 superpower skills”。老实说我一开始也觉得这只是换了个说法直到自己动手开发并实际跑完几个技能包才明白Skills 本质上是在改变智能体的工作方式从每一次“随机发挥”变成有章法地调用成熟流程。这篇文章会拆解 Skills 的第一性原理讲清楚它跟 Prompt、插件、MCP Tool 的真正区别然后以“自动生成短视频分镜脚本”为例完整走一遍从设计、开发到测试的全过程最后把我在真实项目里踩过的坑和排查方法整理成速查表。无论你是做 agent 应用开发还是只想让 AI 助手更可靠这篇文章都值得花二十分钟读完。1. 先理解 Skills 到底解决了什么问题1.1 从 Prompt 到可复用能力的换算最早大家用大模型靠堆提示词每次都把上下文铺满。问题在于同样的任务重复十遍模型每次依然从头开始偶尔还会换一种完全不同的做法。Skills 的思路就很生活化人开车不会每次重新学交规和油门刹车而是调用已经固化的“驾驶技能”。AI 也一样把高频任务的做法、约束、工具调用封装成一个可挂载的能力单元需要时自动加载。就我的实测体验之前让 agent 写一个分镜脚本我需要把格式、景别、时长、镜头内容全部写在 prompt 里输出还不一定合规。把规则固化成 skill 之后描述里只需要一句话agent 会在任务匹配时自动翻开技能包输出的结构基本稳定连脚本都自动生成在项目目录下。这个体验的差异就是 skills 最大的价值。让我把这种演进拆一下普通对话是“拍脑袋”带工具的对话是“边查边做”而带 skills 的 agent 是“调用 SOP 做事”。三者对应的可靠性和可维护性完全不同。如果你还停留在每次手动写 prompt 的阶段你会发现当任务量变大时人会成为瓶颈agent 也会越来越不稳定。1.2 别再把 Skills 和插件、工具混为一谈我在群里经常看到有人把 skills、MCP tools、插件混着说这其实会带来设计上的混乱。简单区分Prompt 是一次性指令适合随机任务不需要沉淀。Plugin 往往是应用层面的功能扩展比如浏览器插件、IDE 插件绑定的是具体宿主。MCP Tool 是一个可调用的函数提供原子能力比如搜索、读文件智能体自己决定怎么用。Skills 则是一个更上层的“套餐”它能把多个工具、步骤、约束和示例打包成一套完整流程给智能体一个“面对这类任务时应该怎么做”的说明书。用做饭类比MCP Tool 是刀、锅、铲Skills 是川菜菜谱你告诉 AI“今晚想吃回锅肉”它翻到对应菜谱按步骤用工具完成。没有菜谱AI 也能做但每次味道都会跑偏。我以前踩过一个坑花了很多精力把各种 API 封装成 MCP 工具结果 agent 面对复杂的业务任务时依然不知道先做什么后做什么。后来补上 skills 这一层把“先调研、再定方案、最后写实现”的流程固化成技能整个输出质量一下子稳定了。两者不是替代关系而是分层协作。1.3 文本型、脚本型、资源型技能包的三种形态按内容载体我习惯把技能分成三类。第一类是纯文本型SKILL.md 里写清楚判断逻辑和输出模板适合生成文案、拟定提纲、做评审这一类任务。第二类是脚本型技能包携带 Python 或 Shell 脚本适合做文件处理、格式校验、批量转换这类需要确定性的操作。第三类是资源型技能包里放着模板、数据集、参考案例agent 根据任务选择合适的资源进行组合输出。实际项目中一个成熟的技能往往是三者的混合。比如我把“短视频分镜生成”做成脚本型但里面同时包含示例资源和校验脚本。理解这个分类的用处在于当你设计技能时可以问自己“这个任务的确定性部分在哪”把确定性部分交给脚本把灵活性部分交给自然语言指令这样的技能才不容易在边界条件下翻车。2. 设计核心细节好技能和烂技能只差几个关键点2.1 技能包的基本骨架目前主流 agent 技能市场里一个标准技能包通常长这样skills/ generate_shotlist/ SKILL.md scripts/ generator.py assets/ template.csv examples/ example_1.mdSKILL.md 是入口文件大模型在需要时主要读它里面包括三块技能说明即这个技能解决什么问题、什么时候不该用执行步骤即从输入到输出的操作流程越具体越好约束与示例包括格式要求、禁忌、一个或多个输入输出示例。scripts 里放可执行的脚本或工具。注意一点skills 不仅限于文本提示。它完全可以搭配 Python、Shell 脚本让 agent 自己调用脚本处理数据、生成文件最后返回结果。这样技能就从一个“话术说明书”升级成了“带自动化能力的流程包”。2.2 让技能在正确的时候被调用大多数平台的触发逻辑是先看全局描述再匹配当前任务。如果描述太宽泛比如“处理文案”那么几乎所有任务都会先想到它结果产生误调用描述太窄比如“计算某公司周报里的平均工时”技能又永远等不到出场。理想写法是给出适用场景、对象和预期产出同时明确不适用的情况。我自己在写技能描述的时候固定用这种结构功能定位一句话、适用输入、生成产物、不适用边界。例如“生成短视频分镜脚本根据选题文案输出包含景别、运镜、时长、台词和画面描述的分镜表不适用于长视频剪辑脚本和口播逐字稿。”这样模型在判断时就很清楚。另外很多 skill 支持在描述里列出触发关键词例如“分镜、脚本、短视频”。但不要完全依赖关键词因为模型的能力来自语义理解关键词只是辅助。我见过把几百个关键词硬塞进描述的技能反而挤压了指令和示例的空间触发率并没有显著提升。2.3 写执行步骤别做“规则狂热者”新手常犯的毛病是恨不能写一千条规则觉得规则越细越好。实测下来指令超过一定长度模型会选择性遗忘中段内容而且大量冗余指令会挤占上下文窗口。我的经验是步骤保持在 5-8 步每步只讲一个动作、一个判断、一个产出。能放进脚本计算的细节不要写进文字指令让代码处理确定性逻辑让自然语言处理决策逻辑。有一个细节很多人不知道技能里的脚本要假设路径是相对于技能包目录的不要写绝对路径。否则用户换机器、换项目后技能直接失效。我的做法是在脚本开头用Path(__file__).parent.parent定位到技能根目录再拼接相对路径这样整体可移植性会好很多。2.4 上下文成本管理每个技能在被调用时都会占用上下文窗口所以技能包不是越大越好。一个常见的错误是为了“稳妥”把所有背景知识都写进 SKILL.md结果 agent 连基础对话的上下文都被挤没了。我的建议是控制在几千字以内只保留框架性知识和必要的判断依据底层细节放进 assets 文件夹需要时再读取。还有一个容易被忽略的点技能之间要尽量避免互相引用。如果技能 A 的描述里强行塞进技能 B 的内容会让调用逻辑变得混乱排查问题时也很难定位。每个技能应该独立自洽就像模块化代码一样高内聚、低耦合。2.5 资源与安全边界如果技能包里带有脚本一定要考虑执行安全。我见过某个第三方技能会在运行前检查文件路径确保不覆盖用户的项目文件这种做法很值得借鉴。自己的技能脚本应该明确写入日志避免静默执行文件操作尽量限制在项目目录或技能目录内不随意处理系统目录。从平台下载别人分享的技能时也建议先打开 SKILL.md 和脚本看一眼。技能市场不是法外之地但“可执行代码”意味着风险尤其是那种带 Shell 脚本且逻辑不明的技能包我会直接跳过。开源社区的技能质量参差不齐靠使用者自己把关才是常态。3. 实操从零开发一个“自动生成分镜脚本”的 Skills 包3.1 选场景和设计产出我挑一个大家比较熟悉的场景短视频分镜脚本生成。选它的原因很简单第一业务边界清晰第二输出是结构化内容第三网上有很多现成模板可以参考。很多人一上来就想做一个“万能写作技能”结果什么都想管最后什么都做不好。做技能和做事一样先窄后宽。我期望的产出是 Markdown 格式的分镜表包含镜号、景别、运镜、画面内容、台词、音效/字幕、预计时长这些字段。这样不管是人看还是后续对接剪辑软件都很方便。同时我要求生成时附带一条“拍摄提示”把每个镜头容易出问题的点标出来这个细节是后面实践里加进去的非常实用。3.2 搭建技能包目录和入口文件我先把目录结构建出来skills/ shotlist/ SKILL.md scripts/ validate_length.py assets/ examples/ good_example.md然后写 SKILL.md。我会在文件里做到三件事告诉模型何时调用告诉模型遵循什么步骤给一个高质量示例。示例里我特意放了一个“错误示范”这在很多官方技能里都有。模型看到反例之后格式违规的概率会明显下降。SKILL.md 的大致内容可以长这样具体字段以平台文档为准--- name: shotlist description: 根据短视频选题文案生成分镜脚本。适用输入2-3分钟短视频的文案或主题。生产产物包含镜号、景别、运镜、画面、台词、字幕、时长的 Markdown 表格。不适用于长视频剪辑脚本、直播台本、文学剧本。 --- # 短视频分镜脚本生成 ## 使用步骤 1. 解析输入文案提取核心场景清单。 2. 按每分钟 8-12 个镜头拆分场景确定镜头数量。 3. 为每个镜头填写景别、运镜、画面内容、台词、音效/字幕。 4. 合理安排每个镜头的预估时长总时长与视频目标时长误差不超过 10%。 5. 在表格下方补充“拍摄提示”标注每个镜头容易出错的细节。 6. 调用 scripts/validate_length.py 校验输出文件若校验失败则根据错误信息修正后重新输出。 ## 输出格式 | 镜号 | 景别 | 运镜 | 画面内容 | 台词 | 音效/字幕 | 预计时长 |这里我没有把整个 SKILL.md 贴完但你可以看到关键逻辑步骤是固定的格式是固定的校验是强制性的。后面生成时模型即使自由发挥也有脚本兜底。3.3 让脚本帮模型兜底文字指令不能百分之百保证格式正确所以我写了个校验脚本validate_length.py接收生成的分镜文件检查总时长是否落在目标范围内检查每行字段是否齐全。skill 的执行步骤末尾加上“生成后用脚本校验若不通过则自动修正后重新输出”。实测下来这一步把格式错误率降低了很多。为什么不把这个校验逻辑全交给模型自己判断因为模型对数字计算不敏感经常把 10 个镜头算成 12 分钟。脚本能确定时长总和、镜头数量、缺失字段是典型的确定性逻辑应该交给代码。下面的脚本框架供参考import sys from pathlib import Path def validate(filepath: str, target_seconds: float 150.0, tolerance: float 0.1): rows Path(filepath).read_text().strip().splitlines() required_fields [镜号, 景别, 运镜, 画面内容, 台词, 音效/字幕, 预计时长] total_seconds 0.0 for line in rows[1:]: cells [c.strip() for c in line.strip(|).split(|)] if len(cells) ! len(required_fields): print(fFAIL: 字段数量不对: {line}) return False try: total_seconds float(cells[-1]) except ValueError: print(fFAIL: 时长字段异常: {line}) return False if abs(total_seconds - target_seconds) target_seconds * tolerance: print(fFAIL: 总时长 {total_seconds}s 超出目标 {target_seconds}s 的容差范围) return False print(fPASS: 总时长 {total_seconds}s) return True if __name__ __main__: sys.exit(0 if validate(sys.argv[1]) else 1)这个脚本很简单但它恰恰证明了“确定性逻辑交给代码”的价值。后来我在多个技能里沿用这个套路效果都不错。3.4 本地测试的基本流程要测试一个技能不需要先接入大模型可以直接手动模拟调用准备好输入文件根据 SKILL.md 的步骤人工走一遍检查步骤是否连贯运行脚本验证输出再用真实 agent 平台跑一次观察模型是否在正确场景触发该技能输出的格式是否符合预期。我通常用三到五组不同难度的输入做测试包括一个正常输入、一个边界输入比如内容明显超出时长、一个意图模糊输入。如果发现模型完全不触发技能先检查描述是不是太啰嗦或者太具体如果角色执行了技能但输出不符合预期就检查指令区和示例。测试不是一次性的技能在真实使用中会暴露新问题因此给技术包加上版本号可以在迭代时避免混乱。我把版本号写在 SKILL.md 的名称字段里并在 README 里维护变更记录这是长期维护的关键。3.5 为什么我不迷信“技能市场一键下载”现在网上有不少 skills 下载平台和官方市场确实方便。但直接下载别人分享的技能包经常遇到几个情况平台格式不兼容技能包里的脚本依赖缺失或者描述里的触发逻辑和你的工作流根本不匹配。我的建议是把第三方技能当参考模板自己动手改一版再上项目。比如我下载过一个“论文提纲生成”技能写得很好但它是面向英文论文的。我花了二十分钟把输出格式改成中文论文结构替换了示例资源并加了一个参考文献格式校验脚本。改完之后这个技能才真正变成我的“工作流的一部分”。抄作业可以但一定要把作业改成适合自己的。4. 常见问题与排查技巧实录4.1 高频问题速查表以下这些问题是我在多个技能开发项目里反复遇到的整理成表格供你直接对照问题现象常见原因排查与解决思路agent 完全不调用技能描述过宽或过窄被其他技能抢占触发机会重写 description明确适用输入和不适用边界技能被错误调用description 里的关键词太多语义模糊删掉宽泛词使用任务场景而非工具名描述输出格式每次都不一样SKILL.md 没有给出固定模板示例不足增加一个高质量示例和一个反例固定表格字段文字指令太长模型中途失忆规则冗余挤占上下文窗口缩减到 5-8 步确定性逻辑交给脚本脚本执行报路径错误使用了绝对路径或路径拼接错误统一用脚本所在目录向上取根目录再拼相对路径技能之间互相“打架”两个技能的描述高度相似为每个技能定义独立场景避免交叉领域第三方技能无法使用平台格式不同依赖缺失检查 SKILL.md 的字段格式补齐 scripts 依赖上下文消耗过快技能描述太长或内置了大量背景知识把详细知识外置到 assets按需读取这个表不一定要完全照搬但排查思路是通用的先确认是否触发再确认触发后的步骤是否完整最后再怀疑模型能力。大多数问题其实出在技能设计本身而不是平台。4.2 每次写完技能都要问的三个问题我每次开发完一个技能都会问自己三个问题。第一如果只让一个完全不知道背景的同事读 SKILL.md能不能按步骤执行这能检验指令的完整性。第二如果输入内容偏离预期技能是优雅降级还是直接崩溃这能检验边界设计。第三如果把脚本删掉技能的正确率会不会大幅下降如果会说明确定性逻辑还没有完全抽离出来。这三点听起来简单但能全部做到的技能包不多。我见过很多技能包里的脚本只有一句print(hello)等于没有也见过描述写得天花乱坠实际执行却全是坑。把这三个问题当成验收标准技能的可用性会有明显提升。4.3 维护和迭代的实用心得技能不是一次写完就一劳永逸的至少每个月要回看一次执行日志。我一般会在技能包里放一个 CHANGELOG.md记录每个版本的变更点。比如我今天改了命名规则明天加了新的运镜类型如果不记录过两周自己都忘了这个技能为什么这么设计。此外建议一个项目里的技能数量不要贪多。五到十个高质量技能比一百个低质量技能可靠得多。每次新增技能之前先在现有技能里找找有没有能复用的避免重复造轮子。我在实际项目里就吃过亏同一个“整理会议纪要”的功能两个目录里放了两份不同的实现agent 有时触发这个有时触发那个最后花了不少时间统一。最后分享我的一点实际体会Skills 的价值不在于“把 prompt 换一个格式保存”而在于逼着你去思考“这个任务到底是怎么被稳定完成的”。当你开始认真拆分任务步骤、抽离确定性逻辑、设计兜底脚本时你其实是在用自己的经验和判断力给 AI 画一张可执行的地图。这个过程本身比任何现成的技能包都更有价值。如果你也想给智能体配一套真正的 superpower skills别急着下载先挑一个反复做过的高频任务从手工编写 SKILL.md 开始你会打开一扇新世界的大门。