Index of every page on this site: llms.txt
All skills
steelan9199 avatar

/skill-description-optimizer-yashu

@9e01957
Run it yourself

本技能专门优化技能的 description 元属性。激活条件:用户消息须包含以下关键词之一:`优化 description`、`优化技能描述`、`重写 description`、`改 description`、`诊断 description 问题`、`修复技能不激活`。

  • 1 file
  • 12.5 KB
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/steelan9199/wechat-publisher/skill-description-optimizer-yashu

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈73 tokens for metadata: the name and description. ≈3.1k when used: this file.

Description uses 2.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈172 characters, or 2.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

技能 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 应控制在 ≤150 字,关键信息前置。

5. 长度硬上限:150 字(Hard Limit)

description 的总长度必须在 150 字以内,这是一条不可协商的硬性规则。

  • 计数口径:按字符数统计(中文字、英文字母、数字、标点、空格均计入),即 len(description) ≤ 150。
  • 超限处理:若优化后的 description 超过 150 字,必须继续删减,直到达标。删减优先级:内容构成 > 价值宣传 > 重复表述 > 次要关键词。
  • 不得超限的理由:超长 description 会稀释关键信号、抬高注意力分配的噪声占比,还会挤占其他技能的 description 空间。长度本身就是路由质量的一部分。
  • 不得以"信息完整"为由超限:信息完整性不是目标,路由准确性才是。宁可少列 1-2 个关键词,也不得突破 150 字。
正确示例(136 字):本技能专门优化技能的 description 元属性。激活条件:用户消息须包含以下关键词之一:`优化 description`、`优化技能描述`、`重写 description`、`改 description`、`诊断 description 问题`、`修复技能不激活`。
错误示例:在功能概述、激活条件之外,再补充"本技能还包含诊断清单、重写模板、冲突检测流程、多轮校验机制……"(内容构成堆砌,必然超限)

工作流

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

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

步骤 2:诊断问题

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

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

步骤 3:重写 description

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

输出前必须做长度校验:统计新 description 的字符数,若 > 150 字,按"5. 长度硬上限"的优先级继续删减并重新计数,直到 ≤150 字方可进入步骤 4。在结果中明确给出字数(如"共 136 字,符合 ≤150 字上限")。

步骤 4:替换

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


工作原则

  • 不瞎改正文:只动 description 字段,不修改 SKILL.md 的主体内容。
  • 150 字硬上限:任何优化结果都必须在 150 字以内,超限即视为未完成,必须继续删减。
  • 给出理由:每次优化必须解释"为什么这样改",让用户知其所以然。
  • 先诊断后下药:不要跳过诊断直接重写,确保每处修改都有依据。

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 9e01957. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 2 months ago
disable-model-invocation
false

README badge

README badge for steelan9199/wechat-publisher/skill-description-optimizer-yashu