SKILL 创建指南
为 EasyAI Agent 创建技能(Skill),扩展 AI 的专业能力与工作流程
概述
Skill(技能)是 EasyAI 平台中用于扩展 Agent 能力的核心概念。每个技能包含一套完整的指令、参考文档、静态资源和可选脚本,让 Agent 能够在特定领域(如文档解析、周报生成、代码审查等)按规范执行任务。
Skill 与 Agent 的关系:Agent 创建时可关联多个技能(skills),模型在对话中可根据用户需求自动激活相应技能,获取其指令与资源。
技能的作用域
| 作用域 | 说明 |
|---|---|
| 系统级 (system) | 由管理员创建,可关联到任意 Agent |
| 个人级 (personal) | 由用户创建,在 AI Chat 中直接使用 |
技能结构
一个完整的技能由以下部分组成:
1. 主指令 (instructions)
即 SKILL.md 的 Markdown 内容,是技能的核心。它告诉 LLM:
- 何时使用此技能
- 如何处理用户输入
- 如何组织输出
- 参考哪些文档和资源
SKILL.md 建议结构(基于 Agent Skills 规范):
2. 引用文档 (references)
引用文档用于存放供 LLM 参考的详细内容,支持两种模式:
| 模式 | 字段 | 说明 |
|---|---|---|
| 直存模式 | markdown_content | 直接保存 Markdown 文本,无需上传 |
支持的文件类型:markdown
引用字段说明:
| 字段 | 必填 | 说明 |
|---|---|---|
| name | ✓ | 引用名称,在主指令中通过 @name 引用 |
| summary | ✓ | 概要,告诉 LLM 这是什么、何时使用 |
| file_type | ✓ | 文件类型 |
3. 静态资源 (assets)
用于存放不需要加载到上下文的静态资源,如 SVG 图标、图片、模板等。LLM 可直接使用资源的 URL。
| 字段 | 必填 | 说明 |
|---|---|---|
| name | ✓ | 资源名称(如 icon-report、company-logo) |
| url | ✓ | OSS 存储地址 |
| file_type | ✓ | 文件类型(png、svg、json、pptx 等) |
| description | 资源描述,告诉 LLM 何时使用 |
在主指令中可通过占位符引用,例如 {{icon-report}}。
4. 脚本 (scripts)
支持在技能中预置 Python 或 JavaScript 脚本,供开启脚本执行的 Agent 调用。模型可根据脚本描述选择并调用。
| 字段 | 必填 | 说明 |
|---|---|---|
| name | ✓ | 脚本名称(标识符) |
| language | ✓ | javascript 或 python |
| code | ✓ | 脚本源码 |
| description | 描述,帮助模型理解用途 |
Agent 需启用 features.enable_script_execution 才能执行脚本,详见 Agent 脚本开发指南。
创建技能的字段说明
创建技能时需填写以下核心字段:
| 字段 | 必填 | 说明 |
|---|---|---|
| name | ✓ | 技能标识符,如 document-parser、project-weekly-report |
| title | 显示名称,用于快速识别(如「文档解析器」) | |
| description | ✓ | 简短描述,用于发现阶段,建议包含触发词 |
| instructions | ✓ | 技能完整指令(SKILL.md 内容) |
| metadata | 版本号、作者、标签等 | |
| references | 引用文档列表 | |
| assets | 静态资源列表 | |
| scripts | 脚本列表 |
写作规范与最佳实践
描述 (description) 的写法
描述用于技能的发现,模型据此判断何时应用该技能。建议:
- 第三人称:以客观语气描述能力
- ✅「根据本周工作内容生成专业项目周报」
- ❌「我可以帮你生成周报」
- 包含 WHAT 与 WHEN:
- WHAT:具体能力
- WHEN:触发场景、关键词
- 示例:
主指令 (instructions) 的写作原则
- 简明优先:每个 token 都占用上下文,只写模型真正需要的内容。
- ** progressive disclosure**:核心说明放主指令,详细内容放引用文档,需要时再加载。
- 明确输出格式:对于报告、模板类技能,提供清晰的输出结构或 Markdown 模板。
- 信息处理策略:说明当用户提供简略信息时如何扩展,何时需要追问。
引用文档的引用方式
在主指令中通过 @引用名称 引用:
示例:平台创建 SKILL 的 JSON Demo
以下为符合平台创建技能接口的完整 JSON 示例,可直接用于 API 请求体或 MCP 工具调用。
| 字段 | 说明 |
|---|---|
name | 技能标识符,必填 |
title | 显示名称,可选 |
description | 简短描述,用于发现阶段,必填 |
instructions | SKILL.md 完整内容,必填 |
metadata | 版本、作者、标签,可选 |
references | 引用文档(直存模式用 markdown_content),可选 |
assets | 静态资源(需 OSS 地址),可选 |
scripts | Python/JavaScript 脚本,可选 |