1. 为什么我最后决定认真研究 skills最早接触 AI 编程助手的时候我跟大多数人一样觉得只要会写 prompt 就行把需求描述清楚AI 就能干活。但真实项目一跑起来就露馅了同一类任务我每次都要把背景、规范、注意事项重新讲一遍讲少了它就给你自由发挥讲多了又耽误时间而且不同 session 里它的表现完全不稳定。有一段时间我甚至觉得AI 助手就是个“记性不好的实习生”。直到我看到有人提到 skills 这个词才意识到问题不在模型本身而在于我没有把经验“结构化”地喂给它。简单的说skills 就是把一套完整的工作流、领域知识、参考规范和校验标准打包成一个文件夹让 AI 在遇到对应任务时自动加载并照着执行。它跟你在对话框里临时复制一段长文不一样——skills 是长期驻留在工程里的“技能库”是可复用、可分享、可版本管理的东西。我也陆陆续续在 GitHub 上看到各种 skills 仓库比如后面我会详细讲的 superpower skills、typesafe ai skills还有一些专门服务数学建模、前端开发和 AI 漫剧工作流的技能包。但网上信息很零散多数人跟我一样卡在“知道有这东西但不知道装在哪儿、怎么用、怎么自己写”这一步。这篇文章就当作我自己的踩坑记录把这些东西一次讲清楚skills 的底层结构是什么、如何从 GitHub 手动装到本地、哪些领域最值得装、怎么写自己的第一个 skill以及如何做清理和维护。不管你是做前端开发的、搞数据建模的还是用 AI 做内容生产的人只要你的工作里已经有大量重复的 AI 交互流程我都建议你花点时间把这套东西理一遍。它不需要你会写很复杂的代码只需要你愿意把平时的经验整理成 Markdown 文件收益是长线的每个新项目都能站在以前的最佳实践上出发而不是每次从零开始教 AI 干活。2. 拆开一个 skill 看结构它到底长什么样要弄明白怎么装 skills最好先花十分钟看看它的内部结构。我见过不少人把 skills 想得很玄乎觉得它是什么黑魔法或者模型微调技术其实不是。skills 本质上就是一套“按约定组织的提示词 参考资料 可执行脚本”核心就一个文件SKILL.md。2.1 SKILL.md 的骨架与元信息任何一个 skill 目录里最核心的必然是 SKILL.md 文件。它通常由两部分组成开头的 YAML frontmatter以及后面的 Markdown 正文。frontmatter 里最要紧的是 name 和 description 两个字段我就是因为没搞懂这俩字段的职责导致最开始装了好几个 skill 都不生效。name 是这个技能的唯一标识建议用短横线风格命名比如code-review、frontend-debug。description 是给模型看的“召唤条件”模型需要根据用户的当前请求来判断是否加载这个 skill所以 description 里必须写清楚这个技能解决什么问题、在什么时候应该被触发。比如一个负责代码审查的 skill它的 description 可以写“当用户请求对 JavaScript/TypeScript 项目进行代码审查、找出潜在 bug 或安全问题时使用”。如果 description 写得太含糊比如“帮助用户处理代码”那模型大概率根本不会触发它。然后就是正文部分。正文里是一套完整的执行说明包括工作流程、输出格式、必须遵守的规则甚至可以直接给出示例代码片段。模型一旦匹配到这个 skill就会把这些内容作为上下文的一部分来指导行为。你可以把它理解为一份“给 AI 看的岗位说明书”不只是告诉它要做什么还要告诉它按什么顺序做、做到什么程度、遇到特殊情况怎么办。2.2 正文、模板、脚本三层内容怎么分工一个比较成熟的 skill 文件夹通常不只包含 SKILL.md还会有模板文件、参考文档和辅助脚本三层内容各司其职。第一层是主线说明也就是 SKILL.md 正文里写的逐步操作指令。第二层是模板和参考文件用来保证输出的一致性比如你写一个“项目周报生成”的 skill那里面就可以带一份周报模板AI 会按照这个模板填内容而不是自己发明排版。第三层是辅助脚本适合那些需要确定性逻辑的操作比如批量重命名文件、跑测试、调用接口等脚本可以保证步骤不漂移。我自己更习惯于这样组织一个 skill 目录my-skill/ ├── SKILL.md # 技能主文件模型优先读取 ├── references/ # 参考资料按需引用 │ └── style-guide.md ├── templates/ # 输出模板 │ └── report.md └── scripts/ # 辅助脚本 └── validate.py这种结构的好处是职责分离模型负责按 SKILL.md 理解任务需要稳定数据时引入 references需要统一格式时套用 templates需要精确计算或操作时调用 scripts。你以后维护也好办改模板不用动主流程改逻辑不用翻资料。2.3 和普通 system prompt、MCP 工具的区别很多人容易把 skills、system prompt 和 MCP 混在一起我起初也犯迷糊后来找到了一个比较清晰的区分方式system prompt 是“常驻的价值观和边界”skills 是“按需加载的领域技能”MCP 是“给模型外接能力的工具插槽”。用生活类比就是system prompt 像公司门口的员工手册所有员工进来都要遵守的基本规则skills 是各个岗位的专业 SOP只有你干对应岗位的活儿时才翻出来看MCP 则像是工具箱里的电钻、扳手——模型本身不会电钻这个动作但它可以通过 MCP 这个接口去调用真实工具。skills 不需要联网、不需要起服务它就是一个本地文件夹加载成本极低。这也是为什么 skills 很适合沉淀个人或团队经验而 MCP 更适合接外部系统。3. 手动安装 GitHub skills 的实操路径现在进入正题手动从 GitHub 装一个 skills 到本地。很多刚接触的人以为需要什么特殊工具或者复杂的命令行操作其实完全不需要整个流程就是“找仓库、拿文件、放目录、验证”四步。下面我以 Claude Code 环境为例讲一套通用做法因为它的目录规范和社区习惯都相对统一。3.1 先找到靠谱的 skills 仓库GitHub 上的 skills 仓库数量增长很快但质量参差不齐。我踩过的坑是看到 star 数高就无脑 clone结果里面有大量过时内容或者跟自己的工具链完全不兼容。选仓库我一般看三样README 里有没有清晰的目录说明、有没有持续更新记录、每个 skill 的 SKILL.md 是不是独立且结构完整的。常见的渠道包括几个方向一个是综合性技能集合像 superpower skills 这种大型仓库里面分门别类装了写作、编程、项目管理等几十个技能适合批量体验另一个是垂直类技能库比如专门给数学建模竞赛用的建模辅助技能给前端开发的代码审查和重构技能给 AI 漫剧创作的分镜、人设和提示词生成技能。还有一个容易忽略的是团队内部仓库很多公司会把内部工作流沉淀成 skills 放进私有 Git 仓库这才是最能发挥价值的地方。以“如何学习 skills”为关键词在 GitHub 上搜也能找到一些专门讲解技能开发的仓库这类仓库很适合上手研究因为它的 README 基本就是一份 skills 开发教程。总之收藏夹里放三四个高质量来源就够了不要贪多否则后面维护都是负担。3.2 克隆、拷贝和目录放置找到需要的仓库之后先不要急着整个塞进你的项目里我吃过这个亏。正确做法是先在本地选一个专门存放第三方 skills 的目录比如git clone https://github.com/example/skills-repo.git ~/skills-repo然后进入仓库看清楚目录结构只把你需要的 skill 文件夹复制出来。比如仓库里面有code-review、report-generator、>cp -r ~/skills-repo/data-analysis ~/.claude/skills/这里有个容易混淆的地方.claude/skills/下每个子目录代表一个 skill子目录里要直接放 SKILL.md而不是再嵌套一层同名目录。也就是最终应该是~/.claude/skills/data-analysis/SKILL.md这个样子。如果你复制出来是~/skills-repo/data-analysis/SKILL.md这种结构那其实直接复制>~/.claude/skills/frontend-deps-audit/ └── SKILL.mdSKILL.md 内容大致如下--- name: frontend-deps-audit description: 当用户要求检查前端项目的依赖安全、版本合理性或需要生成依赖升级建议时使用。尤其适用于 package.json 中有较多过时依赖或安全告警的情况。 --- # 前端依赖审计 ## 背景 本技能用于快速判断前端项目依赖健康状况减少人工逐条核对 package.json 的时间。 ## 流程 1. 读取 package.json 和 lockfile。 2. 检查是否存在已知的高风险版本参考当前主流生态的公告信息。 3. 按“修复建议 - 影响范围 - 改动成本”三个维度输出评估。 4. 对可安全升级的依赖给出具体版本建议对破坏性升级给出风险提示。 ## 规则 - 不要在没有数据支撑的情况下建议升级 major 版本。 - 每次输出必须包含“风险等级”字段取值低 / 中 / 高。 - 如果存在 lockfile 与 package.json 不一致必须首先指出。 ## 输出格式 | 依赖名 | 当前版本 | 建议操作 | 风险等级 | 说明 |这样一个 skill 写下来可能就几十行但实际用起来生成的报告比以前让 AI 自由发挥要靠谱得多。你会发现真正有价值的不是那些大而全的技能而是这种“解决你一个具体痛点”的小技能。5.3 容易踩的三个坑第一个坑是 description 写得像报菜名堆砌了各种关键词但没说明具体触发条件。模型匹配技能的时候靠的是语义相关性不是搜索引擎。所以描述要具体最好包含“当用户……”这样的句式。第二个坑是正文里全是抽象原则没有给示例。对模型来说示例比指令更有说服力。你在规则里写十句“输出应简洁明了”不如直接给它一个“简洁明了”的例子。第三个坑是技能里面带着过时的操作习惯。比如你以前构建工具是 webpack后来换成了 Vite但技能里还写着“执行 webpack 构建”那模型就会被带偏。写技能有一点像写测试用例你希望 AI 在面对某种输入时稳定地做出某种输出那就要把边界条件写清楚而不只是描述理想情况。慢慢你会找到感觉越写越快。6. 使用、清理与版本管理装了一堆 skills 之后新的问题出现了怎么管理它们我见过有人一口气装了上百个技能结果很多技能彼此冲突或者根本用不上不仅占了篇幅还可能让模型在匹配时“选择困难”。所以我专门讲讲使用、清理和版本管理这点事。6.1 如何知道 skill 有没有生效判断一个 skill 到底有没有生效最简单的方法就是主动触发它然后看模型的行为是否符合 SKILL.md 里写的流程。比如你的技能要求先输出背景说明再给建议如果模型直接给了建议而跳过了背景说明那大概率没加载成功或者 description 的匹配出了问题。还有一种情况是多个技能的描述存在重叠模型可能加载了描述更宽泛的那个导致你的新技能直接“失灵”。遇到这种情况我会优先检查描述字段是否足够具体。另外建议每次新增技能后不要马上扎进正式任务里去验证而是开一个干净的对话窗口故意触发一次测试用最小代价确认加载情况。长期经验告诉我这个“测试习惯”能为你节省大量排查时间。6.2 为什么要定期清理技能清理技能这件事社区里讨论挺多的我看到 tibo 也分享过相关的方法和推荐。核心观点其实就一句话技能是上下文的一部分你装得越多模型在匹配时的噪音就越大反而可能降低输出质量。这就像工具箱里塞满了扳手真要用那把 14 号的时候反而要找半天。我的清理策略是按季度来。每个季度初我会把近三个月实际触发过的技能列出来触发次数为零的直接移到一个_archive文件夹而不是删除免得以后后悔。三个月后又确认用不上的就彻底删除。这样既不会误删也保证了当前技能列表永远保持精简。还有一个更激进的技巧把大型技能包拆散。很多时候你安装一个几十个技能的大仓库实际用到的可能只有三个。与其整体保留不如把这三个独立复制出来然后删掉原仓库目录。这样你的配置里就只剩下真正有用的东西不会因为大仓库里某几个技能描述过于宽泛而干扰日常任务。6.3 团队里如何维护一份 skills 库如果你的团队开始推广使用 skills我建议把它当成代码一样纳入版本管理。最开始可以单独建一个skills仓库里面按技能分类建目录每个技能带上 README 说明适用场景和维护人。等稳定下来之后可以考虑把那些和项目强相关的技能直接放进项目仓库的.claude/skills/目录里这样新成员 clone 项目的时候就自动拥有了项目级技能。团队维护还需要注意技能版本与工具版本的兼容问题。某些工具版本更新之后对 SKILL.md 的 frontmatter 字段要求可能会有变化。如果你的技能大量依赖特定字段或脚本建议在 README 里注明适用的工具版本范围避免同事升级工具后技能静默失效。还有一个协作细节多人维护同一份技能时最好约定审核标准。PR 的审查人重点检查 description 和规则部分是否清晰而不是内容多不多。一份技能文档写得再漂亮描述字段没写好模型匹配不到那一切都是白搭。最后想跟你分享一个小习惯我会把每次调试技能时发现的问题记在 SKILL.md 底部的“变更记录”里比如“v1.2 增加了对 monorepo 场景的判断”。这样做的好处是过几个月你回头看时能清楚这个技能为什么长成现在这样。写技能本身不难难的是让它持续贴合你的实际需求而这个记录习惯可以帮你保持清晰的迭代脉络。希望这篇文章能让你少走一些弯路早点用上真正适合自己的 skills。