从Prompt到Superpower Skills：AI智能体技能包开发实战

最近一个月，“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.md

SKILL.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(f"FAIL: 字段数量不对: {line}") return False try: total_seconds += float(cells[-1]) except ValueError: print(f"FAIL: 时长字段异常: {line}") return False if abs(total_seconds - target_seconds) > target_seconds * tolerance: print(f"FAIL: 总时长 {total_seconds}s 超出目标 {target_seconds}s 的容差范围") return False print(f"PASS: 总时长 {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 高频问题速查表

以下这些问题，是我在多个技能开发项目里反复遇到的，整理成表格供你直接对照：

这个表不一定要完全照搬，但排查思路是通用的：先确认是否触发，再确认触发后的步骤是否完整，最后再怀疑模型能力。大多数问题其实出在技能设计本身，而不是平台。

4.2 每次写完技能都要问的三个问题

我每次开发完一个技能，都会问自己三个问题。第一，如果只让一个完全不知道背景的同事读 SKILL.md，能不能按步骤执行？这能检验指令的完整性。第二，如果输入内容偏离预期，技能是优雅降级还是直接崩溃？这能检验边界设计。第三，如果把脚本删掉，技能的正确率会不会大幅下降？如果会，说明确定性逻辑还没有完全抽离出来。

这三点听起来简单，但能全部做到的技能包不多。我见过很多技能包里的脚本只有一句print("hello")，等于没有；也见过描述写得天花乱坠，实际执行却全是坑。把这三个问题当成验收标准，技能的可用性会有明显提升。

4.3 维护和迭代的实用心得

技能不是一次写完就一劳永逸的，至少每个月要回看一次执行日志。我一般会在技能包里放一个 CHANGELOG.md，记录每个版本的变更点。比如我今天改了命名规则，明天加了新的运镜类型，如果不记录，过两周自己都忘了这个技能为什么这么设计。

此外，建议一个项目里的技能数量不要贪多。五到十个高质量技能，比一百个低质量技能可靠得多。每次新增技能之前，先在现有技能里找找有没有能复用的，避免重复造轮子。我在实际项目里就吃过亏：同一个“整理会议纪要”的功能，两个目录里放了两份不同的实现，agent 有时触发这个，有时触发那个，最后花了不少时间统一。

最后分享我的一点实际体会：Skills 的价值不在于“把 prompt 换一个格式保存”，而在于逼着你去思考“这个任务到底是怎么被稳定完成的”。当你开始认真拆分任务步骤、抽离确定性逻辑、设计兜底脚本时，你其实是在用自己的经验和判断力，给 AI 画一张可执行的地图。这个过程本身，比任何现成的技能包都更有价值。如果你也想给智能体配一套真正的 superpower skills，别急着下载，先挑一个反复做过的高频任务，从手工编写 SKILL.md 开始，你会打开一扇新世界的大门。