最近在技术社区里频繁看到一句话：“听说一些公司开始做员工skills了”。初看以为指的是员工技能培训、能力矩阵，也就是传统 HR 体系里那套任职资格盘点。但结合 2025 年下半年到 2026 年初的 AI 工具趋势，这句话还有另一层意思：一批研发团队正在把“团队经验、编码规范、业务知识”沉淀为 AI Agent 可以调用的 Skills 文件，让 Claude Code、Cursor、Codex 这类编程助手，真正学会公司内部的工作方式。
这篇文章我想把两件事讲透：第一，AI 语境下的 Skills 到底是什么，和普通提示词、MCP Tools 有什么区别；第二，如果公司想建立自己的“员工 skills 体系”，从目录设计、格式规范、编写方式到落地维护，具体应该怎么做。内容会贴近 Claude Code Skills、Cursor Rules、Codex Skills 等当前主流实现，同时给出通用思路，方便你迁移到不同平台。
1. 背景：为什么公司突然开始做“员工 Skills”
1.1 先分清两种“员工 Skills”
如果搜索“员工 skills”，大概率会看到两类完全不同的内容：
- 人力资源管理里的 Skills：指员工的专业技能、软技能、岗位胜任力，常配合技能矩阵、培训计划、晋升体系使用。
- AI Agent 里的 Skills：指一组结构化的指令、示例、规范文件，让 AI 助手在特定任务中表现出专业能力，例如“按公司规范生成 Spring Boot 项目”“用团队约定的方式写代码提交信息”“自动执行前端组件的代码评审”。
本文讨论的是第二种。不过两者其实有相通之处：传统员工 skills 解决“人如何具备某种能力”，AI Skills 解决“AI 如何具备某种能力”，而公司做 AI Skills 的过程，往往就是把优秀员工的经验显性化、标准化、代码化。
1.2 AI Skills 解决什么问题
用过 Claude Code 或 Cursor 的开发者应该有这样的体验：直接让 AI 写代码，能跑，但风格和自己团队不一致。比如：
- 项目里要求使用
Result<T>统一返回，AI 却生成裸JSONObject； - 团队规定所有数据库操作必须走 MyBatis-Plus，AI 却写 JdbcTemplate；
- 接口异常需要记录指定格式的日志，AI 完全不知道这个约定。
传统做法是把这些要求反复写进提示词，或者每次在对话里补充“请参考项目规范”。这很累，而且不同开发者复制粘贴的规范版本经常不一致。Skills 的思路是：把规范、示例、操作流程打包成一个可复用的能力单元，放在固定目录里，AI 在遇到对应任务时自动加载。
从公司角度看，这带来的好处很直接：
- 新人上手更快：新员工让 AI 生成代码时，AI 会自动遵守团队规范，减少“代码风格识别”成本。
- 经验不再只存在老员工脑子里：核心技能被文档化、被 AI 使用，降低单点依赖。
- 代码评审压力下降：很多规范性错误在生成阶段就被规避。
- 多工具统一标准：同一个 Skills 目录可以被 Claude Code、Cursor、Codex 等工具共享，团队能力库只需要维护一份。
1.3 Skills 和 Agent、MCP Tools 的关系
很多同学容易把 Skills、Agent、MCP Tools 混在一起，这里简单区分：
- Agent：一个能自主规划、调用工具、执行多步骤任务的智能体。Skills 是 Agent 的“能力包”，MCP Tools 是 Agent 的“工具接口”。
- Tools（工具）：具体执行某个操作的函数或服务，比如“查询数据库”“调用某个 API”。MCP 是工具的统一接入协议。
- Skills（技能）：偏向“教 AI 怎么做得更好”的指令和流程，通常不是可执行代码，而是 Markdown 文档 + 示例，有时会引用 MCP Tools 来获取数据。
举一个容易理解的类比：MCP Tools 相当于给 AI 配了螺丝刀、扳手、电钻；Skills 则是一本“如何按照公司标准安装一台设备”的操作手册。AI 既要有工具，也要有手册，才能稳定输出符合预期的工作成果。
2. 环境准备：搭建自己的 Skills 实验环境
在动手编写 Skills 之前，先准备好环境。由于不同 AI 编程工具对 Skills 的支持存在差异，这里以当前比较典型的 Claude Code Skills 和 Cursor 为例，演示通用思路。
2.1 确认工具版本
- Claude Code：需要较新的 CLI 版本，Skills 功能已经集成在官方客户端中，支持通过
~/.claude/skills全局目录或项目下的.claude/skills目录加载。 - Cursor：支持通过
.cursor/rules或项目内 rules 文件给 AI 注入自定义规则，新版本也在逐步贴近 Skills 格式。 - Codex：OpenAI 的 Codex CLI 支持通过
AGENTS.md或类似机制定义项目级指令，同时社区也有大量codex skills安装教程。 - 其他工具：VS Code 插件、JetBrains AI Assistant、甚至剪映等非编程工具也在引入“技能包”概念，比如搜索热词里就出现了“剪映官方skills”。
版本需要根据你的项目实际情况调整，本文示例以常见环境为例，重点演示配置思路，具体路径以你使用的工具官方文档为准。
2.2 目录规划
无论使用哪款工具，Skills 的落地方式通常分为两种：
| 类型 | 目录位置 | 作用范围 |
|---|---|---|
| 个人全局 Skills | ~/.claude/skills/或用户级配置目录 | 当前用户所有项目可用 |
| 项目级 Skills | <项目根>/.claude/skills/或.cursor/rules/ | 仅在当前项目生效 |
| 团队共享 Skills | 独立 Git 仓库，克隆到各成员本地 | 通过同步机制共享 |
推荐在公司内部使用“独立 Git 仓库 + 项目级软链/复制”的方式，这样既能做到版本管理，又能在不同项目间灵活选择需要启用的 Skills 集合。
2.3 最小目录结构
下面以一个名为team-springboot的团队 Skills 仓库为例：
team-springboot/ ├── README.md ├── skills/ │ ├── generate-springboot-project/ │ │ ├── SKILL.md │ │ └── examples/ │ │ └── demo-result.md │ ├── code-review-rule/ │ │ ├── SKILL.md │ │ └── rules/ │ │ └── exception-handling.md │ └── commit-message-helper/ │ ├── SKILL.md │ └── templates/ │ └── commit-template.md这里的核心是每个技能目录下的SKILL.md文件，它是 AI 理解和执行技能的主要依据。其他辅助文件用来存放更详细的规则、模板、示例，供SKILL.md引用。
3. 核心拆解：SKILL.md 的格式与编写方法
3.1 什么是 SKILL.md
SKILL.md是一个 Markdown 文件，采用类似 frontmatter 的头部信息描述技能的名称、描述、适用场景，正文部分则详细说明执行步骤。AI 工具通过扫描 Skills 目录，读取每个SKILL.md的元信息，在合适的任务场景下自动加载。
下面是一个最小示例：
--- name: generate-springboot-project description: 按照团队标准生成 Spring Boot 3 项目结构，包含统一返回体、全局异常处理、MyBatis-Plus 依赖等。 --- # Spring Boot 项目生成技能 ## 适用场景 当用户要求“新建 Spring Boot 项目”或“初始化一个服务”时，使用本技能。 ## 执行步骤 1. 确认项目名称、包名、端口、数据库类型等基础信息。 2. 按 templates/springboot-template.md 生成项目结构。 3. 所有接口统一返回 Result<T> 结构。 4. 全局异常处理类必须继承 BaseExceptionHandler。 5. 所有 Mapper 继承 BaseMapper<T>，并添加 @Mapper 注解。description字段非常关键，它决定了 AI 在什么时候主动调用这个技能。描述写得越具体，匹配准确率越高。
3.2 Frontmatter 常用字段
不同工具支持的字段略有差异，但以下几项是通用的：
| 字段 | 含义 | 建议 |
|---|---|---|
name | 技能名称 | 使用kebab-case或snake-case，避免特殊字符 |
description | 技能描述 | 写清楚触发场景和技能作用，建议 2-3 句话 |
version | 技能版本 | 方便团队审阅和变更记录 |
tags | 标签 | 便于分类检索，例如前端、后端、规范 |
allowed-tools | 允许调用的工具 | 可以限制该技能是否允许调用 MCP Tools |
注意：不要为了追求字段完整而编造工具一定支持的字段。最稳妥的做法是只写name和description，这是当前主流工具都认可的基础格式，其他字段按需补充。
3.3 SKILL.md 正文的写作要点
正文不是简单地把提示词放进去，而是要像“操作手册”一样，让 AI 能够在多步骤任务中保持稳定。经验上可以按以下结构组织：
- 目标说明：这个技能最终要产出什么。
- 前置条件：执行前需要确认哪些信息。
- 执行步骤：按顺序列出，必须明确、可检验。
- 约束清单：哪些不允许做，哪些必须做。
- 示例参考：引用
examples/下的完整案例。 - 验证方式：怎么判断结果是否符合要求。
这里有一个容易被忽略的点：Skills 不是越详细越好。如果正文写得过于冗长，AI 很可能迷失在细节里。推荐每个步骤控制在 5 行以内，更详细的规则放到辅助文件中，由 SKILL.md 按需引用。
3.4 一个完整的团队示例
以“代码提交信息辅助”为例，这是最适合团队落地的 Skills 之一，见效快、风险低。
--- name: commit-message-helper description: 根据 git diff 生成符合团队规范的提交信息，使用 Conventional Commits 格式。 --- # 提交信息生成技能 ## 适用场景 当用户输入“生成提交信息”或“帮我写 commit message”时，根据 git diff 内容生成提交信息。 ## 执行步骤 1. 执行 `git diff --cached` 或 `git diff` 获取变更内容。 2. 分析变更类型：feat、fix、refactor、docs、test、chore 等。 3. 提交信息格式为 `<type>(<scope>): <subject>`，例如 `feat(user): add user detail page`。 4. 如果需要，生成正文说明变更原因和影响范围。 5. 输出完整的 git commit 命令，方便用户直接执行。 ## 约束 - type 必须来自允许列表，不允许使用其他单词。 - subject 使用英文或中文均可，但同一仓库内保持一致。 - 不修改用户暂存区内容，只输出建议。示例中的“执行 git 命令”是 AI 编程工具普遍支持的基本能力，不属于 MCP Tools，但如果你希望技能能够主动查询代码仓状态，也可以通过allowed-tools声明需要的 MCP 工具。
4. 完整实战：做一个“Spring Boot 项目生成”团队 Skills
下面以一个更完整的实战案例，演示团队如何从零编写一个可供多个开发者使用的 Skills。这个案例借鉴了当前热词中“springboot3 skills生成项目”的场景，非常适合作为公司内部第一个“员工 skills”试点。
4.1 需求描述
假设团队经常要新建内部微服务，每次手工初始化项目都要花 10-20 分钟，而且容易出现依赖版本不一致、缺少统一异常处理、返回体结构不统一等问题。我们希望做一个 Skills，让 AI 在收到“创建用户服务”这类指令时，自动生成符合团队规范的项目骨架。
4.2 创建技能目录
mkdir -p team-springboot/skills/generate-springboot-project/examples cd team-springboot/skills/generate-springboot-project4.3 编写 SKILL.md
--- name: generate-springboot-project description: 按团队规范生成 Spring Boot 3 项目，包含统一返回体、全局异常处理、MyBatis-Plus、Logback 配置等。适用于“新建服务”“初始化项目”“创建 Spring Boot 应用”等场景。 --- # Spring Boot 项目生成技能 ## 前置条件 向用户确认以下信息： - 项目名称（例如 user-service） - 包名（例如 com.example.userservice） - 端口号（默认 8080） - 数据库类型（默认 MySQL） - 需要的模块（可选） ## 执行步骤 1. 创建 Maven 项目结构，生成 `pom.xml`。 2. 在 `pom.xml` 中添加依赖：spring-boot-starter-web、mybatis-plus-spring-boot3-starter、mysql-connector-j、lombok、spring-boot-starter-validation。 3. 创建启动类，使用 `@SpringBootApplication` 注解。 4. 创建统一返回体 `Result<T>`，包含 code、message、data 三个字段。 5. 创建全局异常处理类，使用 `@RestControllerAdvice`，处理业务异常、参数校验异常和兜底异常。 6. 创建 `application.yml`，配置端口、数据库连接、MyBatis-Plus 日志输出。 7. 生成示例 Mapper、Service、Controller，演示基础 CRUD 流程。 ## 约束 - Spring Boot 版本使用 3.x，JDK 使用 17 或 21。 - 所有 Controller 方法返回 Result<T>。 - Service 层必须使用接口 + 实现类的方式。 - 不允许生成任何业务无关的测试数据。4.4 编写辅助模板
把更详细的pom.xml片段放在examples/demo-result.md或独立模板文件里，避免 SKILL.md 过长。
<!-- 核心依赖片段，完整内容由 AI 按项目名补充 --> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus-spring-boot3-starter</artifactId> <version>3.5.5</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> </dependency>注意：MyBatis-Plus 的版本更新较快，示例中的版本号只适合演示。实际团队落地时，建议在模板中明确锁定公司内部验证过的版本，甚至统一走公司私有 Maven 仓库。
4.5 编写统一返回体示例
// 文件路径：src/main/java/com/example/common/Result.java package com.example.common; import lombok.Data; @Data public class Result<T> { private int code; private String message; private T data; public static <T> Result<T> success(T data) { Result<T> result = new Result<>(); result.code = 200; result.message = "success"; result.data = data; return result; } public static <T> Result<T> error(int code, String message) { Result<T> result = new Result<>(); result.code = code; result.message = message; return result; } }这段代码本身不是 Skills 的核心内容，但作为examples目录下的参考产物，AI 在生成项目时会参考它的风格。
4.6 安装到 Claude Code
在项目根目录创建.claude/skills，将团队 Skills 仓库里的generate-springboot-project复制进来：
mkdir -p .claude/skills cp -r team-springboot/skills/generate-springboot-project .claude/skills/启动 Claude Code 后，直接输入：
帮我创建一个订单服务，使用 Spring Boot 3，端口 8082如果 Skills 生效，Claude Code 会在回答中参考generate-springboot-project的步骤，生成符合团队规范的项目结构。如果发现它没有自动加载，可以在对话中明确提示“请使用 generate-springboot-project 技能”。
4.7 验证与迭代
生成项目后，需要人工验证以下几点：
| 检查项 | 预期结果 |
|---|---|
| 项目能正常编译启动 | 是 |
| 返回体是否统一 | 所有接口返回 Result |
| 异常处理是否覆盖 | 有全局异常处理类 |
| 依赖版本是否符合团队规定 | 与模板一致 |
| Controller 是否规范 | 有基本 CRUD 示例，无多余代码 |
常见的情况是第一次生成的代码不完全符合团队约定，这很正常。把发现的问题补充到 SKILL.md 的约束清单里，下一次生成就会更准确。Skills 是持续迭代的产物，不是一次写完就结束的文档。
5. 常见问题与排查思路
在实际使用 Skills 的过程中，团队遇到最多的问题可以归纳为下面几类。
| 问题现象 | 常见原因 | 解决思路 |
|---|---|---|
| AI 不自动加载 Skills | description 不够明确，触发场景不匹配 | 优化 description，增加常见触发词 |
| Skills 生成结果不稳定 | 正文步骤过于含糊或过长 | 精简步骤，把详细规则拆到辅助文件 |
| 多个 Skills 行为冲突 | 不同技能对同一问题的规范不一致 | 建立技能冲突仲裁机制，明确优先级 |
| Skills 在团队中无法同步 | 只放在个人目录，没有纳入 Git 管理 | 使用独立仓库 + 项目级复制/软链 |
| 更新后 AI 仍然使用旧规则 | 工具缓存了旧 Skills 文件 | 重启 AI 进程或清理缓存 |
| Skills 涉及敏感信息 | 模板中写入了数据库密码、Token 等 | 使用占位符，敏感信息走环境变量 |
下面展开两个最容易踩坑的场景。
5.1 AI 不识别 Skills 怎么办
首先确认工具版本是否支持 Skills。如果支持，检查目录位置是否正确。以 Claude Code 为例，全局 Skills 放在~/.claude/skills，项目级 Skills 放在.claude/skills。目录下必须有SKILL.md，且 frontmatter 的name和description不能为空。
其次，工具通常会按“与当前任务的相似度”自动匹配 Skills。如果你用的工具支持通过@技能名的方式强制指定，那就直接显式调用，验证技能本身是否可用。如果显式调用没问题，再回头优化 description。
5.2 Skills 和项目规则冲突怎么办
很多项目里已经有.cursor/rules、AGENTS.md、README等规则文件，Skills 新引入后很可能产生冲突。例如AGENTS.md说“接口返回 JSONObject”，Skills 说“返回 Result ”，AI 会以哪个为准？
不同工具的优先级不同，但通用原则是：
- 项目级规则优先于全局规则。
- 更具体、更新的规则优先于宽泛规则。
- 人工在对话中明确指定的指令优先于自动加载的规则。
因此，建议在团队落地 Skills 时，同步检查项目现有的规则文件，尽量统一描述，避免让 AI 陷入两难。必要时可以在 SKILL.md 中加一行“若与其他项目规则冲突，以本技能说明为准”，但更稳妥的做法是直接消除冲突。
6. 公司落地“员工 Skills 体系”的最佳实践
如果公司准备正式推动员工 skills，而不是个人开发者自己玩玩，下面这些工程建议值得参考。
6.1 从高频、低风险场景切入
不要一上来就想做一个包罗万象的“全能技能库”，建议优先选择下面几类场景：
- 提交信息格式化：风险最低，几乎所有研发团队都需要。
- 项目脚手架生成：见效最快，能明显减少重复劳动。
- 代码评审规则：把团队积累的 review 意见固化成技能。
- 知识库检索：结合企业内部文档，利用 Skills 引导 AI 按指定流程回答问题。
- 测试用例生成：按团队测试规范生成单测或集成测试，提升覆盖率。
这些场景的共同特点是：规则明确、可以标准化、不涉及高风险的生产变更。
6.2 建立技能命名与评审规范
同一个技能可能有多个团队提交，为了避免混乱，建议统一命名规范：
<团队>-<领域>-<动作> 例如：backend-springboot-generate、frontend-react-component-review每个 Skills 仓库应该有一个README.md，记录技能的维护人、最近更新内容、适用范围。新增技能建议走简单的评审流程，至少由两个人确认技能的规则没有明显错误，再合并到主干。
6.3 安全边界与敏感信息管理
Skills 文件本质上是文本，它可以读取到的信息范围受 AI 工具权限控制。落地时要注意：
- 不要在 Skills 模板里写任何真实的密码、Token、内网地址。
- 如果技能需要调用内部 API，建议通过 MCP Tools 传入，而不是把密钥写死在 SKILL.md 中。
- 涉及生产环境变更的技能，例如“自动发布”“数据库订正”，必须在技能正文中增加强制确认步骤，并要求人工审核。
- 对生成代码可能造成的破坏性操作，必须强调先在测试环境验证。
这里想特别提醒：Skills 赋予了 AI“按规范做事”的能力，同时也意味着如果规范有问题，AI 会严格执行错误规范。所以公司级的 Skills 应该有版本记录和回滚机制，最好用 Git 管理，每次更新都能追溯。
6.4 组织知识运营
让员工把经验写成 Skills，最大的阻力往往是“没有时间”或“不知道怎么写得规范”。可以给每个业务线指定一个“技能主理人”，负责把团队经验整理成初稿，再由 AI 能力较强的同学帮忙优化。也可以定期举办“技能编写工作坊”，让不同团队的技能互相评审，形成社区氛围。
从工程角度来看，Skills 仓库本身就可以视为代码仓库，遵循代码评审、测试、发布流程。建议安排每周或者每双周一个固定时间处理 Skills 的 PR，让更新节奏稳定下来。
6.5 衡量效果
判断员工 Skills 体系是否有效，不建议只盯着“AI 使用次数”。更合理的指标包括：
- 新项目初始化时间是否下降。
- 不符合团队规范的代码比例是否下降。
- 技能被调用次数和用户满意度。
- 代码评审中规范性问题的数量变化。
- 团队内重复提问和重复踩坑的频率。
这些指标不一定能完全量化，但只要形成对比趋势，就能说明技能库是否真正发挥作用。
7. 总结
“听说一些公司开始做员工skills了”这句话背后，其实反映了 AI 编程工具正在从“通用助手”走向“团队定制化助手”。Skills 提供了一种相对轻量的方式，把团队经验、编码规范、业务流程打包成 AI 可以理解和执行的单元。无论是个人开发者还是公司团队，现在开始积累自己的 Skills 库都不算晚。
这篇文章的核心收获可以归纳为几点：第一，明白 Skills 与提示词、MCP Tools、Agent 的边界；第二，掌握SKILL.md的基本结构和编写原则；第三，能够从一个简单的团队技能（提交信息、项目生成）开始落地；第四，知道在公司层面推广时要注意命名规范、安全边界、评审流程和效果评估。
下一步可以做的实践练习是：先不追求复杂，找一个自己团队反复要做、规则明确的小任务，比如“生成符合规范的项目结构”或“生成单测”，把它写成第一个 Skills。放到 Claude Code 或 Cursor 里试运行，不断补充 AI 遗漏的规则细节。当第一个技能真正用起来后，再逐步扩展成一套完整的员工 skills 体系，这条路会走得比想象中更顺。
