SKILL 创建指南

为 EasyAI Agent 创建技能(Skill),扩展 AI 的专业能力与工作流程

概述

Skill(技能)是 EasyAI 平台中用于扩展 Agent 能力的核心概念。每个技能包含一套完整的指令、参考文档、静态资源和可选脚本,让 Agent 能够在特定领域(如文档解析、周报生成、代码审查等)按规范执行任务。

技能的作用域

作用域说明
系统级 (system)由管理员创建,可关联到任意 Agent
个人级 (personal)由用户创建,在 AI Chat 中直接使用

技能结构

一个完整的技能由以下部分组成:

技能 (Skill)
├── 主指令 (instructions)     # SKILL.md 内容,必需
├── 引用文档 (references)     # 供 LLM 参考的文档,可选
├── 静态资源 (assets)         # 图片、模板等,可选
└── 脚本 (scripts)            # Python / JavaScript 可执行脚本,可选

1. 主指令 (instructions)

即 SKILL.md 的 Markdown 内容,是技能的核心。它告诉 LLM:

  • 何时使用此技能
  • 如何处理用户输入
  • 如何组织输出
  • 参考哪些文档和资源

SKILL.md 建议结构(基于 Agent Skills 规范):

---
name: your-skill-name
description: 简短描述,说明技能做什么、何时使用
---

# 技能标题

## 使用场景
- 场景 1
- 场景 2

## 信息处理策略
(当用户提供详细信息时 / 简略信息时的处理方式)

## 输出格式
(要求 LLM 严格按照的模板或结构输出)

## 参考文档
- \`@reference-name\` - 说明

## 注意事项
(关键约束与最佳实践)

2. 引用文档 (references)

引用文档用于存放供 LLM 参考的详细内容,支持两种模式:

模式字段说明
直存模式markdown_content直接保存 Markdown 文本,无需上传

支持的文件类型markdown

引用字段说明

字段必填说明
name引用名称,在主指令中通过 @name 引用
summary概要,告诉 LLM 这是什么、何时使用
file_type文件类型

3. 静态资源 (assets)

用于存放不需要加载到上下文的静态资源,如 SVG 图标、图片、模板等。LLM 可直接使用资源的 URL。

字段必填说明
name资源名称(如 icon-reportcompany-logo
urlOSS 存储地址
file_type文件类型(png、svg、json、pptx 等)
description资源描述,告诉 LLM 何时使用

在主指令中可通过占位符引用,例如 {{icon-report}}

4. 脚本 (scripts)

支持在技能中预置 PythonJavaScript 脚本,供开启脚本执行的 Agent 调用。模型可根据脚本描述选择并调用。

字段必填说明
name脚本名称(标识符)
languagejavascriptpython
code脚本源码
description描述,帮助模型理解用途

创建技能的字段说明

创建技能时需填写以下核心字段:

字段必填说明
name技能标识符,如 document-parserproject-weekly-report
title显示名称,用于快速识别(如「文档解析器」)
description简短描述,用于发现阶段,建议包含触发词
instructions技能完整指令(SKILL.md 内容)
metadata版本号、作者、标签等
references引用文档列表
assets静态资源列表
scripts脚本列表

写作规范与最佳实践

描述 (description) 的写法

描述用于技能的发现,模型据此判断何时应用该技能。建议:

  1. 第三人称:以客观语气描述能力
    • ✅「根据本周工作内容生成专业项目周报」
    • ❌「我可以帮你生成周报」
  2. 包含 WHAT 与 WHEN
    • WHAT:具体能力
    • WHEN:触发场景、关键词
  3. 示例
# 项目周报
description: 根据本周工作内容生成专业、美观的项目周报。适用于每周进度汇报、团队成果展示、风险追踪。

# 文档解析
description: 解析 PDF、DOCX、Markdown 等文档,提取文本与结构化内容。当用户上传文档或提及文档解析时使用。

主指令 (instructions) 的写作原则

  1. 简明优先:每个 token 都占用上下文,只写模型真正需要的内容。
  2. ** progressive disclosure**:核心说明放主指令,详细内容放引用文档,需要时再加载。
  3. 明确输出格式:对于报告、模板类技能,提供清晰的输出结构或 Markdown 模板。
  4. 信息处理策略:说明当用户提供简略信息时如何扩展,何时需要追问。

引用文档的引用方式

在主指令中通过 @引用名称 引用:

## 参考文档

- \`@writing-guide\` - 专业报告的写作规范
- \`@priority-guide\` - 任务优先级定义

示例:平台创建 SKILL 的 JSON Demo

以下为符合平台创建技能接口的完整 JSON 示例,可直接用于 API 请求体或 MCP 工具调用。

{
  "name": "project-weekly-report",
  "title": "项目周报生成器",
  "description": "根据本周工作内容生成专业、美观的项目周报。适用于每周进度汇报、团队成果展示、风险与问题追踪。",
  "instructions": "# 项目周报生成器\n\n根据用户提供的本周工作内容,生成结构清晰、内容丰富的专业项目周报。\n\n## 使用场景\n- 每周项目进度汇报\n- 团队工作成果展示\n- 项目风险与问题追踪\n- 下周计划制定\n\n## 信息处理策略\n\n### 当用户提供详细信息时\n直接根据用户提供的内容生成对应章节。\n\n### 当用户提供简略信息时\n发挥专业能力,智能扩展:任务拆解、数据推演、风险预判、计划细化等。仅在完全无法判断项目背景时追问。\n\n## 输出格式\n请严格按照模板输出周报(含本周成果、关键指标、风险与问题、下周计划等章节)。\n\n## 参考文档\n- @writing-guide - 专业报告的写作规范\n- @priority-guide - 任务优先级定义",
  "metadata": {
    "version": "1.0.0",
    "author": "EasyAI Team",
    "tags": ["report", "weekly", "project"]
  },
  "references": [
    {
      "name": "writing-guide",
      "summary": "专业报告的写作规范和最佳实践",
      "file_type": "markdown",
      "markdown_content": "# 周报写作规范\n\n## 写作原则\n- 结果导向:说明做了什么、达成什么效果\n- 数据支撑:用量化指标体现成果\n- 问题明确:风险与问题要具体可执行"
    },
    {
      "name": "priority-guide",
      "summary": "任务优先级的定义和分类标准",
      "file_type": "markdown",
      "markdown_content": "# 任务优先级指南\n\n| 级别 | 名称 | 定义 |\n|:----:|------|------|\n| P0 | 紧急 | 必须立即处理 |\n| P1 | 高 | 3天内完成 |\n| P2 | 中 | 本周完成 |\n| P3 | 低 | 可延后处理 |"
    }
  ],
  "assets": [
    {
      "name": "icon-report",
      "description": "报告主标题图标",
      "url": "https://oss.example.com/assets/icon-report.svg",
      "file_type": "svg"
    }
  ],
  "scripts": [
    {
      "name": "sum-calc",
      "description": "计算一组数字的和",
      "language": "python",
      "code": "def main(args):\n    return sum(args)"
    }
  ]
}
字段说明
name技能标识符,必填
title显示名称,可选
description简短描述,用于发现阶段,必填
instructionsSKILL.md 完整内容,必填
metadata版本、作者、标签,可选
references引用文档(直存模式用 markdown_content),可选
assets静态资源(需 OSS 地址),可选
scriptsPython/JavaScript 脚本,可选