Agent Skills 完整指南：如何让 AI Agent 掌握可复用的专业知识与工作流程

长期把团队规范、领域知识和操作步骤堆进系统提示词，结果通常是上下文越来越长，AI Agent 却仍然无法稳定判断何时使用哪套流程。

最快的解决方式是：本周先把一个高频、结果可验收的流程拆成独立 Skill，用 SKILL.md 写清“做什么、何时使用、如何完成”，再把动态资料放进知识源，把外部操作交给受控工具。Agent Skill 本质上是包含触发描述、操作指令及可选脚本和参考资料的可复用能力包，适合封装稳定流程，但不等于拥有独立运行权限。

本文适合以下读者：

• 第一次接触 SKILL.md 和 Agent Skills 的开发者；
• 希望复用团队标准流程的 Claude Code 用户；
• 准备建立内部 Skill 仓库，并关心脚本、网络访问和权限治理的技术负责人。

最后更新于 2026 年 8 月 17 日，规范字段、目录结构和客户端行为核实自 Agent Skills 官方规范、官方 Skill 示例仓库 与 Claude 技能创建文档。

先拆开 4 个问题：为什么提示词越写越长，流程仍然不稳定

把所有知识写进系统提示词，看起来集中，实际会带来至少 4 个限制。

第一，上下文占用不可控。一个团队可能同时维护代码审查、发布、数据清洗和文档生成流程。如果所有规则始终加载，简单任务也会携带大量无关内容；如果为了缩短提示词而删减，又容易遗漏关键边界。

第二，知识更新和流程更新混在一起。例如税率、接口字段、产品版本属于动态事实，应该从可更新知识源中读取；而“先检查输入，再执行转换，最后运行验收”的顺序属于稳定流程，适合放入 Skill。把两者混为一谈，会造成规则过时却仍被模型引用。

第三，触发范围不清晰。一个名为“开发助手”的大 Prompt 可以覆盖很多任务，却无法告诉 AI Agent 什么时候应该使用代码审查流程，什么时候应该切换到部署流程。结果可能是误调用，也可能是该调用时没有调用。

第四，执行权限被误解。Skill 可以附带脚本，也可以指导 Agent 使用工具，但它本身不是沙箱、不是身份系统，也不是自动获得网络、文件或终端权限的后台进程。真正能否执行命令，取决于客户端、运行环境和权限策略。

官方规范将 Skill 定义为一个至少包含 SKILL.md 的目录，并允许增加 scripts/、references/ 与 assets/ 等目录；这正好对应了“元数据先发现、正文后加载、资源按需读取”的渐进式加载方式。(agentskills.io)

第一步：先确定 Skill 的边界，再决定放哪些文件

一个适合维护的 Skill，不应以“我能做所有开发工作”为目标，而应围绕一个能够重复执行、结果能够验收的工作单元设计，例如：

• 按团队规则审查 Pull Request；
• 将接口文档转换成统一格式；
• 检查发布前的配置、测试和变更记录；
• 依据公司模板生成技术报告。

推荐的最小目录如下：

release-review/
├── SKILL.md
├── references/
│   ├── release-policy.md
│   └── rollback-guide.md
├── scripts/
│   └── check-release.sh
└── assets/
    └── release-report-template.md

官方规范要求 name 使用小写字母、数字和连字符，并且目录名要与之匹配；description 则应同时说明 Skill 的功能和使用时机。正文没有强制章节格式，但官方建议写入步骤、输入输出示例和常见边界情况。(agentskills.io)

SKILL.md 应该写到什么程度

可以采用下面的骨架，但不要机械复制：

---
name: release-review
description: 检查发布分支的测试结果、配置变更和回滚准备。用户要求进行发布前审查、上线检查或回滚评估时使用。
compatibility: 需要 git、项目测试命令和只读仓库访问权限
metadata:
  owner: platform-team
  version: "1.0"
---

# 发布审查

## 目标
确认发布候选版本满足测试、配置和回滚要求。

## 执行步骤
1. 读取变更范围。
2. 检查测试结果和失败项。
3. 对照 references/release-policy.md。
4. 必要时运行 scripts/check-release.sh。
5. 输出阻断项、风险项和通过项。

## 验收标准
- 每个阻断项都包含文件、命令或日志依据。
- 没有把“未检查”写成“已通过”。
- 涉及生产环境的操作必须等待明确确认。

这里最重要的不是章节名称，而是让 AI Agent 知道先做什么、何时停下、什么结果算完成。如果核心流程无法在 SKILL.md 中表达清楚，就不应急着增加更多参考文件。

第二步：把触发描述写成“功能＋时机”，减少误调用

Skill 是否被使用，首先取决于描述是否让 Agent 判断出任务相关性。官方创建指南明确把 description 视为主要触发机制，并建议描述同时包含“做什么”和“什么时候使用”。(github.com)

例如，下面两种写法的触发质量不同：

Prompt 和 Agent Skills，边界到底在哪里？

Prompt 更适合一次性任务、临时角色、当前对话中的补充要求；Agent Skills 则适合把稳定的专业流程保存为独立单元，让多个任务在需要时加载同一套规则。Prompt 通常由调用者主动提供，而 Skill 的描述会参与发现和触发判断，因此二者不能简单视为同一种文件格式。

可以用下面的方法测试触发描述：

1. 写出 3 个应该触发 的真实请求，例如“检查这次上线是否具备回滚条件”；
2. 写出 3 个不应该触发 的相邻请求，例如“解释蓝绿部署的概念”；
3. 加入不直接说出 Skill 名称的自然表达；
4. 检查它是否与代码审查、测试诊断、部署执行等相邻 Skill 发生重叠；
5. 修改描述后重新运行同一组测试，而不是凭一次成功案例下结论。

需要注意的是，简单的一步任务未必会调用 Skill，即使描述完全匹配；复杂、多步骤或专业性更强的任务更能检验触发效果。官方创建指南也建议为 Skill 建立正例和反例测试集，而不是只用一个示例验证。(github.com)

第三步：区分知识、流程、脚本和 MCP 的责任边界

Agent Skills、知识库、普通 Prompt 和 MCP 经常被放在一起讨论，但它们解决的不是同一个问题。

Agent Skills 与 MCP 如何协同？

一种稳妥的组合是：Skill 负责告诉 AI Agent“先读取哪些资料、采用什么判断顺序、输出什么格式”，MCP 负责提供项目管理、数据库、工单或其他外部系统的受控接口。Skill 不应把访问令牌写死，也不应假设任何客户端都支持相同的 MCP 工具名称。

例如，发布审查 Skill 可以要求：

• 先通过知识源读取当前发布政策；
• 再通过 MCP 查询工单状态；
• 最后调用只读脚本检查配置差异；
• 发现生产写入动作时，停止并请求人工确认。

这种拆分能够减少三类错误：把过期资料当成事实、把模型生成的命令当成已执行结果，以及把“有操作步骤”误认为“已有操作权限”。

第四步：脚本可以调用，但不能绕过安全边界

Agent Skill 能不能调用脚本？

可以，scripts/ 就是官方规范建议的可选目录之一；脚本通常用于重复性、确定性较高的检查或转换任务，常见语言包括 Python、Bash 和 JavaScript。不过，是否能真正运行，取决于 Agent 产品是否支持脚本、环境是否安装依赖，以及当前会话是否允许相应工具。(agentskills.io)

安装第三方 Skill 或启用脚本型 Skill 前，至少要检查：

• 脚本是否读取环境变量、密钥、SSH 配置或浏览器数据；
• 是否包含 curl、wget、动态下载和未经说明的网络访问；
• 是否会写入项目目录之外的文件；
• 是否包含删除、覆盖、上传或执行远程内容的命令；
• 依赖包、许可证和版本是否有明确记录；
• 输入文件是否可能包含客户数据、源代码或凭证；
• 失败时是否返回清晰错误，而不是静默修改文件。

官方帮助文档特别提醒，Skill 可能包含第三方软件和可执行脚本，主要风险包括提示注入、恶意包代码和数据外泄，因此应只安装可信来源的 Skill，并在启用前检查文件、依赖、资源和网络指令。(support.claude.com)

用这份清单完成一次最小 Skill 验收

下面的清单适合在本地仓库、团队仓库或远程开发环境中逐项执行：

• [ ] Skill 只解决一个高频、结果可验收的流程，而不是包揽整个开发生命周期。
• [ ] 目录至少包含 SKILL.md，且目录名与 name 字段一致。
• [ ] description 同时写明功能和触发场景，没有只堆叠“智能、专业、自动化”等泛化词。
• [ ] SKILL.md 写出了输入、步骤、停止条件、异常处理和输出格式。
• [ ] 动态价格、版本、接口字段和政策没有被硬编码成永久事实。
• [ ] 大型参考资料已拆到 references/，并在正文中写明何时读取。
• [ ] 脚本依赖、网络访问、写入路径和失败行为已逐项检查。
• [ ] 破坏性操作、生产写入和外部发送动作需要人工确认。
• [ ] 至少准备了正向触发、相邻误触发和不应触发的测试请求。
• [ ] 已使用规范提供的校验工具或等价检查，确认 frontmatter 和命名没有错误。
• [ ] 已记录版本、负责人、变更原因和回滚方式。
• [ ] 已在隔离环境中运行第三方脚本，而不是直接放进生产工作区。

如果 Skill 需要在远程 Mac 环境中安装，建议先阅读 Vuncloud 关于服务与团队协作的说明，确认团队使用时的责任边界、沟通方式和基础服务信息；需要核对远程环境的使用规则、文件处理边界和责任范围时，也可以参考 Vuncloud 服务条款。这样做的重点不是把 Skill 当成云端服务，而是为测试、隔离和复现提供一个边界清晰的运行位置。

第五步：从单个文件建立可维护的团队能力库

当 Skill 从个人实验进入团队使用，真正的难点会从“能不能触发”转为“谁负责、怎么升级、出了问题如何回退”。

建议为每个 Skill 维护以下记录：

不要以 Skill 数量作为团队成熟度指标。更值得沉淀的是那些调用频率高、输入相对稳定、输出可以检查、错误代价明确的流程。一个能够稳定完成代码审查并输出依据的 Skill，通常比十个只有几句泛化指令的 Skill 更有维护价值。

同时，Skill 之间不应依赖隐含顺序。一个发布 Skill 不应假设“测试 Skill 一定已经运行”，而应检查测试结果是否存在；一个文档 Skill 不应假设某个知识库始终可访问，而应在资料缺失时明确标记“不足以判断”。

如果团队准备把个人实验逐步整理成共享能力库，还应提前明确维护责任、环境边界和数据处理原则；这些信息可以结合内部仓库的负责人制度、变更记录和访问审批流程一并核对，但不应把外部服务说明替代内部权限制度或代码仓库治理。

最后确认：Agent Skills 不是知识库，也不是万能插件

截至 2026 年 8 月 17 日，Agent Skills 的目录、frontmatter、渐进式加载和可选资源边界，应以官方规范和具体客户端文档为准，不同 AI Agent 对 allowed-tools、脚本执行、插件安装和组织级分发的支持范围不能互相套用。官方示例仓库也明确提醒，示例 Skill 需要在自己的环境中充分测试，不能把示例行为直接当成所有客户端的统一保证。(github.com)

可以把最终判断压缩成一句话：

• 稳定规则和步骤，放进 Skill；
• 动态事实和长文资料，放进知识源；
• 外部系统读写，交给 MCP 或其他受控工具；
• 确定性转换和检查，放进脚本；
• 临时要求和当前语境，留在 Prompt；
• 密钥、生产权限和破坏性动作，永远不要因为 Skill 的存在而自动放开。

如果当前方案是把所有 Prompt、脚本和资料直接堆在个人电脑或共享服务器上，常见缺点是环境依赖难以复现、权限边界不清、第三方 Skill 容易污染主机，而且多人协作时很难确认运行的到底是哪一个版本。对于只需要临时测试、短期部署或隔离验证的团队，租赁 Mac 环境通常比立刻购买并长期维护一台专用设备更灵活；但如果任务是长期稳定重负载、必须连接特定物理设备，或者需要完全掌控硬件和本地网络，仍应优先评估自购 Mac 或自建环境。

在真正导入第三方脚本型 Skill 之前，先完成文件审查、权限隔离和最小测试，再把通过验收的版本纳入团队仓库，这比单纯追求“安装更多 Skills”更能保证 AI Agent 的可控性。

博客

• 从代码质量度量看 Agent Skills 的设计与验收
• 把专业书籍转化为可部署 Skill：知识封装实践
• 本地 Skill 与个人 AI Agent 的能力扩展思路