“本技能凝聚团队多年经验”、“保持专业、严谨、灵活”不会改变 Agent 的下一步动作，也无法在任务结束后验收。
按照 Agent Skills 规范，一个 Skill 至少包含 SKILL.md：
sales-analysis/ ├── SKILL.md # 必需：元数据与核心工作流 ├── scripts/ # 可选：确定性执行脚本 ├── references/ # 可选：字段、规范与领域资料 └── assets/ # 可选：模板、图片与交付素材
这些目录各自解决不同问题。
| 组成部分 | 适合承载的内容 | 不适合承载的内容 |
|---|---|---|
SKILL.md | 触发条件、核心步骤、分支、边界和验收标准 | 大量可查阅资料、重复代码、宣传背景 |
scripts/ | 格式转换、校验、计算和重复执行代码 | 需要语义判断与开放式权衡的任务 |
references/ | Schema、行业规范、业务规则和详细说明 | 每次任务都必须读取的核心步骤 |
assets/ | 文档模板、图片、字体、样式和示例成品 | 密钥、用户隐私和动态配置 |
不是每个 Skill 都要拥有完整目录。小型 Skill 可以只有 SKILL.md；当任务出现重复脚本、长规范或固定模板时，再把内容拆到相应目录。
SKILL.md 应该写什么SKILL.md 通常包含 YAML Frontmatter 和 Markdown 正文。最小示例如下：
--- name: sales-analysis description: >- 分析销售类 CSV 或 XLSX 数据，完成字段检查、趋势分析、异常识别和结论摘要。 当用户提供销售表、询问收入或销量趋势，或要求定位区域和产品异常时使用。 --- # Sales Analysis 1. 检查输入文件、字段和统计周期。 2. 确认销售额、销量、订单量的口径。 3. 完成趋势、区域和产品拆解。 4. 对异常结论给出数据证据和适用边界。 5. 按指定模板输出报告。
通用规范要求 name 和 description 为必填字段。name 用于识别 Skill，description 用于告诉 Agent 这项能力做什么、何时应该触发。正文则在触发之后提供完整工作方法。触发之后，正文应保留四类会直接影响执行结果的信息：核心工作流、领域规则、资源路由和质量门槛。
核心工作流要写清步骤、分支、停止条件与失败处理；领域规则要保留模型未必知道、却会改变答案的业务口径；资源路由要说明在什么情况下读取哪份 references、调用哪个 script 或使用哪个 asset，例如“需要字段定义时读取 references/schema.md”；质量门槛则要定义可以检查的完成标准。重要资源应从 SKILL.md 直接可达，避免多层跳转。不同平台可能增加自己的字段、目录约定和工具控制，不能把某个平台的扩展字段直接写成通用标准。正文不是越长越好，而是要让 Agent 知道下一步做什么、什么时候查资料、哪些情况必须停下，以及怎样证明任务已经完成。
description 是最容易被低估的部分很多作者把大量时间花在正文，却只写一句：
description: 处理数据分析
Agent 很难据此判断：分析 CSV 是否属于它，做图是否属于它，查询数据库是否属于它，还是所有与“数据”有关的任务都应该触发。
一个有效的 description 至少回答三个问题：
例如：
description: >- 分析销售类 CSV 和 XLSX 数据，完成字段检查、缺失值处理、同比环比计算、异常识别和图表摘要。 当用户提供销售表，询问销量或收入趋势，要求定位区域或产品异常，或需要生成销售分析报告时使用。
描述不需要塞满所有关键词。多个 Skill 的描述高度重叠，同样会造成误触发和能力争抢。
如果把所有 Skill 的所有指令、脚本和参考资料都提前放进上下文，安装的能力越多，无关信息也越多。
Agent Skills 通常采用三级加载思路：
第 1 层：name + description，用于发现与匹配 → 第 2 层：任务命中后，读取 SKILL.md 正文 → 第 3 层：确有需要时，再读取 references、运行 scripts、使用 assets
可以把这三层理解成索引、操作手册和工具箱：
如果触发条件只写在正文里，Agent 在决定是否读取正文时就看不到它；如果把所有领域资料都塞进正文，真正需要的步骤又会被淹没。关键信息放错层，即使内容本身正确，也可能无法被使用。更稳妥的做法是让 SKILL.md 直接指向所需资源，并写明“什么时候读、为什么读、读完做什么”；同一条规则尽量只维护一个权威版本，避免正文与参考资料互相冲突。
先收集 3—5 个真实请求、输入样例和期望输出，找出共同步骤与变化部分。
例如，要建设“销售月报 Skill”，应该先拿到过去几次真实月报：它们查哪些指标，采用什么时间口径，哪些页面固定，哪些分析需要根据数据变化决定。
没有真实样例时，作者很容易写出概念完整、执行空泛的流程。
明确 Skill 负责什么、不负责什么。与其做“通用数据分析”，不如先做“销售月报分析”或“销售表异常检查”。
单一职责不是要求任务必须简单，而是让输入、方法、输出和验收可以被清楚描述。
根据前文的“索引—操作手册—工具箱”结构，为现有材料建立信息归属清单：
name、description：Agent 决定是否触发所需的信息；SKILL.md 正文：每次执行都需要的步骤、边界和验收；references/、scripts/、assets/：按任务需要读取或运行的资源。这一阶段只决定每条信息放在哪里，不重复撰写完整说明。同一条规则只保留一个权威来源，正文负责提示适用条件和资源入口，详细内容留在对应文件。
需要理解上下文、比较多种合理方案或创造内容时，Agent 的判断更有价值；需要精确计算、固定格式、重复转换和规则校验时，脚本通常更稳定。可以按下面的原则分工：
理解语义、比较方案、生成内容 → 文字指令 精确计算、格式转换、规则校验 → scripts/ 大量领域知识和字段说明 → references/ 最终交付要使用的模板和素材 → assets/
判断一个步骤是否需要脚本化，可以问三个问题：它是否会重复执行，是否要求精确数值或严格格式，执行错误是否会悄悄污染后续结果？如果其中两项以上为“是”，就应优先考虑脚本或校验器。比如，让 AI 判断客户反馈属于哪类问题很合适；让它每次临场重写同一段 Excel 格式修复代码则容易波动。开放式写作可以保留较高自由度，财务计算、文件转换和部署步骤则应使用参数化脚本、固定顺序与明确错误处理。新增脚本后还要用正常样例和边界样例真实测试，而不是只在文档里写“执行脚本”。
SKILL.md根据前面确定的职责、内容清单和资源路由，使用清楚的动作语言写明：
删除模型本来就知道的常识、过长的行业背景和“保持专业严谨”一类无法检测的要求。
至少准备三组测试：
| 测试类型 | 要验证的问题 |
|---|---|
| 应该触发 | 典型请求是否正确命中并读取 Skill |
| 不该触发 | 相邻任务是否被错误接管 |
| 边界任务 | 输入缺失、文件损坏或高风险动作时是否正确停下 |
执行测试不能只看最终文字，还要检查 Agent 是否读取了正确资料、运行了正确脚本、遵守了规定顺序，并输出可验证结果。
description 太泛结果可能是典型任务没有触发，或者所有相邻任务都被同一个 Skill 抢走。
背景和定义很多，真正的步骤、分支和完成标准很少。Agent 读完仍然不知道下一步做什么。
字段手册、行业规范和完整示例全部进入上下文，挤占当前任务真正需要的信息。
要求模型每次重新完成复杂格式转换、精确计算或文件结构修复，结果容易波动。适合确定性执行的步骤应由脚本和校验器承担。
示例看起来完整，遇到缺字段、错误文件、相邻意图或高风险动作时却没有处理方案。
“输出专业报告”不是可检查的完成标准。质量门槛应该具体到可以验证，例如：
高风险约束不能只写在 Skill 里。权限、审批、沙箱和审计仍应由宿主应用与工具层共同落实。
Skill 与 MCP 解决不同问题：
例如，一个销售复盘 Skill 可以规定先确认时间与指标口径，再按区域、产品和客户逐层分析；需要真实销售数据时，通过 MCP 调用受控问数能力；拿到数据后，再按企业模板生成报告。
没有 MCP，Skill 也可以处理本地文件和模板；没有 Skill，MCP 也可以执行单次查询。需要稳定完成跨系统任务时，两者通常会组合使用。
Skill 可能包含指令、脚本、外部链接和模板，安装第三方 Skill 应像安装软件依赖一样审查：
SKILL.md、脚本与引用文件；Skill 中的经验会过期。指标口径、模板、平台目录和外部 API 发生变化后，仍需更新与回归测试。
Prompt 通常服务于一次对话或一次任务；Skill 把一类任务的触发条件、工作流、资源和质量标准组织成可复用能力。Skill 可以包含 Prompt，但不等于把 Prompt 保存成文件。
不是每个 Skill 都需要脚本。需要理解语义、权衡方案或生成内容时，用自然语言工作流；需要精确计算、固定格式、重复转换、规则校验或高风险固定步骤时，优先使用脚本和校验器。
SKILL.md 应该写什么，越详细越好吗？不是。正文应保留核心工作流、领域规则、资源路由和质量门槛；长规范和低频资料应放入 references 并按需读取。
取决于宿主环境是否提供相应工具和权限。Skill 负责说明何时、怎样访问；真实连接通常由 MCP、API、CLI 或宿主内置工具提供。
基础结构可以复用，但安装目录、工具权限、脚本环境、网络访问和平台扩展字段可能不同。迁移前应按目标平台验证。
本文基于 Agent Skills 通用规范介绍结构与方法。不同产品可能对目录、字段、加载方式和运行环境作出扩展；具体交付前，应以目标 Agent 平台的当前文档和实际测试为准。
一个 Skill 也不能单独替代权限控制、数据治理或工程测试。任务越接近企业敏感数据和真实业务动作，越需要在工具层与基础设施层增加硬约束。