name: skill-trigger-tuner
slug: skill-trigger-tuner
subtitle: Skill 触发面诊断与重写：给出可粘贴的 description/triggers 方案，并用盲测验证有没有真的变好
summary: 诊断单个 skill 的触发面（锚定/覆盖/排他/一致性/撞车/可测性），产出定位到行的问题清单、可直接替换的触发语文案，以及能做 P/R/F1 回归的盲测清单。
license: MIT
description: >
Skill 触发词优化器：给一个已存在的 skill 做触发面专项诊断，输出「健康分 + 六维结论 + 行级问题清单 +
可直接粘贴替换的 description / triggers / 边界句文案 + 可回算 P/R/F1 的盲测清单」。
六维覆盖：A 锚定（动宾是否具体）、B 覆盖（入口够不够多）、C 排他（边界是否生效）、
D 一致性（各字段是否同口径）、E 撞车（与已有技能是否抢）、F 可测性（能否构造盲测）。
判定引擎是纯标准库 Python 脚本，离线可跑、同一输入结果一致；只有「这句是不是人话」「能否与相邻技能区分」
两个语义项由 AI 按 rubric 打分补齐。
触发词：skill 不触发、技能没被触发、找不到我的 skill、触发词怎么写、when_to_use 怎么写、
这个 skill 抢了别人的活、误触发、触发率太低、提高触发命中、技能触发面、description 没人读、
trigger hit rate、skill not triggering、audit my triggers、why is my skill never used。
只做：对一个已存在的 skill 的触发面做诊断、重写文案与盲测；判断改写后有没有真的变好。
不做：改写 SKILL.md 正文逻辑、重设计交付物（归 skill-creator）；改文件名/补上架字段/打包发布（归 skill-publisher）；
把一个 skill 目录能否上架的整体体检做完（归 skill-package-check）；批量盘点几十个技能的触发 schema（归 zfl-skill-trigger-audit）。
边界争议时：问「这个包还能不能上架、缺什么字段」归 skill-package-check；问「调用率为什么低、整体打分」归 diagnose-skill-callrate；
问「帮我从零新建一个 skill」归 skill-creator；问「怎么打包上传」归 skill-publisher。
不适用：只想给技能起个更好听的名字（改名不涉及触发面）；尚未写好任何 SKILL.md 的空想法。
allowed-tools: Read, Bash, Glob, Grep
version: 1.0.0
display_name: "触发词优化器"
displayName: "触发词优化器"
display_name_en: "Skill Trigger Tuner"
description_zh: "Skill 触发词优化器：给一个已存在的技能做触发面专项诊断。输出健康分、六个维度的结论、定位到文件行号的问题清单、可直接粘贴替换的 description / triggers / 边界句文案，以及一份能做精确率与召回率回归的盲测清单。判定引擎是纯标准库 Python 脚本，离线可跑且同一输入结果一致；「是不是人话」「能否与相邻技能区分」两项语义判断由 AI 按 rubric 补齐。独有的闭环是盲测：把触发语当测试用例，改之前有一版分数，改之后再跑一次，用 P/R/F1 证明改动有没有真的生效，而不是凭感觉。"
description_en: "A trigger-surface tuner for AI Agent Skills. Given an existing skill, it audits the trigger surface across six dimensions (anchoring, coverage, exclusion, consistency, collision, testability) and outputs a health score, per-dimension verdicts, a line-level findings list, ready-to-paste replacements for description/triggers/boundary sentences, and a blind-test sheet that computes precision, recall and F1. The engine is a stdlib-only offline Python script producing identical output for identical input; two semantic judgements are scored by AI against an explicit rubric. What makes it different is the closed loop: keep a blind-test score before and after the rewrite so improvements are proven by metrics, not vibes."
category: development
author: "瑞阳AI应用笔记"
triggers:
- skill不触发
- 技能没被触发
- 找不到我的skill
- 触发词怎么写
- when_to_use怎么写
- 这个skill抢了别人的活
- 误触发
- 触发率太低
- 提高触发命中
- 技能触发面
- description没人读
- trigger hit rate
- skill not triggering
- audit my triggers
- why is my skill never used
tags:
- 触发率
- Skill优化
- 元技能
- 开发者工具
permissions:
read:
- 用户指定的单个技能目录或其 SKILL.md
- 用户自行提供的竞品描述文本文件（用于撞车比对）
write:
- 无。仅在用户显式指定 --blind-out 路径时写出盲测清单；不修改目标技能的任何文件
network:
- 无外部网络请求，纯离线静态扫描
agent_created: true

Skill 触发词优化器

角色

你是 skill 的触发面调音师。输入一个已存在但「叫不动」或「太爱抢」的技能，
输出：哪里写的不好 → 改成什么样 → 怎么证明改完真的变好了。

判断标准只有一个：改完之后，用户说人话时能命中，说别家的话时不命中。
文采、篇幅、理论完备度一律不计分。

取向声明（决定本 skill 怎么落地）：
以确定性脚本为判定主体，AI 只负责给替换文案和打两个语义分。
不做纯 AI 评审式打分——同一个 description 换模型会得不同分数，没法做回归。
规则有稳定编号（trigger-rules.md），同一份输入脚本侧永远给同一结果。

输入契约

不适用（明确转走）：见 frontmatter「边界争议时」四条。

工作流

第 1 步 · 跑诊断

python scripts/tune_trigger.py <技能目录或SKILL.md> --market <竞品文件>

脚本自动识别目录/文件，输出健康分与六维结论。
门禁：路径不存在 → 退出码 2 报错，不许继续。

第 2 步 · 亲自读一遍目标 SKILL.md

不许只看脚本输出就复述结论。 脚本给的是「命中规则」，
Agent 要判断这条命中在真实语境里成不成立。
每条替换文案涉及的行，都要你自己读过原文。

第 3 步 · 给替换文案（本技能的核心交付）

按 references/rewrite-playbook.md 的五步法，直接写出可粘贴替换的成品：
一段新的 description、一份新的 triggers 列表、一句新的边界句。
不要输出「建议加强动词」这种正确的废话。

门禁：每条替换文案必须说明针对哪个维度、解决了哪条规则命中。
说不清对应关系 = 这条文案没依据，删掉而不是凑数。

第 4 步 · 两个语义分（AI 兜底）

按 references/semantic-rubric.md 打 S1 是不是人话、S2 能否区分相邻技能，各 0–4 分：

AI 扣分 = (4 − S1) × 4 + (4 − S2) × 4
最终分  = max(0, 脚本分 − AI扣分)

门禁：每个分数附一句原文证据。说不出证据 = 该分作废，改为「证据不足，暂不扣分」。

第 5 步 · 出盲测清单并要求复跑

python scripts/tune_trigger.py <目标> --blind-out ./blind.tsv   # 生成
# 盲测：把清单里的句子逐条真问一遍，把 actual 列的 ? 换成 y/n
python scripts/tune_trigger.py --score ./blind.tsv              # 回算 P/R/F1

这是本技能与其他诊断工具的分水岭：改之前留一版分数，改之后再跑一次。
拿不出前后两版分数的，结论一律写「未验证」。

输出契约

固定六段，字段名写死：

1. 总体结论——健康分 /100 + 判定（READY · NEEDS WORK · REWRITE）+ 一句话说明
2. 六维结论——表格：维度 / 名称 / 阻断-警告-建议计数；有 --market 时附撞车表
3. 问题清单——严重度 / 维度 / 定位 / 问题 / 修复建议，定位精确到 文件:行号
4. 替换文案——可直接粘贴的新 description / triggers / 边界句，每条标注它修的是哪条规则
5. 盲测清单——应触发 N 条 + 不应触发 M 条，注明来源
6. 修复顺序——阻断 → 警告 → 建议，每步写清改哪个文件哪一行

结尾附免责：本报告只做诊断与文案建议，未修改任何文件；写入需你确认。

质量门禁

• [ ] 已实际运行 tune_trigger.py，结论基于真实输出而非推断
• [ ] 每条阻断/警告带 文件:行号 定位
• [ ] 替换文案每条都能指名它修的是哪条规则命中
• [ ] 两个语义分各附了原文证据
• [ ] 给了盲测清单，并明确「改完必须复跑才有结论」
• [ ] 未修改目标技能的任何文件

红线与反例

• 禁止直接改目标文件：本技能产出文案。要写入必须先给文案、等确认、再用 Edit 逐处改。
• 禁止凭感觉宣称"优化好了"：没有前后两版盲测分数，就写「未验证」。
• 禁止隐瞒撞车：相似度 ≥0.60 必须报阻断，哪怕用户急着上线。
• 禁止把目录里几十个技能一起扫：那不是本技能的场景（归 zfl-skill-trigger-audit）。
• 反例："建议优化 description，增加更多触发词。"
  → 正例："my-skill/SKILL.md:4 命中 A1（无任何具体动作动词）→ 改为
  把 PDF 转成结构化 Markdown 表格，对应 ACTION_VERBS 中的「转换」。"
• 反例："加个 md_trigger_words 字段。"
  → 正例：字段名以目标平台frontmatter 实际支持为准，未核实时写「此为建议写法，非平台公示字段」。

用法

python scripts/tune_trigger.py ../my-skill                       # 基础诊断
python scripts/tune_trigger.py ../my-skill --market market.tsv   # 含撞车检测
python scripts/tune_trigger.py ../my-skill --json                # 供流水线消费
python scripts/tune_trigger.py ../my-skill --blind-out ./b.tsv   # 落盲测清单
python scripts/tune_trigger.py --score ./b.tsv                   # 回算 P/R/F1

退出码：0 = 无阻断；1 = 有阻断项（诊断）/ 有失败用例（回算）；2 = 输入非法。

依赖说明：只用 Python 3 标准库（argparse / json / os / re / sys / io / datetime），
零第三方依赖、离线、不发起任何网络请求，不修改目标文件。
这是刻意的：触发面要不要重写，得能在任意机器上用同一份脚本判出同一个结论。

references

• references/trigger-rules.md：完整规则清单——六维 × 每条规则含判定标准、严重度、修复建议、执行方（脚本/AI），含自测中产生的真实豁免案例
• references/semantic-rubric.md：S1/S2 两个语义分的锚点、合并公式与反噪声纪律
• references/rewrite-playbook.md：重写五步法与「 fake 优化」识别清单