| name | skill-description-optimizer-yashu |
| description | 本技能专门优化技能的 description 元属性。激活条件：用户消息须包含以下关键词之一:`优化 description`、`优化技能描述`、`重写 description`、`改 description`、`诊断 description 问题`、`修复技能不激活`。 |
技能 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：重写 description
基于诊断结果，生成优化后的 description，并解释每一条改动的理由。
步骤 4：替换
使用 SearchReplace 工具将新的 description 写入目标技能的 SKILL.md。
工作原则
- 不瞎改正文：只动
description 字段，不修改 SKILL.md 的主体内容。
- 给出理由：每次优化必须解释"为什么这样改"，让用户知其所以然。
- 先诊断后下药：不要跳过诊断直接重写，确保每处修改都有依据。
