前阵子和一个做前端的朋友聊天他说自己最近被“智能体”刷屏了但越看越迷糊大家都在说 Agent、提示词、插件、MCP、Skills这些词到底什么关系尤其是“Skills”这个词看起来像是一个新功能又像是一个概念包装网上教程要么讲得太深要么只是翻译官方文档零基础的人很难建立起整体认知。这篇文章我就用尽量通俗的方式把“Skills技能包”是什么、解决什么问题、它和提示词/工具/MCP 有什么区别、怎么自己动手做一个技能包完整讲一遍。文章面向的是刚接触 AI 智能体的新手也适合已经在用各类智能体框架、但没系统整理过 Skills 概念的开发者。整个内容会按照“概念 → 原理 → 实战 → 排错 → 最佳实践”的顺序展开代码和配置都能直接复制参考。1. 什么是 Skills先解决一个根本问题1.1 智能体不是“更聪明的对话机器人”先说一个常见的误区。很多人把智能体想象成“一个特别会聊天的 AI”认为只要把提示词写得足够长、足够细它就能自动完成复杂任务。这个理解在简单场景下没错比如让 AI 写一段文案、翻译一段英文靠提示词确实够用。但一旦任务变得具体比如“检查某个前端项目里所有 HTML 页面的图片是否缺少 alt 属性并生成一份报告”情况就不一样了。这类任务需要 AI 具备一套完整的“工作方法”知道去看哪些文件、用什么规则判断、以什么格式输出结果、遇到异常如何处理。如果把这些工作方法全部塞进提示词会出现两个问题上下文窗口被大量挤占。提示词越长留给真实任务处理的空间就越小模型也更容易在长指令中“迷失重点”。能力不可复用。你在项目 A 里写好的检查规则换到项目 B 又要重新写一遍无法沉淀成标准化资产。Skills 要解决的正是“把能力固化、打包、复用”这件事。1.2 技能包的直观比喻岗位说明书 工作工具箱用一个生活中的例子来理解假设你是团队主管要招一个“前端质检工程师”。你不会每次都把这个岗位的所有职责现场写一遍而是会给他一份“岗位说明书”告诉他要检查什么、用什么工具、报告格式是什么。再配合一个“工具箱”里面放着测试脚本、模板、配置清单。在 AI 智能体里Skills 就是这个组合。一个技能包通常包含三个部分一份“说明文件”用人类和 AI 都能理解的语言描述这个技能是做什么的、什么时候该用、怎么用。一个“执行程序”可以是 Python 脚本、Shell 命令、Node 脚本真正去干活的工具。一组“配套资源”比如报告模板、依赖清单、测试用例。当智能体收到一个任务时它会根据说明文件的描述判断当前任务是否属于某个技能包的能力范围。如果是就加载技能包按里面定义的流程执行而不是每次都在对话里临时编写步骤。1.3 Skills 与提示词、插件、工具的区别很多人会把 Skills 和提示词、插件、工具搞混这里我用一张表梳理一下概念核心是什么解决的问题典型例子Prompt 提示词一段自然语言指令引导模型按特定方式回答“请用 Markdown 格式总结这篇文章”Tool 工具一个可调用的函数/接口让模型能访问外部世界搜索接口、计算器、文件读写函数Plugin 插件预定义的工具集合一次配置批量接入外部能力浏览器插件、图像生成插件Skill 技能包说明文件 脚本 资源把完成一类任务的方法论整体固化前端审查、专利辅助、论文格式整理简单说提示词是“说给模型听的话”工具是“模型能用的手”插件是“手的集合”而 Skill 是“一套完整的工作流程”里面可以用到多个工具、多个脚本、多份模板。这也是为什么现在很多 Agent 框架会把 Skills 单独抽象出来——它比工具更大比一套应用更小正好处在“能复用、可分发、易组合”的粒度上。2. 为什么近一年 Skill 突然火起来了2.1 大模型的“通用”遇上业务的“专用”大模型本身是通用的这既是优点也是缺点。优点在于什么都能聊一点缺点在于任何具体领域做到深处都需要领域特有的规则、格式、工具、经验。让一个通用模型成为“合格的前端审查工程师”需要的不只是“知道 HTML 是什么”还要知道你们团队规定的 alt 属性写法、报告模板样式、检查命令怎么跑。这就是一个很现实的矛盾底层模型的能力提升靠的是模型厂商业务垂直能力的积累靠的是每个团队自己。Skills 恰好提供了一个中间层底层模型不变但通过技能包装入行业知识和工作流让通用模型能处理专用任务。它不必重新训练模型也不用为每个场景写一套复杂提示词。2.2 Agent 工作流需要“方法论”沉淀目前主流的智能体工作流基本是“感知—规划—行动—反思”四步循环感知接收用户任务理解目标。规划拆解任务生成步骤。行动调用工具、执行代码、读取文件。反思检查结果决定是否调整重试。在工作流中“规划”和“行动”两个环节需要大量领域知识。比如你让智能体“检查这个项目的前端质量”如果它没有技能包规划出来的步骤可能天马行空行动时也不知道该调用什么命令。而有了技能包之后规划阶段可以直接参考 SKILL.md 中写好的标准步骤行动阶段按脚本执行即可。也就是说Skill 在 Agent 工作流里同时承担了两件事降低规划的不确定性给智能体一个“标准操作手册”。提升行动的稳定性把容易出错的步骤交给预写代码去执行。2.3 主流平台的官方支持与生态爆发从实际生态来看Skills 已经不只是某个框架的私有概念。Claude 在 2025 年下半年把 Skills 作为 Agent 能力的核心组件推出配套了官方技能市场和大量风格示例OpenAI 的 Codex 也支持在项目中定义技能目录在编程类智能体中广泛使用 SKILL.md 作为技能描述文件国内外的智能体平台如 Coze 也将技能/插件作为搭建 Agent 的重要模块。在 GitHub 上可以搜索到大量社区维护的技能包仓库涉及前端开发、代码审查、论文写作、数据分析、专利辅助、销售支撑等多个场景。甚至有人把“Skills 开发”本身当成一种新的工程岗位来讨论这从侧面说明了一个趋势技能包正在成为 AI 工程化中最值得沉淀的资产类型。3. Skills 的核心组成与运行机制3.1 SKILL.md技能的说明文件任何技能包的核心入口通常是一个叫 SKILL.md 的文件。这个文件的作用是让 AI 在“决定要不要用某个技能”时能够快速理解技能的用途和触发条件。一个典型的 SKILL.md 包含两部分YAML 格式的 frontmatter也就是文件最上方被---包住的元信息。Markdown 格式的正文描述完整的工作步骤、注意事项、输入输出格式。我们来看一个示例--- name: frontend-review description: 用于前端页面质量审查检查 HTML 文件中 img 标签的 alt 属性、标题层级等基础可访问性问题适用于网页项目上线前的自查。 --- # 前端审查技能 当用户要求检查前端页面质量、可访问性、图片 alt 属性时使用本技能。 ## 执行步骤 1. 确定目标页面文件或目录。 2. 运行 scripts/review.py 执行检查。 3. 阅读输出结果向用户呈现整改建议。 ## 输出格式 - 默认输出文本摘要。 - 如果用户要求 JSON可附加 --format json 参数。这份文件不需要很长但要足够清楚。AI 大模型会基于这里面的描述判断“当前用户任务是不是属于这个技能的范围”。也就是说SKILL.md 写得越贴近真实触发场景技能被正确调用的概率越高。3.2 技能脚本真正干活的程序SKILL.md 告诉智能体“该做什么”而技能脚本负责“把它做出来”。脚本可以是 Python、Shell、JavaScript也可以是任意能在目标环境中执行的命令。一般来说脚本需要满足几个要求输入参数稳定最好支持命令行参数。输出结构化便于 AI 读取结果并继续向用户汇报。有基本的异常处理不能让一笔脏数据中断全过程。例如3.1 中的前端审查技能实际业务逻辑就写在 scripts/review.py 里。智能体负责判断应该调用这个技能然后通过运行脚本获得结果再把结果组织成自然语言回复给用户。这很重要千万不要让 AI 在对话里“生算”结果而是通过脚本去精确计算。脚本输出的每个字段、每行文本都应当能被 AI 理解和引用。3.3 大模型如何决定“该用哪个技能”你在对话中提出了一个需求智能体请求到达之后它会做一个关键动作把所有可用技能的摘要也就是每个 SKILL.md 里的 name 和 description作为候选列表放进系统提示词。大模型看到的是类似这样的文本可用技能 - frontend-review: 用于前端页面质量审查检查 HTML 文件中 img 标签的 alt 属性…… - patent-assist: 用于专利文档辅助撰写生成技术交底书结构…… - paper-format: 用于学术论文格式整理统一参考文献样式……然后模型会在规划阶段判断用户当前说的“帮我看看这个 HTML 文件有没有问题”与 frontend-review 的描述高度匹配于是决定加载并执行这个技能。这也是为什么技能描述里要写“什么时候用”而不是只写“这个技能是什么”。一个描述模糊的技能很容易在决策阶段被跳过。3.4 Skills、Tools、MCP 的分层关系在真实的智能体工程中Skills 并不是孤立的它和 Tools、MCP 有明确的分层关系Tool工具是最小粒度的可执行单元比如“读取文件”“执行命令”“调用搜索引擎”。MCPModel Context Protocol模型上下文协议是一种标准化协议它让不同的 AI 应用能通过统一接口接入外部工具和数据源。解决了“工具怎么被外部应用发现和调用”的问题。Skill技能包则是更高一层的编排单元它把多个 Tool 调用、脚本执行、决策规则组合成一个完整的任务流程。用一个类比Tool 是拧螺丝的螺丝刀MCP 是标准化的螺丝接口规格而 Skill 是“安装一盏灯”的完整作业指导书——先断电、再接线、后测试。三者并不冲突Skill 通常会使用 Tool也可能会通过 MCP 连接外部系统。4. 动手实战做一个“前端质检”技能包这一节我们从一个零基础可上手的场景出发一步步构建自己的技能包。场景设定是让 AI 智能体检查前端页面中的图片是否都带了 alt 属性便于开发者发现可访问性问题。4.1 场景与技能包设计先明确目标我们想要一个技能包输入是一个 HTML 文件或包含 HTML 的目录输出是如下信息一共检查了多少个 HTML 文件。每个文件中使用了多少张图片。哪些图片缺少 alt 属性。支持文本和 JSON 两种输出格式。基于这个需求技能包的目录结构可以这样设计frontend-review/ ├── SKILL.md └── scripts/ └── review.py先不引入复杂的模板和测试目录保持最小可用。4.2 编写 SKILL.md文件路径frontend-review/SKILL.md--- name: frontend-review description: 检查 HTML 页面中的图片 alt 属性。当用户需要审查前端可访问性、检查 img 标签、生成可访问性报告时使用。 --- # 前端图片 alt 属性审查 本技能用于检查一个或多个 HTML 文件中的 img 标签是否存在 alt 属性并输出统计报告。 ## 用法 在技能目录下执行 bash python3 scripts/review.py html文件或目录 [--format text|json]输出默认输出缺失 alt 的图片列表和汇总行。使用 --format json 时输出 JSON 数组便于程序处理。注意这里的核心是 description。它包含了“检查图片 alt 属性”“前端可访问性”“img 标签”等触发词当用户提出相关需求时智能体能够准确命中。 ### 4.3 编写 Python 脚本 文件路径frontend-review/scripts/review.py 我们使用 Python 标准库中的 html.parser 来解析 HTML不依赖第三方包方便任何环境直接运行。 python #!/usr/bin/env python3 前端图片 alt 属性审查脚本。 import argparse import json from html.parser import HTMLParser from pathlib import Path class ImageAltChecker(HTMLParser): 解析 HTML 并收集 img 标签信息。 def __init__(self): super().__init__() self.images [] def handle_starttag(self, tag, attrs): if tag.lower() ! img: return attr_dict dict(attrs) src attr_dict.get(src, ) alt attr_dict.get(alt, ) self.images.append({ src: src, alt: alt, has_alt: bool(alt.strip()), }) def scan_html(file_path: Path): 扫描单个 HTML 文件。 parser ImageAltChecker() try: content file_path.read_text(encodingutf-8, errorsignore) parser.feed(content) except Exception as exc: return { file: str(file_path), error: str(exc), images: [], } return { file: str(file_path), images: parser.images, } def main(): parser argparse.ArgumentParser( description检查 HTML 文件中 img 标签的 alt 属性 ) parser.add_argument(paths, nargs, helpHTML 文件或目录路径) parser.add_argument( --format, choices[text, json], defaulttext, help输出格式默认 text, ) args parser.parse_args() targets [] for raw in args.paths: p Path(raw) if p.is_dir(): targets.extend(p.rglob(*.html)) elif p.is_file(): targets.append(p) else: print(f跳过无效路径: {raw}) results [scan_html(f) for f in targets] if args.format json: print(json.dumps(results, ensure_asciiFalse, indent2)) return total_images 0 missing_alt 0 for result in results: for img in result.get(images, []): total_images 1 if not img[has_alt]: missing_alt 1 print( f[缺失 alt] {result[file]} - {img[src]} ) print( f\n共检查 {len(results)} 个文件 f发现 {total_images} 张图片 f其中 {missing_alt} 张缺少 alt 属性。 ) if __name__ __main__: main()这段代码用到的核心类是HTMLParser它会在解析过程中触发handle_starttag回调。我们只关注img标签提取src和alt属性然后判断 alt 是否为空。对目录的处理使用Path.rglob(*.html)可以递归找到所有 HTML 文件。4.4 准备测试页面并运行为了验证技能包我们先创建一个测试页面pages/index.html!DOCTYPE html html head meta charsetutf-8 title测试页面/title /head body h1技能包测试/h1 img srcimages/logo.png alt网站 Logo img srcimages/banner.png img srcimages/icon.png alt /body /html然后执行脚本cd frontend-review python3 scripts/review.py ../pages/预期输出大致如下[缺失 alt] ../pages/index.html - images/banner.png [缺失 alt] ../pages/index.html - images/icon.png 共检查 1 个文件发现 3 张图片其中 2 张缺少 alt 属性。如果加上--format json则可以看到结构化的 JSON 数组这也方便把技能输出接入上游的自动化流程。至此一个最简技能包已经流转起来了SKILL.md 负责“被 AI 发现和理解”review.py 负责“实际执行”。把这两部分合在一起就是一个可以被复用的能力资产。4.5 接入智能体的思路不同 Agent 框架的 API 差异很大但接入逻辑是通用的解析技能包目录里的 SKILL.md把技能摘要注入系统提示词然后在需要执行时调用技能脚本。下面是一个“读取技能摘要”的参考实现import re from pathlib import Path def load_skill_summary(skill_dir: Path): 从 SKILL.md 中提取技能名称和描述。 meta_path skill_dir / SKILL.md if not meta_path.exists(): return None text meta_path.read_text(encodingutf-8) yaml_match re.search(r^---\n(.*?)\n---, text, re.S | re.M) if not yaml_match: return None meta {} for line in yaml_match.group(1).strip().splitlines(): if : in line: key, value line.split(:, 1) meta[key.strip()] value.strip().strip(\).strip() if name not in meta or description not in meta: return None return { name: meta[name], description: meta[description], } # 示例扫描 skills 目录生成候选技能列表 if __name__ __main__: skills_root Path(./frontend-review) summary load_skill_summary(skills_root) print(summary)这个思路是通用的无论你用的是某个商业平台的智能体还是自己写的 Agent 调度程序都可以用“读取 SKILL.md 摘要 → 注入决策上下文 → 按需执行脚本”的三步流程。5. 常见问题与排查思路在实际使用和开发技能包的过程中新手最常遇到以下问题问题现象常见原因解决思路智能体从不调用已配置的技能SKILL.md 中的描述与用户任务关键词不匹配重写描述明确触发场景和输入输出技能脚本报“模块找不到”第三方依赖未安装或 Python 环境不对使用虚拟环境提供 requirements.txt技能执行了但结果不稳定脚本输出格式不固定AI 无法解析规定输出格式优先输出 JSON 或表格多个技能描述重叠命中混乱技能边界不清描述相似度过高每个技能只负责一个细分场景差异化描述SKILL.md 没有生效文件名大小写、目录位置不符合平台约定确认平台的技能目录规范参考官方示例下面挑几个高频问题展开说明。5.1 技能被忽略问题可能出在描述如果一个技能总是不被使用命令检查最优先的方向是 SKILL.md 的 description。很多新手会把描述写成“这是一个前端审查技能”但其实智能体是根据用户问句反查技能的。更好的写法是覆盖更多自然表达description: 当用户提到检查网页可访问性、图片缺少 alt 属性、HTML 标签规范性、前端页面质量报告时使用本技能。把“用户会怎么说”写进描述比“描述自己的功能”更有效。5.2 脚本能跑但结果无法被理解技能脚本的输出不只是给人看的也是给 AI 看的。如果脚本输出一堆约束不清晰的文本AI 无法准确提炼结论用户得到的回复自然就乱。解决办法是给脚本设计一套稳定输出协议。默认输出包含固定的字段名JSON 模式使用统一结构。上面示例中scan_html 返回的file、images、has_alt字段就是刻意设计的稳定结构方便 AI 引用。5.3 路径问题的隐藏坑实际使用中很多人会报“脚本明明放在技能包里运行时却找不到文件”。最常见的原因是当前工作目录不对。建议在 SKILL.md 中明确写明所有相对路径都相对于技能包根目录并在脚本内部用Path(__file__).resolve().parent.parent定位项目根而不是依赖运行环境的当前目录。这个技巧能避免大部分路径事故。6. 最佳实践与工程建议想在一个团队中把技能包真正用起来下面这些经验值得参考。6.1 一个技能只做一件事技能包的粒度要小边界要清晰。“前端图片 alt 属性审查”是一个好技能因为它职责明确。“网页全面质量检查”则不是一个好技能因为这个描述太宽泛既可能包含可访问性又可能包含性能、SEO、代码规范。当技能执行到一半AI 发现自己还需要其他能力时正确的做法是让 Agent 调度多个技能协同而不是硬塞进一个技能里。6.2 描述写在“用户怎么说”的维度上写 SKILL.md 描述时不要只写“本技能用于……”而是要写清“当用户什么时候的需求应当调用本技能”。这看起来只是表述差异实际效果差距很大。模型在决策阶段靠的就是描述与用户输入的语义匹配描述越贴近用户真实表达命中率越高。6.3 输出结构优先于输出美观技能脚本的输出应该优先考虑机器可读性再考虑人工可读性。默认输出可以是给人看的摘要但强烈建议同时提供--format json选项。这样一来技能不仅能服务终端用户还能被其他程序或 Agent 继续消费。6.4 安全边界必须考虑技能包运行时本质是让 AI 拿到了一段可执行代码。这里有两个风险点权限风险技能脚本可能读取文件、执行命令、调用网络接口。应严格限制技能默认使用的工具集不要给高危指令。数据风险涉及生产环境、数据库、线上系统的操作必须默认只读并在执行敏感变更前要求人工确认。在 SKILL.md 中可以明确声明技能的权限边界比如“本技能仅读取本地 HTML 文件不会修改任何源文件”“本技能不会访问任何外部接口”。在编写脚本时也应当避免接收任意的 shell 指令拼接参数。6.5 为技能包建立版本和测试技能包也是软件资产应当像普通代码一样管理。推荐在技能包目录中加入tests/目录为脚本写最小测试用例。也可以给 SKILL.md 增加版本号字段便于在不同 Agent 环境中追踪技能版本。--- name: frontend-review version: 0.1.0 description: ... ---在团队多人协作时还可以建立内部技能包仓库统一规范目录结构、描述写法、输出协议让不同项目的 Agent 可以共享同一个技能集市。6.6 定期回归测的不只是脚本还有描述技能脚本的测试相对容易输入一组 HTML检查输出是否准确。但更隐蔽的问题是当底层模型版本变化时同样的技能描述是否还能被正确触发。建议在每次升级模型版本后用一批真实用户提问做一次“技能命中测试”把提问输入模型看它是否正确选择了对应技能。这一步虽然麻烦却是保证技能包长期有效的关键。7. 下一步如何从零开始搭建自己的技能包如果你看完这篇文章想立刻动手验证建议按下面三步操作选一个你每天都在做的重复性任务比如“整理会议纪要格式”“统一代码提交信息”“检查读书笔记里的错别字”哪怕它很小只要重复就有沉淀价值。按照本文的模式写一个最小 SKILL.md 一个脚本先在你的开发环境里手动运行脚本确认输出稳定。接入你常用的智能体平台用几轮真实提问测试技能触发率再持续优化 description。真正的 AI 工程化能力不是会调用几个大模型接口而是能把日常工作固化成像技能包这样可复用、可分发、可评测的资产。等你积累了第一个技能包再往下就可以去看技能市场、技能编排、多技能协作这些更进阶的方向。如果你在搭技能包的过程中遇到触发不准、输出解析失败、路径混乱这些问题欢迎把这篇文章里的排查思路试一遍。手动跑通了第一步后面的事情会顺很多。