Skill规范

一、Skill的颗粒度

Skill的范围和颗粒度做多大？

Skill的边界界定遵循“微服务化与单一职责”原则。过大的Skill会导致模型幻觉增加、意图识别混乱；过小的Skill会导致上下文碎片化。

• 单一意图闭环（推荐边界）：一个Skil只解决一个完整的业务诉求。例如，年假申请Skill包含了“查余额->判断是否合规->提交请假单”，这是一个完美的闭环。

• 警惕“大而全”（越界危险）：不要建立例如万能HR助手这样的超级Skill。当一个Skill同时包含招聘、薪酬、绩效、请假等十几个API接口时，大模型的“工具选择幻觉”会急剧增加，导致执行混乱。

二、Skill设计规范

文件结构

skill-name/
├── SKILL.md          # 必须，主文件
├── tool_schema.json  # 必须，系统自动生成
├── references/       # 可选，按需加载的文档
└── assets/           # 可选，按需加载的文档

标准Skill通常为一个包含以下内容的目录：

• SKILL.md (必选): 技能描述文档。包含技能概述、功能说明、输入参数要求、输出格式和具体操作指引。定义Skill的触发条件和执行步骤，启动时只加载 name和 description，当用户请求匹配时才加载完整指令。

  • 文件名必须是 SKILL.md，大小写敏感，不接受 skill.md 或 SKILL.MD

  • SKILL.md 由两部分组成：顶部的 YAML frontmatter 和下方的 Markdown 正文。

  • Frontmatter部分包含name和description 2个必填字段。【name】：2-64 个字符，【description】：触发描述，最长 1000 字符。Agent 凭此字段决定是否激活 Skill

  • SKILL.md 内容建议控制在 500 行，否则会影响执行效果，最大不超过 2000 行或 80000 字符。

• references/ (可选): 参考资料子目录。提供详细的上下文知识、文档或说明书。存放参考文档和输出模板。把详细的格式定义放在这里，而不是塞进 SKILL.md，保持主文件的精简。

三、Skill编写示例

打车SKILL.md示例

注意：AAA111.query_horoscope是tool唯一标识，规范是{pluginCode}.{toolName}。

---
name: 星座运势查询
description: 当用户想要查询十二星座运势时使用。Use when: 星座运势、查运势、今日运势、明天运势、本周运势、本月运势、今年运势、星座查询、看看运势、运势怎么样、帮我查运势、十二星座运势、星座今日运势、我运势如何。
---

# 全局强制规则

1. **星座参数可缺省**：用户未提供星座时，`constellation` 留空，由服务端按 userId 自动回填历史记忆；若服务端返回 NEED_CONSTELLATION，必须追问用户星座，不得自行猜测或默认。
2. **时间类型映射**：用户说"今天/今日" → `today`；"明天/明日" → `tomorrow`；"这周/本周" → `week`；"这个月/本月" → `month`；"今年/本年" → `year`；未指定默认 `today`。
3. **播报优先**：查询成功后使用 `<cmd>Speak</cmd>` 播报运势内容，播报前加垫词让过渡自然。
4. **禁止杜撰运势**：所有运势内容必须来自 `rawResponse.model.text`，绝不自行编造运势文本。
5. **错误静默降级**：工具返回 `success=false` 时，不暴露错误码，用友好话术告知用户稍后再试。

# 概览

查询十二星座的今日、明日、本周、本月、本年运势，涵盖综合运势、爱情、事业、财运、健康、幸运色、幸运数字等维度，以语音方式播报给用户。

# 使用模式

## 查询星座运势

**触发词**：星座运势、查运势、今日运势、明天运势、本周运势、本月运势、今年运势、看看运势、运势怎么样、帮我查运势、我运势如何、星座今日运势

**调用序列**：

1. 从用户输入提取星座名（如"白羊座"）和时间范围（如"今天"），映射为工具参数
2. 调用 ^^AAA111.query_horoscope^^(constellation=白羊座, type=today)
3. 检查 `rawResponse.success`：
   - `true` → 读取 `rawResponse.model.text`，组装话术播报
   - `false` 且 errorCode 为 NEED_CONSTELLATION → 追问用户星座
   - 其他失败 → 友好提示稍后再试

**参数示例**：

| 用户说 | constellation | type |
|---|---|---|
| "白羊座今天运势" | 白羊座 | today |
| "看看天蝎座本周运势" | 天蝎座 | week |
| "查运势" | （留空） | today |
| "双鱼座明年运势" | 双鱼座 | year |

**话术**：

- **A 类（成功播报）**：
  - "帮您查到啦～{constellation}{type_text}的运势来了：{text}"
  - "{constellation}{type_text}运势出炉～给您播报一下：{text}"
  - "好的，{constellation}{type_text}的运势是这样的：{text}"

- **B 类（追问星座）**：
  - "请问您是什么星座呀？告诉我才能帮您查运势哦～"
  - "需要知道您的星座才能查询呢，您是哪个星座？"
  - "告诉我您是什么星座，我马上帮您查～"

- **C 类（垫词 / 转场）**：
  - "好的，这就帮您看看～"
  - "没问题，马上查询～"
  - "来，帮您看看运势～"

**追问策略**（≤ 1 轮）：
- 追问 1 次用户星座，若用户仍不提供则播报默认话术引导结束。

# 规则 DO / DON'T

**DO**：
- 用户未指定星座时留空 constellation，依赖服务端回填
- 成功时用 `<cmd>Speak</cmd>` 播报完整运势文本
- 追问时语气亲切自然

**DON'T**：
- 不要自行编造运势内容
- 不要在用户未说明星座时随意指定一个星座
- 不要暴露工具错误码或内部字段名
- 不要一次查询多个星座（一次只查一个）