那段时间我快被自己蠢哭了。明明给 AI 编程助手写了一大堆“规则”，每次开新会话都得把同样的话粘贴一遍，结果它该犯的错一个没少。直到我把目光转向“Skills”这个词，才意识到问题不在提示词长度，而在我一直在用最笨的方式跟 AI 协作。如果你也遇到过“AI 总是忘记历史约定”“同一件事每个会话都得重新教”的困境，这篇文章就是写给你的。我会从 Skills 的本质讲起，手把手带你自己写一个可复用的 Skill，再讲清楚它和 MCP 工具的关系、社区里哪些 Skill 值得装，以及我真实踩过的一堆坑。
1. 先搞清楚一件事：Skills 不是“更长的提示词”
1.1 我被“提示词模板”坑了两个月
先说我的黑历史。之前做项目，我习惯把团队的编码规范、提交信息格式、测试要求写成一个超长文档，每次开新对话就丢给 AI。问题是：这套操作有两个硬伤。第一，上下文窗口是有成本的，你把 2000 字的规则塞进去，AI 能记住的代码上下文就变少了。第二，AI 对“规则”和“参考信息”的处理权重不一样，它很容易把你的要求当成背景噪音，真正执行的时候又回到自己的默认习惯。
后来我看到社区里聊 Claude Code Skills、Codex Skills，才恍然大悟。Skills 本质上不是提示词，而是一套可以被 AI 动态加载的“职业技能包”。它不是让 AI 每次都知道，而是让 AI 在“需要用的时候才去读”，用完了就放下。这就像你给新同事不是发一本 500 页的《公司制度》，而是告诉他“遇到报销找财务手册，遇到服务器部署找运维手册”，他真正干活时再翻对应那本，效率完全不一样。
1.2 Skills 的三种硬通货：结构化描述、可执行脚本、上下文资产
一个标准的 Skill 目录，一般长这样：
my-skill/ ├── SKILL.md ├── scripts/ │ ├── analyze.py │ └── run_check.sh └── assets/ ├── template.html └── reference.pdf其中SKILL.md是灵魂，它是一个带 YAML 头的 Markdown 文件。scripts目录放可执行脚本，assets目录放 AI 执行任务时可能要参考的模板或资料。这里有个很多人误解的点：Skills 不只是“告诉 AI 怎么做事”，它真的可以调用本地脚本，也就是说 AI 可以把任务拆给脚本去完成，而不是自己凭空生成。
打个比方，普通提示词是给 AI 一张菜谱，让它凭经验做菜；Skill 是给厨房配了称量工具、食材清单和标准的操作流程图，AI 照着流程走，还能用工具测量。这两种方式做出来的菜，稳定性和出品质量完全不在一个量级。
1.3 为什么三大 Agent 平台都在做 Skills
2025 年下半年开始，Claude Code、OpenAI Codex、开源的 OpenCode 等主流 Agent 平台都陆续支持了 Skills 机制。这个时间点不是巧合，而是因为大家发现光靠模型本身的能力，无法覆盖长尾的专业场景。模型再强，也没法默认知道你们公司的代码规范、数学建模论文模板、某类 bug 的排查套路。
Skills 的目标就是把这些“少数人知道、长期沉淀、可复用”的知识固化下来，形成可以跨项目、跨团队分发的能力单元。吴恩达专门讲过 Agent Skills 的教程，核心观点也很直接：未来最有价值的不是会写提示词的人，而是能把专业工作流封装成 Skill 的人。你可以把 Skills 理解成 AI 时代的“插件生态”，谁掌握了封装能力，谁就能让 AI 替自己干更多脏活。
2. 手写一个属于自己的 Skill：以“测试用例生成器”为例
2.1 Skill 目录结构与 SKILL.md 的 YAML 头字段
纸上谈兵没意思，我直接带你写一个能用的 Skill。我们的目标很具体：让 AI 根据代码仓库里的函数，自动生成边界测试用例，并输出成指定格式。
先创建目录：
mkdir -p ~/.claude/skills/test-case-generator/{scripts,assets} cd ~/.claude/skills/test-case-generator然后创建SKILL.md：
--- name: test-case-generator description: 当用户需要对某个函数、模块或接口编写单元测试用例，或者需要生成覆盖边界条件的测试数据时，使用此技能。 --- # 测试用例生成器 ## 工作流程 1. 定位用户指定的函数或接口，提取输入参数、返回值和关键逻辑分支。 2. 使用 scripts/scan_dependencies.py 分析函数的外部依赖。 3. 根据 rules.md 中的边界值清单，生成测试用例表格。 4. 将结果输出为用户指定的测试框架代码（如 pytest、JUnit、Go test）。这里最需要注意的是name和description两个字段。name是 Skill 的唯一标识，而description是 AI 决定“什么时候该用这个技能”的主要依据。你写得越具体、越贴近用户真实说法，AI 触发它的概率越高。
2.2 让 AI“发现”你的 Skill：description 的设计比写正文更费功夫
很多人写完 Skill 后发现 AI 死活不调用，十有八九是 description 写得像废话。比如你写“用于生成测试用例”，这句是没错，但太抽象了。AI 不是每次都在思考“我该不该用测试用例生成器”，它是在看完用户消息后，匹配哪个 Skill 的 description 和当前任务语义最接近。
更有效的写法是列举触发场景：
description: 当用户提到“写单测”“补测试”“覆盖边界”“测试没写全”“生成测试数据”，或者要求对特定函数/接口进行测试覆盖时，使用此技能。不适用于整体项目的测试策略讨论。加一句“不适用于什么情况”也很重要，能防止 AI 在错误场景下强行走这个流程。我在实际测试中发现，加了这个负向约束后，误触发率明显下降。
2.3 安装与验证：npx skills add 的真实执行过程
自己手写目录是一种方式，社区里更常用的是用 CLI 工具安装别人写好的 Skill。你在很多仓库 README 里会看到这样一行命令：
npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y拆开解释一下：npx skills add是调用一个叫skills的 npm 工具去拉取 GitHub 仓库里的 Skill；sandai-org/vidmuse-skills是仓库地址；--agent claude-code指定这套 Skill 给哪个 Agent 用；-g表示装到全局目录；-y表示跳过确认提示。
安装完成后，你可以直接用这样的方式验证：
npx skills list --agent claude-code或者直接问 AI：“你现在有哪些可用技能？”它如果列出了你刚装的 Skill，说明加载成功。如果你自己手写了目录，也可以在项目里让 AI 执行这个 Skill 对应的任务，看它是否会引用 SKILL.md 中的步骤。
3. 让 Skill 调用 MCP 工具：从“会说话”到“会干活”
3.1 MCP 与 Skills 的关系：一个是水电，一个是家电
很多刚接触 Skills 的人会被另一个词搞晕——MCP。MCP（Model Context Protocol）是模型的上下文协议，它解决的是“AI 怎么安全地连接外部工具和数据源”的问题。比如让 AI 查数据库、调浏览器、访问内部 API，这些都是通过 MCP 服务器来完成的。
那 MCP 和 Skills 是什么关系？我自己的理解是：MCP 是水电基础设施，Skills 是家电。家里通了水电（MCP），但你还需要具体的电器（Skill）知道怎么用水电来做饭、洗衣服。一个 Skill 的脚本里，完全可以去调用一个 MCP 服务器提供的工具，把外部实时数据拉回来再处理。这也是为什么很多热搜词里会有“skills 如何调用 mcp 工具”——这两个东西本来就是配合使用的。
3.2 在 Skill 中声明并传递 MCP 能力的实操方式
当你的 Skill 需要某个 MCP 工具时，有两种做法。
第一种是在SKILL.md的 YAML 头里显式声明依赖：
--- name: web-visual-check description: 当用户需要对页面截图进行视觉还原度检查，或要求比对设计稿与前端实现时，使用此技能。 allowed-tools: - mcp__playwright - mcp__vision ---allowed-tools字段告诉 AI：执行这个技能时，可以调用哪些 MCP 工具。AI 看到这个声明后，会在执行过程中优先使用对应的工具，而不是自己瞎猜。
第二种是把 MCP 服务器配置在项目级别，然后在 Skill 正文里写上“请先通过 mcp__xxx 工具获取数据，再进入下一步”。这两者的区别在于：前者是声明式，AI 在技能加载阶段就知道要用什么；后者是命令式，AI 执行到某一步才想起来要调工具。实际体验下来，声明式更稳定，推荐优先用。
3.3 实例：图片还原设计稿的 Skill 如何把视觉识别串进来
热搜词里有个很具体的需求：“图片还原设计稿给前端开发好用的 skills”。这个场景特别适合展示 MCP + Skills 的组合拳。社区里一个比较典型的 Skill 流程是这样的：
- 用户丢给 AI 一张设计稿截图，说“按这个实现页面”。
- 这个 Skill 的 description 命中，触发流程。
- Skill 内部第一步调用一个视觉类 MCP 工具，把图片中的布局、配色、字体、间距提取成结构化 JSON。
- 第二步调用前端脚手架相关的工具，生成 React/Vue 组件代码。
- 第三步可选调用浏览器截图工具，对渲染结果截图，再与原始设计稿比对，计算还原度。
如果没有 MCP，AI 面对一张图片只能“描述它看到了什么”，无法把视觉信息精确转成样式代码；如果没有 Skill，AI 就算有了视觉能力，也不知道该按什么顺序做。两者结合，才真正做到从设计稿到页面的半自动还原。
4. 值得安装的社区 Skills 清单（按真实场景筛选）
4.1 前端开发与结构图生成
前端场景是 Skills 数量最多的领域之一。我在实际用下来，真正值得装的有两类。
一类是页面还原类，也就是上面提到的设计稿转代码。注意这类 Skill 的质量参差不齐，判断标准是看它的SKILL.md有没有定义可量化的输出规范，比如“输出组件必须使用 TypeScript”“样式单位统一使用 rem”，没有这些约束的八成就只是一个花架子。
另一类是结构图生成类。AI 生成 Mermaid 语法并不难，难的是如何根据代码仓库的目录结构和函数调用关系，抽取出有价值的架构图。好的结构图 Skill 会先调用脚本扫描代码依赖，再按指定风格生成图表，而不是让 AI 凭感觉画。这里我多说一句：结构图 token 消耗高，如果只是画个简单的流程示意，不建议启用重型 Skill。
4.2 数学建模/数模比赛场景
数学建模是另一个让我眼前一亮的应用方向。搜索“数学建模skills推荐”能翻出不少资源，但真正有含金量的集中在三块。
第一块是数据预处理。数模比赛的第一天基本都是在清理数据，一个能自动识别缺失值、异常值并生成清洗报告的 Skill 非常值钱。第二块是模型选择，好的 Skill 会把问题类型（预测、分类、优化）和候选算法列表之间的映射关系写清楚，避免 AI 上来就给你套一个神经网络。第三块是论文输出，数模比赛对 LaTeX 排版和图表格式要求极高，一个内置论文模板的 Skill 能帮你节省至少半天时间。
我自己用过的一个思路是：把往年优秀论文的摘要结构拆解成模板，写进 Skill 的 assets 目录，然后让 AI 按那个结构生成摘要。效果比让 AI 自由发挥稳定得多。
4.3 测试用例与代码审查
测试用例类 Skill 属于“门槛低、上限也低”的类型。简单说说它的问题：很多测试用例 Skill 只会套一个模板，生成的用例全是 happy path，边界值覆盖基本靠运气。我用下来比较可靠的做法是，在 Skill 的脚本里内置一个“边界值枚举器”，让它自动解析函数签名，生成 null/空值/超长/负数/精度临界等测试数据，再交给 AI 组织成测试代码。
代码审查类 Skill 则更看重规则沉淀。你可以把团队的 Code Review 检查表固化进 SKILL.md，比如“禁止魔术数字”“所有数据库查询必须带 limit”“错误信息必须包含上下文”，AI 在审查时就会逐条核对，而不是笼统说一句“代码质量不错”。
4.4 Codex 环境下的项目分析 Skill
如果你用的是 OpenAI Codex，会发现它的 Skills 生态和 Claude Code 不太一样。OpenCode 这类开源项目也在做自己的实现。跨平台使用时，最稳的方案是找那种“只写 SKILL.md + 纯脚本、不依赖特定 Agent 特性”的通用 Skill，它们到哪个平台都能跑。
Codex 环境下的“项目分析” Skill，我见过做得比较优秀的，会在SKILL.md里定义一个多层级的分析流程：先读取项目 README 和依赖清单，再扫描核心模块的代码结构，最后生成一份包含风险点、技术债、可选优化方向的报告。它的核心价值不在于分析得有多深，而在于输出格式一致，方便团队横向对比不同项目的健康状况。
4.5 哪些 Skills 我建议谨慎安装
社区 Skills 鱼龙混杂，下面几类我建议谨慎。
第一类是带自动执行脚本但代码不透明的。有些 Skill 的 scripts 里写着 curl 外传数据，或者偷偷执行一些你不知道的操作。安装前务必把脚本从头到尾读一遍。
第二类是宣传“一键搞定渗透测试”的。这类技能看着炫酷，但我建议只在明确授权、完全合规的测试环境里使用。安全自动化是个严肃话题，别把它变成给自己挖坑的工具。我个人的原则是：凡是要碰他人系统的，一律手动确认每一步，不用全自动 Skill。
第三类是对模型版本有隐性依赖的。有的 Skill 在 Claude 3.5 上运行良好，换到新模型反而频繁出错。装完之后一定要在最小案例上跑一遍，别等到紧急任务时才发现不兼容。
5. 实测踩坑记录：Skill 装了不等于能用
5.1 安装了但 AI 死活不调用，问题出在 description
我先说一个最普遍的问题：装了 Skill，但 AI 跟没装一样。
我的排查链路一般是这样：先确认 Skill 真的被加载了，可以用npx skills list查看，也可以直接问 AI 当前有哪些可用技能。如果列表里有，但任务里不调用，问题基本锁定在 description 的匹配度上。
接着我会做一个小实验：用一个最简单、最直白的触发句，比如“帮我写这个函数的单测”，看 AI 会不会调用。如果这样都不调用，说明 description 里的关键词和我的表达方式没对齐。此时我会重新改写 description，把用户习惯说的词都列进去，同时加一些反面示例。改完之后不用重新安装，直接新开一个会话就能生效。
5.2 脚本依赖装不上：runtime 与权限的坑
第二个高频坑是 Skill 里的脚本跑不起来。最常见的原因是环境不一致。举例来说，某个 Skill 的scripts/check.py里用了 Python 3.11 才有的语法，但你机器上默认 Python 是 3.9，一执行就报语法错误。解决办法很简单，在 SKILL.md 里明确写出运行环境和依赖安装命令：
required-python: ">=3.11"第三个坑是执行权限。从 GitHub 克隆的仓库，文件默认可能没有execute权限，AI 调用时会提示 permission denied。如果你在 macOS 或 Linux 上安装，记得手动检查：
chmod +x ~/.claude/skills/my-skill/scripts/*另外，用npx skills add安装的 Skill 有时会被放到 npm 的缓存路径，而不是你预期的目录。这时候别硬找，直接看npx skills list输出的实际路径。
5.3 Claude Code、Codex、OpenCode 三套格式并不通用
这是一个很多人不知道的细节。同样是 Skills，Claude Code 用的是~/.claude/skills，Codex 有自己的一套目录约定，OpenCode 也搞了一套兼容方案。你以为写一个 SKILL.md 到处能用，实际上每个平台的加载逻辑和字段支持度都有细微差别。
我给个对比表格，方便你快速判断：
| 平台 | 目录示例 | SKILL.md 支持情况 | 主要注意点 |
|---|---|---|---|
| Claude Code | ~/.claude/skills/<name>/SKILL.md | 完整支持 | description 触发最敏感 |
| Codex | 项目内.agents/skills | 部分字段支持 | allowed-tools 可能被忽略 |
| OpenCode | 插件目录或项目.opencode/skills | 兼容为主 | prompt 模板能力更强 |
实际操作中，跨平台使用的最稳妥策略是：SKILL.md 只写 name、description 和正文流程，不用平台专属字段；脚本用 Python 或 Shell 这类通用运行时；路径引用一律用相对路径。
5.4 团队协作时，Skill 仓库的版本维护方案
最后聊聊团队场景。当你把 Skill 从个人玩具变成团队资产时，会遇到版本问题。我自己的做法是把所有 Skill 收进一个 Git 仓库，目录按团队命名空间组织：
team-skills/ ├── frontend/ │ └── design-to-code/ ├── testing/ │ └── test-case-generator/ └── README.md每次更新 Skill 后，我会在SKILL.md的 YAML 头里加一个version字段，然后在变更记录里写明“改了什么、为什么改”。这样当有人反馈“某个 Skill 突然不好用了”，第一件事不是推翻重写，而是看最近一次变更改动了哪个环节，回滚成本大大降低。
版本管理还有一个好处：新成员入职时，不用靠口口相传去学“我们团队是怎么让 AI 干活的”，直接 clone 仓库，按 README 装一遍，就能获得和团队一致的能力基线。这对于强调工程化、强调可复制的团队来说，价值甚至比某个具体 Skill 本身更大。
我自己的体会是：Skills 最迷人的地方不在于某个技能包有多强，而在于它把“经验”这种原本只存在于人脑里的东西，变成了可分发、可版本化、可审查的实物。以后换项目、换机器、换队友，这套技能库都能跟着你走。如果你还没动手写过第一个 Skill，建议今天就从一个小小的场景开始，不要追求宏大，把一个让 AI 稳定输出特定格式数据的技能跑通，你就已经领先大多数还在靠提示词硬扛的人了。
