技能市场 SEO 优化器
诊断并优化 WorkBuddy / SkillHub 技能的搜索曝光能力。这是"卖铲子"的技能——帮别人的技能被搜到。
Overview
技能做得好不等于有人用。SkillHub 上已有 4 万+ 个人技能，绝大多数从未被搜到过。本技能把「让技能被搜到」这件事从玄学变成可量化的工程动作。
核心产出：一份带分数的体检报告 + 可直接复制的优化后 description + 平台表单填写文案。
验证过的效果：某公众号排版技能用本方法优化后，30 个模拟搜索词的 description 命中率从 23% → 93%，上架后获 4.5 分评价。
核心认知：搜索是怎么发生的
不懂这个，优化就是瞎猜。
| 层级 | 内容 | 何时进入上下文 |
|---|---|---|
| L1 | name + description |
始终在，用户每次对话都被 AI 读取 |
| L2 | SKILL.md 正文 | 仅在被触发后加载 |
关键推论：
- 用户不只靠搜索框找技能，更多时候是 AI 替他找。 用户说「帮我排版公众号文章」，AI 拿所有已装技能的
description做语义匹配，决定调不调用你。description写不好，AI 根本想不起你——看都不会看你正文一眼。 description是唯一的常驻广告位，正文写得再好，触发不了就是零。- 所以优化优先级：
description> 平台展示名 > 正文 >name。
五条铁律
铁律 1：frontmatter 只能有 5 个字段（违反 = 技能消失）
官方规范只允许：name / description / license / allowed-tools / metadata。
网上教程（含腾讯云开发者社区那篇）教你加 trigger:、tags:、category: —— 不要加。解析器遇到未知字段会报错，技能直接从列表消失，且不给明确提示。
关键词必须塞进 description 和 metadata.keywords，不能靠新增字段。
> agent_created 是 WorkBuddy 生态特有字段，属于例外，保留无害。
铁律 2：name 上线后不要改
改 name = 改目录名 = 平台视为新技能，已有下载量、评分、评论全部清零，还要重新审核。
name 必须是小写连字符（如 skill-seo-optimizer），中文用户搜不到。解法在平台表单：提交时的「显示名称」可以填中文，那才是曝光主战场。
铁律 3：description 按 7 类搜索意图铺词
不要写一段通顺的营销文案，要铺关键词。7 类框架见下方工作流。
铁律 4：包内只能有安全文件类型
.bat .command .exe .sh .app 会被上传校验拒绝。报错只列第一个违规文件就中断——修一个再传一次是浪费时间，必须一次全清。
需要双击运行能力时，改成「包内放一个 .py，用户运行后本地生成启动器」。
铁律 5：展示名要堆关键词，不要写品牌名
市场头部技能的真实命名：「视频短视频图片音乐音频配音口播数字人全能创作」（15.1万）、「全能金融爬虫」（10.1万）。这是关键词战争，不是 branding。
工作流
第 1 步：体检
python scripts/audit_skill.py <技能目录或zip路径>
可选 --json 输出机器可读结果，--strict 把警告也当失败（适合 CI）。
拿到报告后，先处理所有 ❌ 项，再处理 ⚠️。
第 2 步：补关键词
python scripts/keyword_expander.py # 交互式，逐项问
python scripts/keyword_expander.py --subject "公众号排版" --competitors "秀米,135编辑器"
按 7 类框架产出词表，并拼装成可直接复制的 description 草稿。
7 类搜索意图框架：
| 类别 | 说明 | 举例（以排版技能为例） |
|---|---|---|
| 1 主体词 | 用户怎么称呼这个东西 | 公众号排版、微信图文排版、推文排版 |
| 2 同义词 | 同一事物的不同叫法 | 图文排版、文章排版、自媒体排版 |
| 3 动作词 | 用户想干什么 | 转换、生成、一键、批量、导出 |
| 4 痛点词 | 用户遇到什么问题 | 格式丢失、排版乱了、表格没颜色 |
| 5 竞品/替代词 | 用户现在在用什么 | 秀米、135编辑器、i排版、壹伴、Markdown Nice |
| 6 英文词 | 海外用户 + AI 语义匹配 | wechat editor、markdown to wechat |
| 7 场景/人群词 | 谁在什么情况下用 | 产业链梳理、投资早报、自媒体写作 |
第 5 类最容易漏，也最值钱：用户搜「有没有替代秀米的免费方案」，命中你 = 直接抢竞品的精准流量。
第 3 步：改写 description 并复检
按下面模板组织（顺序即优先级）：
<主体词 / 同义词>：<一句话说明做什么>。适用于<场景词>。
用户说这些话时使用：<用户的原话，越口语越好>。
产出：<具体交付物>。<差异化/信任背书>。
<英文段落>。Triggers on: <英文触发词>。
改完再跑一次 audit_skill.py，确认分数提升且无 ❌。
第 4 步：填平台表单
| 字段 | 填法 |
|---|---|
| 显示名称 | 堆关键词，不写品牌名。20 字以上优先 |
| 描述 | description 前 30 字最关键（卡片会截断），把最强关键词放开头 |
| 版本号 | 重大更新跳主版本号，小修跳修订号 |
| 变更说明 | 务必写一句「核心逻辑未改，输出格式不变」——降低审核方风险判断，加快放行 |
| 分类 | 选错 = 自断流量，参考同类头部技能所在分类 |
第 5 步：冷启动
上架不等于有流量。垂直工具类天花板在 10 万级，靠自然流量爬升极慢。
必须自己推第一把：把技能发到自己的渠道（公众号 / 社群 / 朋友圈），把下载量冲起来，才有机会进飙升榜拿到自然流量。
评分体系
| 维度 | 分值 | 说明 |
|---|---|---|
| A 合规性 | 一票否决 | 字段非法 / name 不合规 → 直接不合格 |
| B name 规范 | 10 | 小写连字符、长度 ≤64 |
| C description 质量 | 35 | 长度区间 + 7 类意图覆盖 + 首 30 字 |
| D 文件安全 | 20 | 类型白名单 + 包体积 |
| E 结构完整 | 20 | SKILL.md、references、allowed-tools、metadata |
| F 正文触发词 | 15 | 正文是否有触发词速查表 |
等级：90+ 优秀可直接提交 ／ 75-89 良好 ／ 60-74 建议优化 ／ <60 风险较高 ／ 合规不通过直接判不合格。
常见失败场景
| 症状 | 原因 | 解法 |
|---|---|---|
| 提交报「不允许的文件类型」 | 包内有 .bat/.command/.exe |
一次全清，改成本地生成启动器 |
| 提交报「已存在相同的名字」 | 本地已装同名技能 | 卸载本地同名技能，不是改名 |
| 技能在市场搜不到 | frontmatter 有非法字段 | 删除 trigger/tags/category 等字段 |
| 上架后零下载 | 分类选错 / description 无关键词 | 改分类，按 7 类重铺词 |
| 评分被扣可靠性 | 缺库时抛英文 traceback | 延迟 import + 中文提示 + 自动安装引导 |
| 评分被扣适用性 | 只有会命令行的人能用 | 加交互式向导 |
上手门槛
零第三方依赖，纯 Python 标准库（刻意不依赖 pyyaml，因为用户环境不一定装了——缺库抛 traceback 正是技能被扣可靠性分的常见原因）。任何失败场景都输出中文提示和解决办法。
Resources
scripts/audit_skill.py— 体检打分主工具scripts/keyword_expander.py— 关键词生成与 description 草稿references/playbook.md— 完整方法论、市场真实数据、平台规则细节references/case-study.md— gzh-article-html 从 23% 到 93% 的完整复盘assets/intent-patterns.json— 7 类搜索意图检测词库（可自行扩充）
