# Skill Description Optimizer Yashu > 本技能专门优化技能的 description 元属性。激活条件：用户消息须包含以下关键词之一:`优化 description`、`优化技能描述`、`重写 description`、`改 description`、`诊断 description 问题`、`修复技能不激活`。 - Skill: `steelan9199/skill-description-optimizer-yashu` (Agent Skill) - Install (CLI): `npx skillmds add steelan9199/skill-description-optimizer-yashu` - Raw SKILL.md: https://api.skillmd.com/api/skills/steelan9199/skill-description-optimizer-yashu/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: steelan9199 (https://skillmd.com/u/steelan9199) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/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 的主体内容。 - **给出理由**：每次优化必须解释"为什么这样改"，让用户知其所以然。 - **先诊断后下药**：不要跳过诊断直接重写，确保每处修改都有依据。