Skill 是一个带 SKILL.md 的文件夹，用来把某类任务的流程、领域知识和可复用文件交给 StablEdge 的 Agent。Agent 平时只看到每个 Skill 的名字和简介，判断任务用得上时才加载正文，需要时再读取附带的参考文档、模板或运行脚本。
什么是 Skill
可以把 Skill 理解成一份写给 Agent 的“上岗手册”。它适合沉淀这样一些内容：
- 多步骤流程：某类任务固定的操作顺序和检查点；
- 文件格式或接口的用法：例如读写某种文档、调用某个 API 的约定；
- 团队内部知识：数据结构、业务规则、写作规范；
- 可复用的文件：脚本、参考文档、模板和素材。
StablEdge 自带的 pdf、docx、xlsx、pptx 等内置 Skill 都是这种结构，可以当作参考。
Skill 还是插件
| 需求 | 建议 |
|---|---|
| 让 Agent 学会一套做事方法、遵守一套规则 | Skill |
| 给 Agent 提供参考资料、模板，或几个在沙箱里运行的脚本 | Skill |
| 需要自己的界面、后台常驻任务、存储或对外服务 | 插件 |
| 插件同时希望教会 Agent 怎么使用它 | 插件内附带一份 Skill |
插件可以附带自己的 Skill：插件启用后，它目录下的 SKILL.md 会以 plugin.<插件 ID> 为名注册，不参与自动激活，插件停用后随之失效。
Skill 由哪些部分组成
my-skill/
├── SKILL.md 必需：YAML frontmatter + Markdown 正文
├── reference.md 可选：按需读取的参考文档
├── scripts/ 可选：由宿主在沙箱里运行的脚本
│ └── run.py
└── assets/ 可选：模板、图片等产出用的文件
└── template.docx- frontmatter：至少包含
name和description。这两项始终对 Agent 可见，决定 Skill 会不会被选中。详见 SKILL.md 与 frontmatter。 - 正文：Skill 被加载后才进入上下文的操作指引。
- 附带文件：放在 Skill 目录里，Agent 通过
skill工具读取、复制或运行，详见 资源与脚本。
三级加载
| 层级 | 内容 | 何时进入上下文 |
|---|---|---|
| 1. 元数据 | name、description 等 frontmatter 字段 | 始终可见，用于检索和匹配 |
| 2. 正文 | SKILL.md 的 Markdown 正文；Progressive Skill 是“封面 + 章节索引” | Agent 加载该 Skill 时 |
| 3. 附带文件 | 参考文档、脚本、模板 | Agent 明确读取、复制或运行时 |
正文较长、分主题的 Skill 建议写成 Progressive 结构，Agent 只读取当前任务需要的章节，详见 Progressive 结构。
Agent 如何使用 Skill
Agent 通过内置的 skill 工具使用 Skill，支持以下动作：
| 动作 | 作用 |
|---|---|
list | 分页浏览已安装的 Skill（每页 50 条，简介截断到 80 字） |
search | 按任务关键词检索 Skill（默认返回 5 个，最多 10 个） |
load | 加载 Skill 正文；Progressive Skill 返回封面和章节索引 |
read_section | 按章节 ID 读取 Progressive Skill 的一个章节 |
list_files | 列出 Skill 目录里的附带文件 |
read_file | 把一个附带文件读进上下文 |
copy_file | 把附带文件复制到当前工作区 |
run_script | 由宿主在沙箱里运行 scripts/ 下的脚本 |
Skill 从哪里来
StablEdge 按以下顺序发现 Skill，同名时先发现的生效：
- 当前账号安装的 Skill（
<StablEdge 数据目录>/skills/user/）； - 已启用插件附带的 Skill；
- 随应用发布的内置 Skill。
内置 Skill 的名字是保留名。本地放一份同名副本不会覆盖内置版本，只会被忽略并给出诊断提示。给自己的 Skill 起名时请避开
pdf、docx、xlsx、pptx、skill-creator、plugin-creator 等内置名字。企业版可由管理员在服务端统一分发受管 Skill，这类 Skill 由企业管理，不在本文档范围内。
阅读路径
- SKILL.md 与 frontmatter：写出第一个能被正确识别的 Skill。
- Progressive 结构：正文变长后，按章节拆分。
- 资源与脚本：附带参考文档、模板和脚本。
- 安装与更新：从文件夹、ZIP、HTTPS 或 GitHub 安装，修改后自动同步。
- 最佳实践与示例：两个完整示例和常见错误。