Agent Skill

Agent Skill 是 Claude 制定的一套标准，直译过来就是“技能”，一个 Skill 就是一个技能。智能体技能（Agent Skills）是一个包含指令、脚本和资源的文件夹，智能体可以发现并使用这些技能，从而更准确、更高效地完成任务。Skills是一个开放的、模块化的、可组合的智能体技能库。它的核心理念很简单：“不要让AI从零开始学做事，而是给它一套标准化的‘技能工具箱’。”就像人类通过学习“开车”、“做饭”、“写代码”等技能来完成复杂任务，AI智能体也可以通过加载不同的技能（Skill）来扩展能力边界。

Agent Skills的官方文档中强调了一个核心关键词：File-system based（基于文件系统）。可以通过一个例子更直观地理解这句话：在编写程序时，并不一定所有代码都是我们自己写的。

我们可能会通过import xxx来引入一些外部包，这些包存放在固定的位置（如node_modules）。当程序需要调用这些包的能力时，就会从指定文件夹取出对应的代码然后执行。Agent Skills也是类似的逻辑，每个Skill都是一个实实在在存在的文件夹，它存放在一个固定的位置（如.claude/skills）。该文件夹包含以下内容：

• 指令（Skill.md）：用于指导AI执行的标准操作流程（必选）。
• 参考（reference）：提供更详细的参考文档（可选）。
• 脚本（scripts）：例如Python代码，使Skill能够调用外部功能（可选）。
• 资源（assets）：包含图片、模板等可能用到的资源（可选）。

如果在你的Agent执行目录（例如你的项目代码目录）下放置了这个文件夹，那么在下次与Agent对话时，它就能自动根据你的需求匹配到这个Skill，无需再进行任何额外的配置。

Name字段规范

• 仅使用小写字母
• 必须包含与Skill.md的目录名称匹配
• 不能包含括号或特殊字符

示例：

• ✅ test-driven-development
• ✅ pdf-editor
• ❌ test_driven_development（下划线）
• ❌ PDF Editor（大写、空格）
• ❌ skill(v2）（括号）

Description 字段规范

描述字段至关重要，它决定了 Agent 何时使用这个 skill。最佳实践：

1. 以 "Use when..." 开头，聚焦触发条件
2. 包含具体的触发器、症状和情况
3. 用第三人称编写，以注入系统提示。
4. 保持在 500 字符以内
5. 描述问题，而非技术细节（除非Skill本身是技术特定的）。

scripts/：可执行代码

• 相同代码被重复编写
• 需要确定性和可靠性
• 任务复杂但重复

reference/-参考文档

• Agent 工作时应参考的文档
• 详细的工作流程指南
• 数据库模式、API 文档、领域知识

assets/：输出资源

• Skill 需要在最终输出中使用的文件
• 不打算加载到上下文中，而是在输出中使用的文件

• 触发：Agent 启动/会话初始化。
• 加载：技能名称与简述（极低Token占用）。
• 作用：建立“能力索引”，让模型知道“我会什么”，但不引入具体做法。
• 结果：Claude知道自己“会什么”，但还不知道“具体怎么做”。

• 触发：用户提出具体意图（例如“处理 Excel”）。
• 加载：该技能的Skill.md文件（即标准化操作手册/SOP）。Claude 发现此任务属于“Excel 处理”技能的范围，因此会通过后台命令读取该文件夹中的Skill.md文件。
• 作用：明确“怎么做”的步骤、边界与注意事项，进入可执行状态。只有在这个时候，详细的操作步骤和注意事项才会被 AI 理解。

• 触发：开始执行具体步骤。

• 参考（reference）：用户下达的任务可能是分析 Excel，也可能是创建 Excel。这两个操作可能有完全不同的处理步骤。详细的步骤不一定都在 Skill.md中，可以分开，放在不同的参考文献（reference）下。当 Claude 识别到用户要分析 Excel 时，才会去查阅 Excel 分析的参考资料。
• 脚本（scripts）：Skill中可以内置一些可执行的Excel处理脚本。在Skill.md或者具体的参考文献（reference）下，会告诉你应该如何调用这些脚本。还有最重要的一点是，Claude只需要按照指引执行脚本，而脚本本身的代码并不会被AI读取，因此你完全不用担心超大的代码文件会消耗Token。
• 原则：按需加载。脚本由 Agent 根据指引调用，代码本身不会注入到模型上下文中，从而避免上下文膨胀。