steelan9199/skill-description-optimizer-yashu

技能 Description 优化器 - 优化技能描述

"一个技能的 description，决定了 AI 是否会在合适的时机找到它。"

技能的 description 是 YAML frontmatter 中的元属性，AI 用它来做技能路由 -- 即判断用户的意图是否匹配某个技能。如果 description 写得模糊、笼统、与其他技能重叠，AI 就可能在需要时漏掉你，或在不该激活时误触发。

---

LLM 路由原理

在优化任何 description 之前，必须先理解 LLM 是如何做技能路由的。否则写出的规则可能看似合理但实际无效。

LLM 的技能路由本质是概率预测，在机制层面表现为注意力匹配。AI 在收到用户消息后，会将消息内容与所有技能的 description 做语义/关键词匹配，匹配度最高的技能被触发。由于训练数据的分布特性，description 中的规则性文本（如激活条件声明）在概率层面会影响路由决策。

关键认知：description 中的排除文本对路由效果不可靠

优化者可能以为，在 description 中写排除条件（如"若消息以 QA 开头则不触发本技能"）就能避免误触发。但这种做法在多数场景下效果不如正向条件可靠，不推荐使用。 原因如下：

1. 注意力机制（Attention Mechanism）

当用户消息中的词与 description 中的关键词匹配时，注意力机制给该技能高权重。关键在于：description 中提及的任何概念都会获得注意力信号，无论该概念出现在正向条件还是排除条件中。

这就解释了为什么正向条件比排除条件可靠：正向条件（"须包含X"）提及 X，X 获得注意力信号，而这恰好是你想要的--你希望 X 出现时触发本技能，信号增强与目标一致。排除条件（"若消息以 QA 开头则不触发"）同样提及 QA，QA 也获得注意力信号，但这与你想要的相反--你希望 QA 出现时不触发，信号增强却推向了触发。换言之，"不要梨"让 AI 对"梨"的注意力不降反升，因为"梨"这个词被提及本身所带来的信号增强，大于否定词带来的抑制。

2. 信息检索视角（Information Retrieval）

技能路由是一个 IR 问题。用户消息是 query，技能 description 是 document。在 IR 中，文档内添加排除文本对检索得分的降低效果有限--被排除的概念仍然作为文档的一部分参与语义匹配。更糟的是，排除文本引入了本想回避的概念，扩大了这些概念的误匹配面积。

结论：不要在 description 中写排除条件来解决关键词冲突--正向条件让注意力信号为目标服务，排除条件让注意力信号与目标对抗。正确的做法是收窄冲突关键词本身，用正向条件引导路由。

---

信息论视角：信号与噪声

description 中的每一句话都消耗 token，但不是每一句话都对路由决策有贡献。优化者必须用信息论的视角，区分信号与噪声。

description 中的信息可分为四类，第一类和第四类对路由决策有直接贡献：

1. 能力定位（保留）

技能"能做什么"--其目的、角色、功能边界。

• 回答的问题：这个技能是干什么的？
• 抽象示例：做X、定义X的法则、优化X的Y属性
• 对路由的贡献：强信号。帮助 AI 判断用户意图是否与技能能力匹配。
• 判断特征：描述技能的外部功能，用户读到后能判断"这个技能是否与我的需求相关"。

2. 内容构成（删除）

技能"包含什么"--其内部结构、格式、组件。

• 回答的问题：这个技能里面有什么？
• 抽象示例：包含A、B、C、提供X步骤和Y模板、内含X框架
• 对路由的贡献：弱信号/冗余。对路由决策贡献很小，信息与能力定位高度重叠。
• 删除理由：AI 在选择技能时需要的是"该不该选"，而非"选了之后会看到什么"。内容构成信息在路由决策之后才有价值，在决策过程中不提供增量信号。
• 判断特征：描述技能的内部内容细节，用户读到后只知道"配料"，但无法据此判断是否需要这个技能。

3. 价值宣传（删除）

技能"带来什么好处"--营销式的好处声明或结果承诺。

• 回答的问题：这个技能有多好？
• 抽象示例：确保X友好、提供高质量Y、让X更优秀
• 对路由的贡献：噪声。无区分度，任何技能都可以声称同样的好处。
• 删除理由：价值宣传没有区分度，无法帮助 AI 把这个技能和其他技能区分开。它消耗 token 却不提供路由信号。
• 判断特征：营销式语言，描述结果或承诺而非功能。

4. 结构性引导文本（保留）

description 中可能包含结构性引导文本，如激活条件声明"激活条件：用户消息须包含以下关键词之一:"。这类文本是格式约定，用于为关键词提供语义上下文，对路由决策有直接贡献。

判断规则速查

| 信息类型 | 回答的问题 | 对路由决策的贡献 | 处理方式 | | -------------- | -------------------- | ---------------- | -------- | | 能力定位 | 这个技能是干什么的？ | 强信号 | 保留 | | 内容构成 | 这个技能里面有什么？ | 弱信号/冗余 | 删除 | | 价值宣传 | 这个技能有多好？ | 噪声 | 删除 | | 结构性引导文本 | 这是什么格式的约定？ | 强信号 | 保留 |

---

关键词选择原则：动作导向优于纯名词

在注意力匹配中，关键词的语义丰富度决定区分度。纯名词（如 SOP）语义单一，可出现在多种语境中--"SOP是什么？""制定SOP""SOP流程如下"都包含这个词，注意力机制无法区分这些截然不同的意图。动作导向短语（如 制定SOP）语义更丰富、更具体，只在用户明确要执行某动作时才形成强匹配，因此区分度更高。

核心原则：关键词应采用动作导向短语，而非纯名词--因为动作导向短语在注意力匹配中比纯名词更具区分度。

• 制定SOP -- 语义具体，只在用户要创建 SOP 时强匹配
• SOP -- 语义模糊，"SOP是什么？"也会强匹配，容易误触发

---

纯名词使用指南

纯名词不应作为触发关键词。 纯名词语义单一，在注意力匹配中区分度不足，容易导致不相关的消息被误路由到本技能。所有纯名词都应收窄为动作导向短语。

| 纯名词 | 问题 | 收窄建议 | | ------ | -------------------------------------- | ---------------------------- | | 扣子 | 纯名词，语义模糊，区分度不足 | 调用扣子、测试扣子智能体 | | SOP | 既出现在"SOP是什么？"也出现在"制定SOP" | 制定SOP、生成SOP | | 飞书 | 纯名词，语义模糊，区分度不足 | 操作飞书、管理飞书文档 |

---

核心目标

审查并重写目标技能的 description 字段，使其满足以下标准：

0. 功能概述 (Function Overview)

description 首句必须用一句话说清楚技能是做什么的，让 AI 读到第一眼就心里有数。功能概述即"能力定位"信息（见上文信息论视角）在 description 首句中的具体体现。

正确示例：本技能专门优化技能的 description 元属性。
错误示例：这是一个很有用的技能。（什么都没说）

1. 激活条件声明

使用以下句式：激活条件：用户消息须包含以下关键词之一:\X`、`Y`。`

激活条件声明列出正向触发条件--即明确哪些关键词会触发本技能。如上文注意力机制所述，正向条件提及的关键词会获得注意力信号，且信号方向与触发目标一致，因此比排除条件可靠。

description 的推荐结构顺序为：功能概述 -> 激活条件声明 -> 关键词清单。

2. 关键词锚点 (Keyword Anchors)

列出 3-6 个用户可能说出的具体触发短语，用反引号 ` 包裹，方便 AI 做字面匹配。

动作导向原则：关键词应为动作导向短语（见上文纯名词使用指南）。

正确示例：`制定SOP`、`给我一个操作流程`
错误示例：`SOP`、当用户需要结构化方案时（太泛）

3. 语言覆盖 (Language Coverage)

用户群体是中文用户，触发关键词应匹配目标用户群体的真实表达习惯。中文用户在技术语境中常混合使用中英文（如"优化 description"），关键词应覆盖用户最可能使用的表达形式。

4. 简洁可扫描 (Scannable)

AI 在毫秒级做出路由判断，description 应控制在 <200 字，关键信息前置。

---

工作流

步骤 1：读取目标技能并获取可用技能列表

读取用户指定的技能的 SKILL.md，提取当前的 description 字段和正文内容。同时获取系统提供的可用技能列表，提取各技能 description 中的关键词，建立关键词索引以便后续检测跨技能关键词冲突。

步骤 2：诊断问题

对照上述标准，逐条诊断当前 description 的问题：

• [ ] 首句是否说清了技能是做什么的（功能概述）？
• [ ] 是否包含内容构成或价值宣传描述？如有，应删除（保留能力定位和结构性引导文本）。
• [ ] 是否保留了结构性引导文本（如激活条件声明"激活条件：用户消息须包含以下关键词之一:"）？
• [ ] 关键词是否为动作导向短语？
• [ ] 关键词数量是否在 3-6 个之间？
• [ ] 触发关键词是否匹配用户真实表达习惯（含中英混合场景）？
• [ ] 是否简洁（<200字）？
• [ ] 是否存在与其他技能的关键词冲突？如有，是否已通过收窄关键词解决？
• [ ] 结构顺序是否符合"功能概述 -> 激活条件声明 -> 关键词清单"？

步骤 3：重写 description

基于诊断结果，生成优化后的 description，并解释每一条改动的理由。

步骤 4：替换

使用 SearchReplace 工具将新的 description 写入目标技能的 SKILL.md。

---

工作原则

• 不瞎改正文：只动 description 字段，不修改 SKILL.md 的主体内容。
• 给出理由：每次优化必须解释"为什么这样改"，让用户知其所以然。
• 先诊断后下药：不要跳过诊断直接重写，确保每处修改都有依据。