1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区、AI 工具群还是各种折腾效率工具的圈子里“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到Claude、Agent Skills、SKILL.md、Claude Code、superpower skills、数学建模skills推荐、ai漫剧常用skills……这些词全都指向同一个东西——给 AI 智能体Agent装载的“技能包”。说白了skills 就是一套写给 AI 看的“操作手册”。它用结构化的方式告诉 AI遇到某类任务时应该按什么步骤做、调用哪些工具、注意哪些坑。你可以把它理解成给一个新员工发的 SOP 文档只不过这个员工是 AI而这份文档的格式是SKILL.md。我最早接触这个概念是在折腾 Claude Code 的时候。当时想让 Claude 帮我处理一些重复性的代码审查工作每次都要重新写一遍提示词烦得不行。后来发现社区里已经有人把这类任务封装成了 skill直接丢进指定目录就能用那一刻的感觉就像发现了新大陆。再后来superpower skills、codex nature skills、opencode skills这些不同平台和场景下的技能库陆续冒出来skills 生态一下子就热闹了。这篇文章我想从实操角度把 skills 这件事讲透。不管你是刚听说Claude Code想试试水的新手还是已经在用Claude但还没碰过 skills 的老用户或者你是做数学建模、前端开发、AI 漫剧这类具体场景想找现成技能包的从业者下面这些内容应该都能帮到你。我会重点讲清楚skills 的核心结构长什么样、怎么从零写一个自己的 skill、怎么安装别人做好的 skill、以及我在实际使用中踩过的那些坑。2. skills 的核心结构拆解SKILL.md 到底怎么写2.1 一个 skill 的最小构成单元先看最核心的问题一个 skill 到底由什么组成答案比你想的简单——一个文件夹里面放一个SKILL.md文件再加上可选的辅助脚本和资源文件。SKILL.md是整个 skill 的入口和说明书。它的格式是 Markdown 加 YAML frontmatter结构大概长这样--- name: code-review-helper description: 对指定代码文件进行结构化审查输出问题清单和改进建议 --- # 代码审查助手 ## 使用场景 当用户要求审查代码质量、查找潜在 bug 或提出改进建议时使用本技能。 ## 操作步骤 1. 读取用户指定的代码文件 2. 按以下维度逐项检查 - 变量命名是否清晰 - 是否存在未处理的边界条件 - 错误处理是否完整 - 是否有明显的性能问题 3. 输出格式按严重程度分级列出问题每条附带修改建议 ## 注意事项 - 不要自动修改代码只输出建议 - 如果文件超过 500 行先询问用户是否只审查关键部分这个结构看起来平平无奇但每一部分都有它存在的理由。name和description放在 frontmatter 里是为了让 AI 在决定是否调用这个 skill 时能快速判断。下面的正文则是给 AI 看的详细指令。我试过把同样的内容直接写在对话里让 Claude 执行效果远不如封装成 skill。原因在于skill 会被系统预先加载到上下文里AI 对它的“记忆”更牢固执行时不容易跑偏。这就像你临时口头交代一件事和写进工作手册里的区别。2.2 为什么是 Markdown 而不是 JSON 或 YAML有人可能会问既然是给机器看的为什么不用更结构化的 JSON我一开始也有这个疑问后来想明白了——skills 的使用者不只是机器还有人。Markdown 的好处是人和 AI 都能读。你写了一个 skill同事想看看它干了什么直接打开SKILL.md就能看懂不需要额外的文档。而且 Markdown 天然支持自然语言描述AI 对自然语言指令的理解能力已经足够强没必要把所有东西都塞进严格的键值对里。另一个实际原因是skills 经常需要包含示例、注意事项、边界情况说明这些内容用 JSON 表达会非常别扭。Markdown 的段落、列表、引用块刚好适合这种“半结构化”的表达。2.3 辅助文件什么时候需要不是所有 skill 都只有一个SKILL.md。当你的 skill 需要执行具体操作时通常会搭配脚本文件。比如一个“批量重命名文件”的 skill可能会包含一个rename.py然后在SKILL.md里写明“调用同目录下的 rename.py 并传入参数”。我的经验是能用自然语言描述清楚的逻辑就不要写脚本。脚本会增加维护成本而且一旦环境变化比如 Python 版本不同就容易出问题。只有当任务涉及精确计算、文件操作、API 调用这类 AI 直接做容易出错的事情时才值得写辅助脚本。3. 从零手写一个 skill完整流程和关键决策3.1 先想清楚这个 skill 解决什么问题写 skill 最容易犯的错误是“为了写而写”。我见过有人把“帮我写周报”这种一次性任务也封装成 skill结果用两次就扔了。一个好的 skill 应该满足两个条件任务会重复出现且每次的执行逻辑基本一致。举个例子我做前端开发时经常需要把设计稿的标注转换成 CSS 变量。这个任务每次的流程都一样读取标注数据、按命名规范转换、输出变量文件。这种就非常适合做成 skill。而“帮我设计一个页面布局”这种每次需求都不同的任务就不适合。3.2 写 description 的讲究description这一行看似简单实际上直接影响 skill 会不会被正确触发。我踩过的坑是description 写得太模糊导致 AI 在该用的时候不用不该用的时候乱用。好的 description 应该包含三个要素做什么、什么时候用、输出什么。对比一下差的写法description: 处理代码好的写法description: 对 Python 代码进行 PEP8 风格检查和重构建议当用户要求代码审查或提到代码规范时使用第二种写法明确限定了语言Python、任务类型风格检查和重构建议、触发条件用户提到代码审查或规范AI 判断起来就准确得多。3.3 操作步骤的粒度控制写操作步骤时粒度太粗 AI 会自由发挥粒度太细又会让 skill 变得僵化。我的经验法则是关键决策点写清楚执行细节留给 AI。比如写一个“数据清洗”的 skill我会写明必须先检查缺失值比例超过 30% 的列要询问用户是否保留数值列和类别列要用不同的填充策略输出清洗报告但不会写明“用 pandas 的 fillna 方法参数用 methodffill”。因为具体用什么库、什么参数AI 根据实际数据情况判断可能比我预设的更好。3.4 一个完整示例数学建模辅助 skill结合热搜词里“数学建模skills推荐”这个需求我写一个实际可用的例子--- name: math-modeling-assistant description: 辅助数学建模竞赛提供模型选择建议、论文结构规划和代码框架生成 --- # 数学建模辅助 ## 使用场景 用户正在准备数学建模竞赛需要模型选型、论文框架或代码实现方面的帮助。 ## 工作流程 ### 第一步问题分析 - 阅读题目识别问题类型优化、预测、评价、分类等 - 列出已知条件、目标函数、约束条件 - 如果题目信息不完整向用户确认 ### 第二步模型推荐 根据问题类型推荐 2-3 个候选模型说明各自优缺点 - 优化类线性规划、整数规划、遗传算法、粒子群优化 - 预测类时间序列、回归分析、神经网络、灰色预测 - 评价类层次分析法、熵权法、TOPSIS、模糊综合评价 ### 第三步论文框架 按标准竞赛论文结构输出大纲 摘要、问题重述、问题分析、模型假设、符号说明、模型建立与求解、模型检验、灵敏度分析、模型评价与推广 ### 第四步代码框架 生成对应模型的 Python 代码骨架包含数据读取、模型定义、求解、结果可视化四个部分。 ## 注意事项 - 不要直接给出完整论文只提供框架和思路 - 模型推荐要结合题目数据特点不要盲目推荐复杂模型 - 代码框架要包含注释方便用户理解和修改这个 skill 我实际用过几次最大的感受是它把“从零开始想”变成了“在框架上填充”效率提升非常明显。尤其是论文框架那部分直接省掉了大量纠结结构的时间。4. 安装和使用现成 skills各平台操作指南4.1 Claude Code 下的 skills 安装Claude Code是目前 skills 生态最活跃的平台之一。安装 skill 的基本流程是找到 skill 的存放目录。在 Claude Code 中通常是项目根目录下的.claude/skills/或者用户主目录下的~/.claude/skills/把下载的 skill 文件夹整个复制进去重启 Claude Code 或者重新加载会话这里有个容易踩的坑目录层级。有些 skill 压缩包解压后会多一层文件夹比如code-review-helper/code-review-helper/SKILL.md这样 Claude Code 是识别不到的。正确的结构应该是skills/code-review-helper/SKILL.md。另外热搜词里有人问“claude code怎么手动装github上的skills”答案就是从 GitHub 下载仓库后找到包含SKILL.md的那个文件夹整个复制到 skills 目录下。如果仓库里有很多 skill就挑你需要的复制不用全装。4.2 验证 skill 是否生效装完之后怎么确认 skill 被正确加载了我的做法是直接问 AI。在对话里输入“你现在有哪些可用的 skills”如果安装成功AI 会列出已加载的 skill 名称和描述。如果没生效按这个顺序排查检查SKILL.md的 frontmatter 格式是否正确---不能少name和description必须有检查文件编码是否为 UTF-8检查目录层级是否多了一层检查是否有语法错误导致整个文件解析失败4.3 不同平台的差异除了 Claude Codeopencode skills、codex nature skills等平台也支持类似的机制但目录位置和加载方式略有不同。共同点是核心都是SKILL.md文件差异主要在存放路径和触发机制上。我的建议是如果你主要用某个平台就按那个平台的文档来。如果多个平台都用可以把 skill 放在一个统一的仓库里管理用脚本同步到各个平台的目录下。这样维护一份源文件就够了。5. 常见问题与排查技巧实录5.1 skill 不触发怎么办这是最高频的问题。AI 没有按预期调用你的 skill通常有三个原因问题现象可能原因解决方法完全不触发description 太模糊重写 description加入具体触发词偶尔触发与其他 skill 功能重叠明确区分各 skill 的适用边界触发但执行不对操作步骤描述有歧义细化关键步骤增加示例我遇到过一次典型情况写了一个“生成 API 文档”的 skill但 AI 总是用另一个通用的“写文档”skill。后来发现是两个 skill 的 description 都包含了“文档”这个词AI 分不清该用哪个。解决办法是在 API 文档 skill 的 description 里加上“当用户提到 API、接口、端点时使用”把触发条件收窄。5.2 skill 之间冲突怎么处理当你装了很多 skill 之后冲突几乎不可避免。我的处理原则是功能相近的只保留一个或者明确划分使用场景。比如同时装了“代码审查”和“代码优化”两个 skill前者关注规范问题后者关注性能问题。如果 description 没写清楚AI 可能在该做性能优化时调用了代码审查 skill。这时候要么合并成一个 skill 用条件分支处理要么在各自的 description 里写清楚“仅用于 XX 场景”。5.3 性能问题skill 太多会不会拖慢响应会。每个 skill 的SKILL.md内容都会被加载到上下文里skill 越多占用的 token 越多AI 的响应速度和准确性都会受影响。我的经验是同时启用的 skill 控制在 10 个以内不常用的及时禁用或移出目录。热搜词里有个“tibo关于清理skills的方法推荐”虽然我没看过具体内容但清理思路无非就是定期审查、合并重复、归档不用的。我自己的做法是建一个skills-archive文件夹把暂时不用的 skill 移过去需要时再移回来。5.4 跨平台兼容性注意事项如果你写的 skill 打算分享给别人用要注意不同平台的兼容性。主要差异点文件路径分隔符Windows 用反斜杠其他用正斜杠脚本执行环境Python 版本、依赖库特殊指令的写法有些平台支持特定标记换平台就失效我的做法是尽量用纯自然语言描述少依赖平台特有功能。这样写出来的 skill 通用性最强换个平台基本都能用。6. 进阶玩法把 skills 组合成工作流单个 skill 解决单个问题但实际工作中往往需要多个 skill 配合。比如做一次完整的数据分析项目可能涉及数据清洗 skill、特征工程 skill、模型训练 skill、结果可视化 skill。我的做法是写一个“元 skill”在SKILL.md里定义整个工作流的步骤每一步引用对应的子 skill。这样 AI 在执行时会按顺序调用各个子 skill形成流水线。这种组合方式的好处是每个子 skill 可以独立维护和复用工作流 skill 只负责编排。改一个子 skill 的逻辑所有用到它的工作流都会自动更新。不过要注意组合 skill 的调试比单个 skill 麻烦。我的建议是先把每个子 skill 单独测试通过再组装成工作流。否则出了问题很难定位是哪个环节的毛病。7. 我个人的一些实操心得写了这么多 skill有几个体会特别深。第一不要追求大而全。我一开始写了一个“全能编程助手”skill想把代码生成、审查、调试、文档全包进去。结果 AI 执行时经常混淆任务类型效果还不如不装。后来拆成四个独立 skill每个只做一件事反而准确率高得多。第二description 值得反复打磨。我有个习惯写完 skill 后用不同的问法测试十几次看触发率如何。如果发现该触发的时候没触发就回去改 description。这个过程很枯燥但效果立竿见影。第三版本管理很重要。skill 也是代码改坏了要能回滚。我用 Git 管理 skills 目录每次修改都提交出问题随时回退。这个习惯帮我省过好几次事。第四别忽视社区的力量。热搜词里提到的superpower skills、typesafe ai skills github这些都是社区沉淀下来的优质资源。与其自己从零写不如先看看有没有现成的在别人的基础上改比从头造轮子快得多。最后分享一个小技巧如果你不确定某个任务适不适合做成 skill先手动做三遍。如果三遍的流程基本一致那就值得封装如果每次都不一样说明这个任务还没形成稳定模式再等等。这个判断方法我用了很多次基本没出过错。