一、先说结论：技能系统到底解决了什么问题？
很多人使用 AI 编程助手时，最大的问题不是模型不会，而是每次都要重新交代背景：项目规范是什么、修改流程是什么、审查标准是什么、什么时候该保守、什么时候该大胆。这些内容如果每次都靠临时输入，必然会出现遗漏、误解和重复劳动。
技能系统的价值，就是把这些反复验证过的流程、经验、检查清单、上下文资料，打包成一个可以被模型发现、调用、执行和持续改进的能力模块。它不像传统插件那样强调复杂接口，而是强调"把知识结构化，让模型按标准流程行动"。
换句话说，技能不是单纯的命令，也不是普通提示词，而是一种"可调用的知识包"。它可以包含名称、描述、触发条件、允许使用的工具、执行方式、模型偏好、努力等级、适用路径以及附加参考文件。真正执行时，模型会把技能内容加载进上下文，然后按照里面的流程完成任务。
1.1 为什么这件事很关键？
AI Agent 要从"会聊天"变成"会干活"，必须具备三个能力：第一，能理解任务；第二，能调用工具；第三，能记住组织里反复出现的最佳实践。前两个能力很多系统已经具备，但第三个能力往往被低估。没有技能系统，团队经验只能散落在聊天记录、文档、脑子和口头规范里；有了技能系统，这些经验可以被沉淀为可执行流程。
这也是为什么技能系统非常适合企业团队：代码审查规范、上线前检查、迁移流程、文档格式、PR 规则、安全红线、组件库使用方式，都可以被写成技能。它既能提升效率，也能降低新人使用 AI Agent 时的失误率。
二、技能的本质：不是代码逻辑，而是结构化知识
技能系统最反直觉的一点是：它的核心不是写一堆业务代码，而是写一份模型能够理解并执行的结构化操作说明。一个技能通常由一个目录组成，目录里最核心的是 SKILL.md 文件。这个文件前半部分是元数据，后半部分是正文说明，还可以配套参考资料、模板、脚本或资源文件。
元数据负责"让模型知道什么时候该用这个技能"，正文负责"告诉模型用的时候怎么做"，附加文件负责"在真正需要细节时再读取"。这种设计被称为渐进披露：先把最轻量的信息放进上下文，等任务真的需要，再加载更详细的内容。
2.1 元数据：决定技能能不能被正确发现
元数据里最重要的是名称和描述。名称要短、清晰、可识别；描述要明确说明"适合什么任务、什么时候调用、解决什么问题"。如果描述太虚，模型不知道该不该用；如果描述太长，又会浪费上下文预算。
在工程实现里，技能还可以携带更多控制字段。例如 allowed-tools 用来声明技能需要哪些工具；context 用来决定是在主上下文执行，还是放到隔离的子 Agent 中执行；model 和 effort 可以指定更强模型或更高推理档位；paths 可以让技能只在特定目录被触发。
2.2 正文流程：把"经验"写成模型可执行的步骤
技能正文不是随便写一段说明，而应该像操作手册。好的技能正文通常包含：任务目标、适用边界、执行步骤、成功标准、常见坑、失败时的处理方式、需要用户确认的节点、最终输出格式。
尤其要强调成功标准。很多 AI 任务失败，不是因为模型没有做，而是因为它不知道做到什么程度算完成。比如"优化代码"太泛；如果写成"删除重复逻辑、保持接口不变、补齐单元测试、列出风险点"，执行稳定性会明显提高。
三、内置技能：把官方最佳实践预装进系统
内置技能可以理解为系统预装的能力包。它们在启动阶段被注册成统一的命令对象，之后和用户自定义技能走同一套发现、调用、执行逻辑。这样做的好处是架构统一：不管技能来自系统、用户、项目还是远端，最终都能以统一方式被模型调用。
3.1 内置技能的几个典型代表
第一类是配置和调试类，例如更新配置、键盘快捷键、调试诊断等。它们更像系统操作助手，帮助用户调整工具自身的行为。
第二类是工程流程类，例如批量迁移、代码简化、验证变更等。它们把复杂开发流程拆成研究、计划、执行、检查、汇总等阶段，让 AI Agent 不至于一上来就盲改。
第三类是元能力类，例如把当前成功会话提炼成新技能，或者整理记忆层。这类能力特别关键，因为它让系统具备"从实践中学习"的可能。
3.2 为什么有些技能必须禁止模型主动调用？
像批量迁移、并行工作树、大规模 PR 创建这类能力，一旦误触发，成本和风险都很高。因此它们通常只能由用户明确输入触发，而不是让模型自己决定使用。这个设计体现了一个重要原则：越是高影响、高成本、高权限的技能，越不能完全交给模型自行启动。
四、用户自定义技能：把个人和团队经验变成能力资产
用户自定义技能是整个系统最有想象力的部分。个人可以把常用写作、代码审查、数据处理、发版检查沉淀成技能；团队可以把项目规范、组件库约束、接口风格、测试要求写进仓库；企业可以通过策略管理，把审计过的技能统一下发。
4.1 多来源加载：个人、项目、企业各司其职
技能可以来自多个层级。企业管理层适合放安全审计后的通用能力；用户全局层适合放个人高频流程；项目本地层适合放仓库专属规范；附加目录适合临时挂载实验性能力；旧命令目录则用于兼容历史模式。
这种分层设计非常符合真实工程场景：个人需要效率，项目需要一致性，企业需要治理。把它们强行混成一层，要么太死板，要么太混乱。
4.2 元数据解析：宽容但不失控
技能加载时会解析 frontmatter 里的字段，包括描述、工具、触发条件、模型、执行上下文、努力等级、路径条件等。这里有个非常实用的工程思想：对无效字段尽量宽容，不轻易让一个技能因为小错误彻底不可用；但对安全相关字段保持谨慎，不能随便放权。
例如 effort 字段可以让某个技能指定更高推理强度，但如果填写无效，系统可以忽略并记录调试信息，而不是让整个技能崩掉。这样的设计对扩展系统很重要，因为用户自定义内容天然会有格式差异。
五、调用链路：从 Markdown 到模型上下文
当技能真正被调用时，系统会把原始 Markdown 做一系列处理：补充技能所在目录、替换用户参数、注入会话标识、处理路径变量，并根据来源决定是否允许执行内联命令。处理完成后，技能内容会作为结构化内容进入主对话，或者交给子 Agent 在隔离上下文中完成。
5.1 inline 与 fork：两种完全不同的执行模式
inline 模式适合轻量任务。技能内容直接进入当前上下文，模型在同一条对话里继续执行。这种方式成本低、衔接顺，但会占用主上下文。
fork 模式适合复杂任务。系统会启动子 Agent，在独立上下文中完成研究、审查、验证或批处理，最后只把结果摘要带回主流程。这相当于把复杂工作外包给一个临时专家，避免主上下文被大量中间过程污染。
六、条件技能：只在相关路径出现，避免上下文污染
如果所有技能都常驻上下文，系统很快会变得臃肿。条件技能的作用，是让某些能力只有在用户操作特定文件路径时才被激活。例如某个 React 组件库规范，只在用户编辑 src/components 目录时出现；某个后端接口规范，只在服务目录被触达时出现。
6.1 对 monorepo 特别友好
大型仓库里经常有多个包、多个服务、多个团队规范。如果所有规则都放进一个全局提示里，模型会被无关信息干扰。路径条件让每个目录拥有自己的局部能力：只有当用户真的操作相关文件，专属技能才进入可用集合。
更重要的是，技能一旦被激活，整场会话中都可以继续使用。这样既保持了"按需出现"的轻量，又避免用户反复触发同一个路径条件。
七、MCP 与远程技能：能力可扩展，但信任必须分层
技能不仅可以来自本地目录，也可以通过 MCP 或远程技能搜索机制进入系统。这样一来，组织可以把能力分发到更多环境，外部服务也能提供专业能力。但能力越开放，安全边界越重要。
7.1 统一格式，不等于统一权限
一个很重要的架构原则是：不同来源的技能可以被统一包装成命令，但不能享受同样的权限。内置技能可信度最高；用户本地技能相对可控；项目技能依赖仓库信任；MCP 或远程技能必须更谨慎。
因此，远程技能通常被当成声明式知识，不允许直接执行内联命令。这能防止外部内容伪装成技能后，诱导系统执行危险操作。对于 AI Agent 来说，远程扩展和提示注入的边界非常近，必须默认保守。
八、上下文预算：技能再多，也不能挤占真正工作空间
技能系统有一个非常现实的问题：技能越多，模型需要看到的名称和描述越多，上下文窗口就会被占用。系统的解决方案是给技能发现列表设置硬预算，只拿出很小一部分上下文用于展示技能目录。
8.1 为什么技能列表只负责发现，不负责执行？
技能列表的作用是让模型知道"有哪些能力可以用"，而不是把所有技能细节一次性塞进上下文。真正调用技能时，系统会再加载完整内容。这和搜索引擎很像：搜索结果页只给标题和摘要，点进去才看全文。
当预算足够时，展示完整简洁描述；预算不足时，非核心技能描述会被压缩；极端情况下，只保留技能名称。内置核心技能描述优先保留，因为它们通常承担基础能力，触发条件更重要。
九、技能生命周期：注册、发现、调用、执行、改进、重载
成熟的技能系统不是"写完就结束"，而是一套完整生命周期。技能先被注册，再以轻量描述被模型发现；当任务相关时被调用；执行后，如果用户纠正了行为或表达了偏好，系统可以把这些变化反向沉淀到技能里；文件变更后，缓存被清理并重新加载。
9.1 自我改进：把用户纠正变成下一次的稳定表现
很多团队最宝贵的经验，不是写在正式规范里的，而是在一次次纠正中出现的。例如"不要这样命名""这里必须先跑验证""这个组件不要直接改""这种情况先问我"。如果这些纠正只停留在一次对话里，下次还会重复犯错。
技能改进机制的意义，就是在技能使用过程中观察用户反馈，把偏好、纠正、新步骤、新边界提炼成更新建议，再通过独立流程改写技能文件。这样一来，技能会从静态文档变成可演进资产。
十、权限模型：默认谨慎，敏感能力必须确认
技能能影响模型行为，也可能申请使用工具、触发 hook、进入子 Agent 或访问资源。因此权限模型不能粗放。系统采用白名单思路：只有明确被认为安全的属性，才能自动通过；包含敏感字段的技能，需要进入确认路径。
10.1 白名单比黑名单更适合扩展系统
黑名单模式的问题是：当新字段出现时，如果忘记加入黑名单，可能直接放行。白名单模式正好相反：只有列入安全集合的字段才自动通过，未知字段默认需要确认。对于不断扩展的 AI Agent 平台，这种保守默认更可靠。
权限规则还支持精确匹配和前缀通配。团队可以对一组同名前缀的技能统一授权或拒绝，这对企业治理很实用。例如审计通过的 review 系列技能可以统一放行，高风险实验技能可以统一拦截。
十一、企业落地：技能系统应该怎么用？
真正落地时，不建议一开始就追求"大而全"的技能库。更好的方式是从高频、稳定、可验证的流程开始：代码审查、上线检查、日志排查、接口迁移、文档生成、测试补齐、PR 描述、设计评审等。
11.1 个人层：先把自己的重复劳动自动化
个人最适合沉淀"我每周都要做"的流程，比如整理会议纪要、生成周报、检查代码风格、写 PR 描述、做数据分析、生成技术文章结构。个人技能的目标是减少重复输入，让 AI 更懂自己的工作习惯。
11.2 项目层：把仓库规范直接放进代码库
项目层技能适合写入仓库专属规则，例如目录结构、组件约定、测试命令、发布流程、接口风格、错误处理模式。这样每个进入项目的人使用 AI Agent 时，都会得到同一套上下文指导。
11.3 企业层：统一分发可审计能力
企业层更关注权限、安全、版本和合规。哪些技能可以自动使用？哪些技能需要确认？哪些远程能力不能执行命令？哪些技能只允许官方维护？这些问题不能靠个人自觉，而应该通过策略层统一治理。
十二、写好技能的实战方法论
第一，技能要聚焦一个重复任务，不要把多个无关流程塞进一个技能里。越聚焦，模型越容易判断是否调用。
第二，描述要写清触发场景。不要只说"用于代码处理"，而要说"当用户要求审查 PR、检查安全风险、发现重复逻辑时使用"。模型主要靠描述判断是否触发。
第三，正文要写步骤和成功标准。不要只写原则，要写"先做什么、再做什么、输出什么、完成标准是什么"。
第四，附加资料要拆分。核心流程放在 SKILL.md，详细规范、模板、参考材料放到独立文件里，需要时再读。
第五，工具权限要最小化。一个只读审查技能，尽量只给读取和搜索能力；一个发版技能，才考虑命令执行或外部工具。
第六，技能要持续复盘。每次模型用错、遗漏、过度执行，都应该反向修正技能，而不是每次靠临时提醒补救。
十三、核心知识点速查表
|---------------|------------------------|--------------|
| 知识点 | 通俗解释 | 工程价值 |
| SKILL.md | 技能的核心说明文件，包含元数据和执行说明 | 让知识变成可调用能力 |
| 渐进披露 | 先展示名称描述，需要时再加载正文和资源 | 节省上下文，降低噪音 |
| inline / fork | 轻任务在主上下文，复杂任务交给子 Agent | 兼顾效率与隔离 |
| paths 条件 | 操作匹配目录时才激活相关技能 | 适合大型仓库和多团队项目 |
| MCP 技能 | 外部服务提供技能能力 | 扩展生态，但必须降权 |
| 1% 预算 | 技能列表只占很小上下文空间 | 避免挤占真正任务内容 |
| 白名单权限 | 只有安全属性自动通过，敏感能力确认 | 新增能力默认谨慎 |
| 自我改进 | 根据用户纠正持续更新技能 | 让团队经验越用越稳定 |
十四、总结：技能系统是 AI Agent 工程化的关键拼图
技能系统真正厉害的地方，不在于多了一个命令入口，而在于它提供了一种把经验、流程、规范、权限、上下文预算和自我改进统一起来的工程抽象。
对于个人，它能减少重复提示，让 AI 更懂你的工作方式；对于项目，它能把仓库规范沉淀成可执行流程；对于企业，它能把可审计的能力统一分发，并通过权限和信任边界控制风险。
未来的 AI Agent 竞争，不只是模型本身有多强，而是谁能把组织知识沉淀得更细、调用得更准、治理得更稳。技能系统就是这条路上的关键基础设施。
参考资料：https://pan.baidu.com/s/1Fm6rZSZkY3q2NcrmTfTMeQ?pwd=6fkr