常刷 AI 编程社区的朋友最近应该都有一种很强烈的体感同一个模型在别人手里像个靠谱的资深工程师在你手里却像刚入职三天、还不熟悉公司规范的实习生。它能把单点问题回答得很漂亮但一旦让它修改一个老项目、提交代码、配合团队规范干活输出就会变得又长又乱。这个差距很多时候不是模型能力造成的而是你少给模型递了一份“操作手册”。GitHub 上正在快速爆发的 skills就是这份“操作手册”的标准化形态。从公开数据看这类 skills 相关项目已经出现了 21 万 star、下载量超 1400 万次的现象级数据这已经完全不是小圈子里的自嗨。很多开发者发现给 AI 配上一套组织良好的 skills 之后生成代码的风格稳定了、审查更规范了、提交信息也像团队一起约好的一样整齐。这篇文章不是给你推荐某个工具。我想把 skills 这件事彻底讲明白它到底是什么、为什么突然火了、怎么手写、怎么接入工具链、有哪些坑。看完之后你可以直接动手做出第一个能改善 AI 代码质量的 skill。1. AI 写“屎山代码”的根源不是模型笨是缺工作流先说一个很多人踩过的坑让 AI 写一个独立的 Python 函数它写得又快又干净但让它在一个老项目里加功能时它可能会同时改十几个文件命名风格和项目里不一致不补测试也不考虑旧代码的兼容性。这不是模型突然变笨了。模型擅长的是“单点生成”并不天然擅长“在工程约束下持续工作”。当用户只给它一句话需求时它缺少三样东西项目规范、任务边界、工作流步骤。这三样东西恰恰是团队里资深工程师会隐式遵守的东西。如果用一句话总结 AI 生成代码的质量可以这样理解AI 生成质量 ≈ 模型能力 × 上下文质量 × 工作流约束模型能力大家差不多差异主要出在后两项。上下文质量指模型能看到的项目背景、代码风格、接口约定工作流约束指模型按什么步骤干活、输出什么格式、哪些不能做。纯 Prompt 方式的问题在于上下文是聊天式的、一次性的。今天告诉它“代码要写注释”明天它还是会忘团队里有人用中文注释有人用英文注释模型也很难稳定输出统一风格。你把规范写在一个超长系统提示词里模型确实能看到但它没有执行顺序也没有触发边界效果自然不稳定。Skills 要解决的就是这个问题。它不是一段临时提示词而是一个可版本化、可复用、可分发的“工作流插件”。当某个任务匹配到对应技能时模型会把技能里的操作手册加载进上下文按里面规定的流程执行。这意味着团队规范能从一个 Markdown 文件沉淀下来下次任何人、任何项目都能复用。2. 什么是 Skills给大模型的岗位说明书Skills 本质上是一个包含 SKILL.md 入口文件和可选辅助资源的目录。SKILL.md 开头的 YAML 元信息里name 是技能名称description 是给模型看的触发条件正文部分是给模型看的操作手册。没有 skills 时AI 像一个什么都会一点但不懂你公司流程的临时工有了 skills 后它像一个刚入职就领到岗位说明书和 SOP 的员工。2.1 SKILL.md 是入口一个最小可用的 Skills 目录长这样code-review-skill/ ├── SKILL.md └── reference/ └── checklist.mdSKILL.md 是最核心的文件。它决定了两件事description 决定模型何时调用这个 skill。正文决定模型调用后如何执行。现代 AI 编程工具会根据用户指令的语义与已安装技能的 description 做匹配。如果匹配成功工具就把整个 SKILL.md 和它引用的资源文件加载进模型上下文然后模型按里面的步骤执行。所以 description 必须要写得像搜索引擎的关键词一样准确描述触发场景正文要写得像给外包团队的需求说明清晰、无歧义、可执行。2.2 Skills、Prompt、插件与 MCP 的区别很多刚开始接触 skills 的读者容易把它和 Prompt、插件或 MCP 混在一起。它们其实是不同层级的东西概念本质解决什么问题典型示例Prompt一次性自然语言指令单次对话中约束模型“请你用 Python 写一个排序函数”Skills可复用的结构化工作流让模型在特定任务上按流程执行代码审查、提交信息规范化、测试生成插件IDE 扩展能力增强开发环境语法高亮、格式化工具、调试器MCPAgent 连接外部工具和数据的协议让模型能调用外部 API、数据库、文件系统查询商品库、读写 k8s 配置Skills 与 MCP 很容易被混为一谈但定位差别很大。MCP 解决的是“Agent 能碰什么”Skills 解决的是“Agent 会怎么想、怎么做”。你可以用 MCP 让模型读取数据库再用 Skills 规定它要带着哪套审查标准去分析这些数据。两者是配合关系。目前 Claude Code、Cursor、GitHub Copilot、Codex CLI、OpenCode 等主流 AI 编程工具都已经或正在以不同方式支持技能目录。这个趋势意味着 skills 正在变成 Agent 生态的“配置中心”。3. 为什么 Skills 能在 GitHub 成为爆款一个 Markdown 文件组成的技能包为什么能滚出 21 万 star、超 1400 万次下载级别的热度从社区反馈来看背后有几个很现实的驱动力。第一工具支持铺开了。之前写 AI 工作流可能需要写插件、开发专用框架现在主流工具开始原生识别 SKILL.md门槛从“写代码”降到了“写文档”。第二写一个 skill 的成本极低。很多有用的技能核心就是一个整理得足够清晰的 SKILL.md。前端开发、后端编码、测试用例生成、学术研究辅助、内容创作这些场景不需要你会写插件只要你会把流程讲清楚。第三可复用性很强。一段 Prompt 只能存在你的聊天记录里但一个 skill 可以放进 Git 仓库、分享给同事、发布到社区。团队知识从“口头经验”变成了“工程资产”。第四需求侧已经变了。越来越多团队关心的不再是“AI 能不能生成代码”而是“AI 生成的代码能不能直接进生产”。这就需要一个约束生成的机制skills 正好是这个缺口上最轻的补丁。更关键的是skills 让 AI 编程从“单轮对话”进入“可沉淀工程资产”阶段。单个技能可能不复杂但当团队积累了代码审查、提交规范、接口对接、数据库操作、发布检查等多个 skill 以后效果会产生复利模型对团队规范的符合度会越来越高人工 review 的成本会明显下降。4. 环境准备把 Skills 装进你的 AI 编程工具在动手写 skill 之前先确认两件事你用的工具是否支持 skills以及它读取哪个目录。如果你的工具还不支持 skills要么升级到新版本要么换一个支持的工具。如果网络访问 GitHub 不稳定导致下载失败请先确认本机网络是否能够正常访问 GitHub 官方仓库再换一个网络环境重试。4.1 工具选择与目录约定不同工具的技能目录名称略有差异。以 Claude Code 为例用户级技能目录通常是~/.claude/skills项目级技能目录通常是.claude/skillsCursor 等编辑器也提供了自己的技能目录配置。项目级目录适合跟随仓库分发团队 Clone 项目后自动启用相关技能。具体目录名不要凭记忆猜第一次使用前先查你所用工具的官方文档。这里的关键是理解“目录扫描机制”工具启动时会扫描指定目录下所有包含 SKILL.md 的子目录把它们注册为可用技能。4.2 建议目录结构无论使用哪个工具我都建议先按下面这种结构组织技能包~/.claude/skills/ ├── code-review/ │ ├── SKILL.md │ └── reference/ │ └── checklist.md ├── commit-message/ │ └── SKILL.md └── test-generator/ └── SKILL.md一个目录一个技能技能名用短横线连接。如果技能需要脚本资源建议放在 scripts 子目录里避免 SKILL.md 目录下太乱。4.3 用 Git 管理技能包Skills 是文本文件天然适合 Git 管理。把团队公共技能包放到独立仓库里代码和技能分开维护。更新技能时走 PR 评审合并后本地拉取即可生效。不要直接在生产机器上手工改技能因为这样失去了版本跟踪和回滚能力。如果技能只包含 Markdown 文件那不需要额外安装 Python 或 Node.js如果技能里包含了脚本则需要对应解释器。写 skill 不需要会写插件但如果你会用一点 Python 或 Shell技能能做的事情会更多。5. 完整示例手写一个代码审查 Skill纸上谈兵再多不如直接写一个真实可用的技能。下面我以“代码审查”为例带你从零创建一个 code-review-skill。这个技能在项目里复用价值很高也很适合理解 SKILL.md 的编写方式。5.1 创建目录先创建一个空项目目录mkdir -p code-review-skill/reference cd code-review-skill5.2 编写 SKILL.md创建SKILL.md内容如下--- name: code-review description: 当用户要求审查代码、检查 Pull Request 或希望在合并前进行代码评审时按安全、性能、可维护性、测试四个维度输出结构化评审结果。 --- # Code Review Skill ## 工作流程 1. 先阅读代码和上下文不要只盯着单个函数。 2. 依次检查以下四个维度 - 安全性输入校验、敏感信息、命令注入、越权访问等。 - 性能循环复杂度、N1 查询、资源释放、缓存使用等。 - 可维护性命名一致性、分层清晰、重复代码、依赖方向、注释质量等。 - 测试关键分支是否有测试覆盖、异常路径是否完整、断言是否有效。 3. 输出格式 - 开头给出总体结论通过 / 需修改 / 需要讨论。 - 按严重程度分类列出问题P0 阻断、P1 必须修改、P2 建议优化。 - 每个问题给出文件路径、大致行号、问题描述、修改建议。 ## 注意事项 - 不要修改代码本身只输出审查意见。 - 对不确定的问题标记为“需确认”不要武断。 - 如果代码涉及数据库变更、权限配置或生产环境操作在审查意见中额外标注“高风险变更需测试环境验证”。这个 SKILL.md 里最关键的是 description。它描述了触发场景和输出承诺这样模型才能在你问“帮我看看这段代码”时准确唤起技能。正文里用“先……再……最后……”给出执行顺序比直接丢一堆要点更有效。5.3 添加参考清单创建reference/checklist.md把常见问题清单单独拆出来。这样 SKILL.md 保持简洁模型需要更细的检查项时可以引用这个文件。# 代码检查清单 ## 安全 - 是否对用户输入做了校验 - 是否直接拼接 SQL、命令或 HTML - 是否在日志中打印了密钥、Token、手机号等敏感信息 - 是否缺乏权限判断存在越权访问 ## 性能 - 是否存在 N1 查询或高复杂度循环 - 大对象是否及时释放 - 是否缺少缓存或使用了不合适的缓存策略 ## 可维护性 - 命名是否与项目风格一致 - 是否有明显重复代码可以抽取 - 依赖方向是否合理有没有循环依赖 - 注释是否解释了“为什么”而非重复“是什么” ## 测试 - 新增关键分支是否有单元测试 - 异常路径和边界条件是否覆盖 - 断言是否验证了业务结果而非实现细节这种拆法还有一个好处团队要更新检查项时只需要改 checklist.md不需要重新编辑 SKILL.md 主文件。5.4 把示例跑起来把code-review-skill放到工具支持的技能目录后重新打开一个会话然后说请用 code-review 技能审查一下当前分支的 diff。如果技能生效模型会按 SKILL.md 里规定的四维度和输出格式返回结果。如果模型没有触发技能大概率是 description 写得太泛或者技能目录没有被正确扫描。6. 团队场景规范 Commit Message 的 Skill除了代码审查团队里最容易直接见效的 skill 是提交信息规范化。大多数团队的 commit message 都是任意的有人写中文有人写英文有人只写“fix”过两个月回头看完全无法定位变更动机。与其每次去强调规范不如直接写一个 commit-message skill让 AI 根据 git diff 自动生成符合规范的提交信息。创建commit-message/SKILL.md--- name: commit-message description: 当用户要求生成提交信息、写 commit message、或者准备提交代码时根据 git diff 生成符合 Conventional Commits 规范的提交信息。 --- # Commit Message Skill ## 工作流程 1. 执行 git diff 和 git status查看暂存区变更。 2. 判断本次变更的类型 - feat新功能 - fix修复问题 - docs文档变更 - refactor重构 - test测试相关 - chore构建或辅助工具变更 - perf性能优化 3. 解析变更重点提炼出用户可见的影响不要罗列文件清单。 4. 输出提交信息格式如下 - 标题type(scope): 摘要不超过 50 个字符。 - 正文说明变更动机和影响范围不要写“修改了 xxx 文件”。 ## 示例 feat(user): 增加用户登录连续失败锁定 连续失败超过 5 次后锁定账号 15 分钟防止暴力破解。 锁定后会发送邮件提醒用户。这个技能的价值在于它把团队已经达成共识的提交规范直接内化到模型行为里。以后团队里每个人提交的代码都会自动采用同一种格式代码审查和版本回溯都更轻松。需要提醒的是提交信息只是辅助。即使 AI 生成了规范的 commit message提交前仍要人工确认内容是否准确尤其是涉及数据库迁移、配置变更、生产环境相关提交时不要只依赖 AI 的判断。7. 安装、启用、验证与常见问题排查写好了 skill接下来就是接入工具链和验证效果。7.1 安装与启用以 Claude Code 这类支持用户级技能目录的工具为例可以把编写好的技能复制到用户级技能目录mkdir -p ~/.claude/skills/code-review cp -r code-review-skill/. ~/.claude/skills/code-review/如果你希望技能只对某个项目生效可以复制到项目级目录。不同工具的目录名称不同具体以你所用工具的官方文档为准。安装完成后重启 AI 编程工具或者新开一个会话。大多数工具不会要求你手动注册它会自动扫描技能目录。7.2 效果验证验证一个 skill 是否生效有两种方式。第一种直接询问模型请列出你当前已加载的 skills。如果它能完整回答出code-review和commit-message说明技能已经被扫描进上下文。第二种用一个小任务触发。打开一个项目选中一段有明显问题的代码然后说请对这段代码做一次 code review按已加载的 code-review 技能执行。判断成功的标准是看输出格式是否和 SKILL.md 里规定的一致是否有总体结论、是否按 P0/P1/P2 分类、是否给出文件路径和修改建议。如果输出只是普通聊天式的点评说明技能没有正确触发。7.3 常见问题排查表问题现象可能原因排查方式解决方案技能没生效技能目录不对检查工具文档确认扫描的是哪个目录把技能复制到正确目录description 写得太泛模型无法判断何时调用检查 SKILL.md 开头的 description把触发场景写具体开头用动词技能触发了但输出不稳定正文流程不够清晰查看模型实际输出和 SKILL.md 的差异补充执行顺序、输出格式、禁止事项与其他全局规则冲突全局指令优先级更高检查工具的全局设置和技能内容统一规范或在 SKILL.md 中明确特殊规则技能包含脚本但执行失败缺少依赖或 Python 环境查看脚本报错日志安装依赖或者在技能目录中补充环境说明下载技能包失败网络无法正常访问 GitHub 官方仓库先确认网络状态更换网络环境后重试如果技能没生效第一步不是改 SKILL.md而是先确认扫描路径。很多人花了半天优化 desc最后发现技能根本没有被扫到。8. 最佳实践、安全边界与后续学习方向到了这一步你已经能写出可用的 skill 了。接下来是让技能从“能用”变成“好用”的一些经验。8.1 最佳实践一个技能只做一件事。不要把代码审查、提交信息、测试生成全部塞进一个 SKILL.md。单一职责的技能更容易维护也更容易被模型准确唤起。description 要写得像一个触发词索引。建议格式是“当用户要求……时按……执行”。开头用动词越具体越好。比如“当用户要求审查代码、检查 Pull Request 或希望在合并前进行代码评审时”这样模型在多种相近表达下都能触发。SKILL.md 不要写太长。模型加载技能后长篇大论会稀释重点。能在 reference 里拆分的就拆分出去。实践下来主文件控制在几十行到一两百行的可读性最佳。用示例驱动。每个重要流程都配一个“输入前 / 输出后”示例模型会快速学会格式。示例比一千句描述更有效。技能包纳入版本管理。在团队中通过 Git 仓库分发更新走评审而不是直接改生产文件。这样可以回溯也方便回滚。8.2 安全边界社区里已经有大量现成的 skills 集合例如 Superpowers Skills、各类 skills 推荐仓库等。下载后不要直接运行先看 SKILL.md再看它引用的脚本。脚本如果包含读取敏感文件、外发网络请求、删除文件等操作要格外谨慎。不要在 SKILL.md 里存放任何密钥、Token、内部域名、数据库连接串。技能文本会被加载进模型上下文也可能会被分享敏感信息放进技能等于公开。更重要的是如果技能涉及数据库变更、权限配置、生产环境操作必须在测试环境先验证并做好备份和回滚方案遵循最小权限原则。AI 能生成建议但生产变更的决策和授权必须由人完成。8.3 后续学习方向如果你想继续深入有几个值得关注的方向。第一把 skills 和 MCP 结合。skills 负责“怎么思考”MCP 负责“能连接什么”两者配合可以做出更强的 Agent 工作流。第二从编程场景扩展到测试、前端开发、学术研究辅助、内容创作等场景。Skills 的格式是通用的UI 设计、测试用例生成、论文写作辅助都可以用同一套流程规范。第三如果你在用 Codex CLI、OpenCode 等工具可以研究它们各自的技能加载机制。工具之间还有不少差异但核心逻辑是一致的描述要清晰流程要固定资源要分离。我最推荐的下一步是先写一个和你团队最痛场景相关的技能。代码规范混乱就写格式化审查提交信息混乱就写 commit-message测试覆盖率低就写测试生成。从几十行的小技能开始跑通之后再慢慢扩展。Skills 本质上不是让人更依赖 AI而是让 AI 在团队规则内工作。当你把团队的工程经验固化成技能包后模型就不再是那个“每次都要重新教的实习生”而是一个能稳定执行规范的协作者。这个转变才是 skills 最近在 GitHub 上火爆的真正原因。