Skill 设计规范

清海 AI 所有技能（SKILL.md）的标准化设计规范。新增技能必须按此规范编写，已有技能逐步对齐。

一、定位与原则

Skill 是什么

Skill 是清海 AI 的按需加载能力单元。每个 Skill 是一个独立文件夹，包含一份 SKILL.md，描述"这个能力做什么、怎么用、有什么限制"。

三层渐进式加载

第一层（始终存在）  system prompt 里只有技能名 + 路径 → AI 知道"我有哪些能力"
第二层（按需读取）  AI 自己 read SKILL.md             → AI 知道"怎么用这个能力"
第三层（实际执行）  tool_use 调用外部系统              → AI 拿到数据，完成任务

设计原则

原则	说明
一个 Skill 一件事	每个 Skill 聚焦一个业务领域，不混合不相关的能力
AI 读得懂	SKILL.md 是写给 AI 看的操作手册，不是给人看的产品文档
信息最小化	只写 AI 需要的信息，不堆砌背景知识和实现细节
trigger 决定命中率	trigger 写得准，AI 才能在正确的时机调用正确的技能
权限内置	涉及数据访问的 Skill 必须说明权限规则，AI 执行时自行判断

二、文件结构

目录约定

skills/
  {skill-name}/          # 小写 kebab-case，如 org-query、feishu-table
    SKILL.md             # 技能定义（必须）

文件夹名 = 技能名，和 SKILL.md 的 name 字段保持一致
一个文件夹只放一个 SKILL.md，不放其他文件

命名规范

类型	格式	示例
飞书类	`feishu-{功能}`	`feishu-table`、`feishu-approval`
组织类	`org-{功能}`	`org-query`
研发类	`{平台}`	`gitlab`
通用类	`{业务领域}`	`attendance`、`knowledge`

三、SKILL.md 模板

完整模板

markdown

---
name: {skill-name}
trigger: {触发关键词，竖线分隔}
description: {一句话描述，20 字以内}
tools:
  - {tool_name_1}
  - {tool_name_2}
scope: {all | boss | manager | employee}
---

# {技能中文名}

{一句话说明这个技能做什么，给 AI 快速定位用。}

## 可用工具

### `{tool_name_1}` — {功能}

**参数：**
- `param_1`（必填）— 说明
- `param_2`（可选，默认 xxx）— 说明

**返回：** {返回内容的简要描述}

**示例调用：**
```json
{
  "tool": "{tool_name_1}",
  "params": { "param_1": "示例值" }
}
```

### `{tool_name_2}` — {功能}

（同上格式）

## 使用流程

{描述 AI 应该按什么顺序使用这些工具。如果只有一个工具，可省略此节。}

## 权限规则

{描述不同角色能查什么、不能查什么。无权限要求的 Skill 可省略此节。}

## 回复规范

{描述 AI 回复时的语气、格式、风险标记等要求。}

## 注意事项

- {关键限制或易错点}
- {关键限制或易错点}

各字段说明

Frontmatter（YAML 头部）

字段	必填	说明
`name`	✅	技能标识，与文件夹名一致，kebab-case
`trigger`	✅	触发关键词，竖线分隔。AI 根据用户消息匹配，决定是否读取此 SKILL.md
`description`	✅	一句话描述，注入 system prompt 第一层，帮 AI 快速判断
`tools`	✅	此 Skill 提供的 tool_use 工具名列表
`scope`	❌	权限范围：`all`（默认，所有人可用）/ `boss` / `manager` / `employee`

trigger 写法规则

trigger 直接决定 AI 的调用命中率，是 SKILL.md 最关键的字段。

规则：

用用户会说的词，不用技术术语
覆盖同义词和口语表达
不同 Skill 的 trigger 之间不能有重叠

正例：

yaml

# org-query
trigger: 部门|成员|上级|下属|谁管|组织架构|团队|几个人|有谁

# feishu-attendance
trigger: 考勤|打卡|迟到|请假|加班|出勤

反例：

yaml

# 太笼统，和其他飞书 Skill 冲突
trigger: 飞书|查询

# 太技术化，用户不会这么说
trigger: bitable_query|api_call

Markdown 正文各节

章节	必填	说明
标题 + 一句话	✅	AI 读到的第一句话，快速确认"找对了"
可用工具	✅	每个 tool 的参数、返回、示例调用
使用流程	❌	多 tool 配合时写清顺序，单 tool 可省略
权限规则	❌	涉及数据隔离时必写，无权限限制时省略
回复规范	❌	有特殊语气/格式/风险要求时写
注意事项	✅	易错点、边界情况、硬性限制

四、Tool 设计规范

命名规则

{动词}_{对象}           查询类：query_department_members
{动词}_{对象}_{补充}     操作类：send_feishu_msg
list_{对象}s            列表类：list_bitables
search_{对象}           搜索类：search_contacts

全小写 snake_case
动词在前，名词在后
同一 Skill 内的 tool 用统一前缀（如 query_org_*）

参数规范

规则	说明
必填参数尽量少	降低 AI 调用门槛，能默认的就默认
参数名自描述	`department_name` 而不是 `name`
枚举值列清楚	`status: "pending"
时间参数统一	ISO 8601 格式：`2026-03-13` 或 `2026-03-13T10:00:00`

返回值规范

规则	说明
返回结构化 JSON	方便 AI 解析和二次处理
包含 `success` 状态	`{ "success": true, "data": [...] }`
错误信息人类可读	`{ "success": false, "error": "未找到部门：产品三部" }`
列表带总数	`{ "data": [...], "total": 15 }`

五、权限设计规范

涉及数据访问的 Skill 必须在 SKILL.md 中写明权限规则，AI 在返回结果前做判断。

三级角色模型

角色	标识	数据范围
老板	`boss`	系统全部信息
管理者	`manager`	本部门 + 公司公开信息
普通员工	`employee`	自己 + 公司公开信息

权限规则写法

在 SKILL.md 的「权限规则」章节，用表格列出：

markdown

## 权限规则

| 查询类型 | 员工 | 管理者 | 老板 |
| --- | --- | --- | --- |
| 公司部门列表 | ✅ | ✅ | ✅ |
| 部门成员列表 | ✅ 仅本部门 | ✅ 全部 | ✅ 全部 |
| 个人薪资/绩效 | ✅ 仅自己 | ✅ 本部门 | ✅ 全部 |

**被拒绝时的回复模板：**
「{信息类型}属于{隐私级别}信息，建议联系{引导对象}」

信息分级

级别	示例	默认可见范围
公开	部门列表、公司架构、部门成员名单	所有人
部门内部	部门项目进度、团队考勤汇总	管理者 + 老板
个人隐私	薪资、绩效、个人考勤明细	本人 + 上级 + 老板

六、回复规范

风险标记

Skill 返回的内容涉及外部可见操作时，AI 需标记风险等级：

等级	标记	场景
none	`<!--risk:none-->`	只读查询，无副作用
low	`<!--risk:low-->`	发消息通知、日程提醒
high	`<!--risk:high-->`	涉及金额、审批、敏感数据
block	`<!--risk:block-->`	必须老板确认才能执行

回复语气

场景	要求
正常返回	直接给结果，不加多余寒暄
查不到	友好提示 + 建议换个说法，不报技术错误
权限拒绝	说明原因 + 引导联系谁能帮忙
异常考勤/逾期	语气关心，不像系统通报

七、Skill 分类与分组

分组规则

Skill 在 system prompt 中按分组注入，AI 先定位分组再找具体 Skill：

xml

<available-skills>
  <group name="飞书" trigger="需要读取飞书任何数据时">
    <skill name="feishu-table" path="skills/feishu-table/SKILL.md" />
    ...
  </group>
  <group name="组织" trigger="查部门、成员、汇报线等组织信息时">
    <skill name="org-query" path="skills/org-query/SKILL.md" />
  </group>
  <group name="研发" trigger="查代码、提交、CI等研发信息时">
    <skill name="gitlab" path="skills/gitlab/SKILL.md" />
  </group>
</available-skills>

新增分组的时机

同类 Skill 达到 2 个以上时独立成组
只有 1 个 Skill 时归入最近的相关分组，或放在「通用」分组

八、Skill vs 常驻 Tool 判断标准

不是所有能力都需要做成 Skill，判断标准：

条件	做法
tool schema 自描述就够用，参数简单	常驻 Tool（始终注册在 tool_use）
需要详细说明用法、参数、流程、权限	Skill（SKILL.md 按需加载）
系统自动处理，AI 不需要主动调用	系统能力（不做 Skill）

当前常驻 Tool：

Tool	说明
`create_scheduled_task`	创建定时任务
`send_message`	发消息（飞书/TG）
`read_file`	读取文件
`search_memory`	深度检索记忆库

九、设计 Checklist

新建 Skill 时逐项检查：

[ ] 文件夹名 = name 字段 = kebab-case
[ ] trigger 覆盖用户常用说法，无技术术语
[ ] trigger 与其他 Skill 不冲突
[ ] tools 列表与正文「可用工具」一致
[ ] 每个 Tool 有参数说明 + 返回说明 + 示例调用
[ ] 涉及数据访问的 Skill 写了权限规则
[ ] 注意事项覆盖关键边界和易错点
[ ] 整个 SKILL.md 不超过 200 行（控制 AI 读取的 token 消耗）
[ ] 已同步更新 config.mts sidebar（如有对应文档）

十、完整示例

以下是一个符合规范的 Skill 完整示例：

markdown

---
name: org-query
trigger: 部门|成员|上级|下属|谁管|组织架构|团队|几个人|有谁
description: 查询公司组织架构信息
tools:
  - query_department_members
  - query_person_info
  - query_reporting_line
  - query_org_structure
scope: all
---

# 组织架构查询

查询公司的部门、成员、汇报关系等组织信息。

## 可用工具

### `query_department_members` — 查部门成员

**参数：**
- `department_name`（必填）— 部门名称，支持模糊匹配

**返回：** 成员列表（姓名、职位、是否兼职）

### `query_person_info` — 查个人信息

**参数：**
- `person_name`（必填）— 人名，支持模糊匹配

**返回：** 姓名、部门、职位、直属上级

### `query_reporting_line` — 查上下级

**参数：**
- `person_name`（必填）— 人名
- `direction`（可选，默认 "up"）— "up" 查上级，"down" 查下属

**返回：** 上级或下属列表

### `query_org_structure` — 查部门架构

**参数：**
- `root`（可选，默认公司根节点）— 起始部门名称

**返回：** 部门树结构

## 使用流程

1. 用户问组织相关问题 → 判断属于哪类查询
2. 模糊匹配命中多个结果 → 列出选项让用户确认
3. 返回结果前检查权限 → 越权则友好拒绝

## 权限规则

| 查询类型 | 员工 | 管理者 | 老板 |
| --- | --- | --- | --- |
| 部门列表 / 架构树 | ✅ | ✅ | ✅ |
| 部门成员列表 | ✅ | ✅ | ✅ |
| 个人基本信息（部门/职位） | ✅ | ✅ | ✅ |
| 个人敏感信息（薪资/绩效） | ❌ 仅自己 | ✅ 本部门 | ✅ |

**被拒绝时：** 「薪资属于个人隐私信息，建议联系人事部门的{人事负责人}」

## 注意事项

- 「产品」能匹配「产品部」，模糊匹配优先精确
- 同名时列出选项：「找到 2 位张姓同事：张三（产品部）、张四（研发部），你问的是哪位？」
- 兼职人员在部门成员结果中标注「兼」
- 查不到时：「没找到叫王六的同事，要不要换个名字试试？」

文档

电子表格

多维表格

知识库

Skill 设计规范

一、定位与原则

Skill 是什么

三层渐进式加载

设计原则

二、文件结构

目录约定

命名规范

三、SKILL.md 模板

完整模板

各字段说明

Frontmatter（YAML 头部）

trigger 写法规则

Markdown 正文各节

四、Tool 设计规范

命名规则

参数规范

返回值规范

五、权限设计规范

三级角色模型

权限规则写法

信息分级

六、回复规范

风险标记

回复语气

七、Skill 分类与分组

分组规则

新增分组的时机

八、Skill vs 常驻 Tool 判断标准

九、设计 Checklist

十、完整示例

Skill 设计规范 ​

一、定位与原则 ​

Skill 是什么 ​

三层渐进式加载 ​

设计原则 ​

二、文件结构 ​

目录约定 ​

命名规范 ​

三、SKILL.md 模板 ​

完整模板 ​

各字段说明 ​

Frontmatter（YAML 头部） ​

trigger 写法规则 ​

Markdown 正文各节 ​

四、Tool 设计规范 ​

命名规则 ​

参数规范 ​

返回值规范 ​

五、权限设计规范 ​

三级角色模型 ​

权限规则写法 ​

信息分级 ​

六、回复规范 ​

风险标记 ​

回复语气 ​

七、Skill 分类与分组 ​

分组规则 ​

新增分组的时机 ​

八、Skill vs 常驻 Tool 判断标准 ​

九、设计 Checklist ​

十、完整示例 ​

Skill 设计规范

一、定位与原则

Skill 是什么

三层渐进式加载

设计原则

二、文件结构

目录约定

命名规范

三、SKILL.md 模板

完整模板

各字段说明

Frontmatter（YAML 头部）

trigger 写法规则

Markdown 正文各节

四、Tool 设计规范

命名规则

参数规范

返回值规范

五、权限设计规范

三级角色模型

权限规则写法

信息分级

六、回复规范

风险标记

回复语气

七、Skill 分类与分组

分组规则

新增分组的时机

八、Skill vs 常驻 Tool 判断标准

九、设计 Checklist

十、完整示例