1. 什么是 Skill

Skill 是挂载在 AI Agent 上的结构化指令包，用于封装特定领域的知识、工作流程和约束规范，使其成为可复用的模块化组件。

简单来说，就是把技能封装好，供 AI Agent 按需调用。

Skill 的核心价值：

• 固化复杂的多步骤工作流，避免每次靠 AI 自由发挥
• 把团队规范和历史经验注入 AI，保证输出风格与质量一致
• 通过"按需加载"机制，在不超出上下文限制的前提下引入大量知识

Skill 的使用场景：

• 需要重复执行的标准化任务（如报告生成、代码检查）
• 对输出格式或质量有严格要求的场景（如法律文书、医疗诊断建议）
• 需快速调用垂直领域知识的场景（如金融分析、学术研究辅助）

2 Skill 的三层加载机制

该流程分为三个层级：第一级是Frontmatter（包含名称和描述），始终存在于Agent上下文中，用于决定是否触发后续操作；第二级是SKILL.md正文（建议不超过500行），在触发后加载，用于描述工作流程、约束框架和文件加载指引；第三级包括reference/、rules/、knowledge-base/等目录，在执行特定步骤时按需读取，且没有大小限制。

层级	内容	何时加载	体积建议
第一级	name、description（可选 title、argument-hint）	始终在Agent上下文中触发判断	约百字级
第二级	SKILL.md正文（工作流/边界/执行前置/文件加载指引）	触发后加载	建议≤500行
第三级	reference/、rules/、knowledge-base/等附属资源	执行到对应步骤时按需读取	正文外无硬性上限

3. Skill 的目录结构

3.1 完整结构

your-skill-name/
├── SKILL.md                # 必须：技能主入口
├── scripts/                # 可执行脚本（重复性操作）
├── reference/              # 参考资料（模板、规范、知识型参考）
│   ├── template.md
│   └── README.md
├── rules/                  # 规则文件（.mdc，核心约束）
│   ├── {领域}/             # 领域级规则
│   └── chapter/            # 章节级规则（生成对应章节时读取）
├── knowledge-base/         # 历史案例库（供相似度匹配）
└── assets/          

注意：简单的Skill只需要有SKILL.md+reference即可

3.2 各目录职责

目录/文件	职责	示例
SKILL.md	入口：边界、前置、路由、步骤、输出格式	发消息前必须预览确认
scripts/	确定性操作：校验 JSON、批量写表、抽样	validate_payload.py
reference/	接口字段、配置说明、话术模板	MCP 参数映射、报告模板
rules/	强制约束，按领域/章节拆分	输出格式规范、Figma 读取规范
knowledge-base/	历史案例、badcase 样例，供对照	优化/劣化对比样例
assets/	不参与推理、直接使用的静态文件	.docx 模板、图标

4.SKILL.md 结构规范

4.1 Frontmatter（最关键）

Frontmatter 决定 Skill **是否被触发**；正文决定 **触发后怎么做**。

---

name: your-skill-name          # 唯一标识，与目录名一致，kebab-case

title: 用户友好的显示名称         # 可选，中文

description: >-                # 必须：WHAT + WHEN，第三人称，带触发词

  Generates formal test conclusions and badcase comparisons for OSEE vision

  models. Use when the user mentions badcase, 测试结论, 准出, 版本对比,

  or asks to summarize evaluation results.

argument-hint: [版本号/样例数/是否仅草稿]  # 可选，提示用户如何传参

disable-model-invocation: true # 可选，默认 true：仅点名或 @ 时加载

---

具体职责：

字段	必填	说明
name	是	最长 64 字符；仅小写字母、数字、连字符；与文件夹名一致
description	是	第三人称；写清做什么 + 何时用；含触发关键词
title	否	界面/文档友好名称
argument-hint	否	提示用户可传哪些参数
disable-model-invocation	否	true：须用户点名「用 xxx Skill」；省略则允许自动触发

4.2 必须包含的内容区块

## 什么时候使用 / 什么时候不使用
（明确边界，防止误用）
## 执行前置要求
（列出执行前必须读取哪些规则文件，以及跳过的后果）
## 工作流 / 执行步骤
（分阶段说明，每个阶段有明确的输入/动作/输出）

4.3 执行前置要求的写法

文件路径	作用描述	优先级类型
rules/评测/工作流规则.mdc	完整生成流程	强制
rules/评测/输出格式规范.mdc	结论与表格格式	强制
rules/评测/Figma读取规范.mdc	Figma 设计稿处理	条件（有 Figma 输入时）
reference/template.md	测试结论模板	强制