技能市场 SEO
优化 skill 在市场中的可发现性与被选中率：让 Agent 搜索技能市场时更早命中目标 skill、更快判定其适用性，并最终选择它。
脚本位于本 skill 基目录（Base directory）的 scripts/，下文以 $SKILL_DIR 指代。
0. 前提：技能市场的检索机制（实测结论）
动手前必须接受这三条实测结论，否则会把力气花在无效字段上。完整数据见 references/market-mechanics.md。
- 搜索只能看到元数据。 返回字段仅
skillId / name / version / description / categories / installedVersion / installed / updateAvailable——看不到 SKILL.md 正文、脚本内容、作者、下载量、评分、依赖与权限。 - categories 几乎不承担筛选职能。 全库仅十余个封闭 slug，每个 skill 平均挂 1.6 个标签，前四个标签占近七成标注量，且命名体系自身重叠（
education-learning与knowledge-learning并存、opc-solo-business与business-operations并存）。 - description 是唯一携带有效信息、也是唯一可被关键词命中的字段。
name只用于安装定位与去重（且存在大量近似重名，如markitdown与markitdown-skill、xlsx与excel-xlsx与minimax-xlsx）。
推论：所有 SEO 压力都在 description 上。
另一条关键前提：description 的读者是 Agent，不是终端用户。Agent 读它是为了做"要不要选它"的决策，因此竞品对比、失败兜底、能力边界这类信息必须写进去。这与"sell 话术不进面向用户的对话正文"完全不冲突——那是另一个受众、另一个载体。
1. 核心方法：三层漏斗
| 层级 | 要解决的问题 | 手法 |
|---|---|---|
| L1 可被搜到 | 关键词能否命中 | 覆盖竞品共识词、用户口语变体、链接与格式特征；中英双写 |
| L2 被留下 | Agent 初筛只读前 20~30 字 | 首句完成"是什么 + 交付什么"，并对齐该赛道既有的句式范式 |
| L3 被选中 | 凭什么选你而不是竞品 | 提炼竞品给不了的差异化锚点；主动给出风险对冲与免费出口；写清边界以提高选择准确率 |
L3 最容易漏、收益最大。 竞品越同质，"选我"的理由越必须在文案里显式给出——Agent 不会自己替你把优势推出来。
2. 工作流
Step 1 读取目标 skill
确认目标形态：用户给的是 skill 名、本地目录、还是市场里的一条记录。读取 SKILL.md 全文（frontmatter + 正文）。
正文中的「定位 / 为什么选它」「能力边界」「依赖说明」「信任话术」等章节，是差异化锚点的主要来源——优先从文档里挖，不要凭空编写卖点。
Step 2 提炼能力清单与差异化锚点
列三项：
- 能力清单：动词 + 对象 + 结果
- 交付物：最终交到用户手上的是什么（本地文件路径？报告？表格？一个链接？）——交付物形态常常就是最强的差异点
- 差异化锚点：竞品给不了的。常见来源：零配置 / 无需 API Key / 本地运行 / 失败兜底 / 可恢复续传 / 正规主体可追溯 / 有免费层 / 有明确边界声明
Step 3 采集竞品
用市场搜索工具按多组关键词取同类记录（每组 limit 取满 20），至少覆盖三类词：领域词、动作词、交付物词。把返回的 description 全部抄回来做对照。
同步统计：命中总数、竞品文案的句式范式、高频共识词、长度分布。
若当前环境没有市场搜索工具，降级为：读本地 ~/.workbuddy/skills/ 下同类 skill 的 description，或请用户粘贴竞品文案。
Step 4 关键词覆盖诊断
python "$SKILL_DIR/scripts/audit.py" --skill <skill 名或 SKILL.md 路径>
脚本输出字数、分段结构、通用关键词命中与反模式告警。再用 Step 3 的竞品文案补出「竞品在用而目标 skill 没用」的词——这是 L1 的关键增量。
Step 5 按三层漏斗重写
按 references/playbook.md 的句式范式与长度分档改写，产出三档，每档独立成立：
- 全量版（约 400~800 字符）→ 写入 SKILL.md frontmatter，供 Agent 加载时决策
- 精简版（约 100~150 字）→ 市场展示位
- 超短版（约 40 字）→ 卡片位
Step 6 合规红线自检
逐条对照 references/playbook.md 的红线清单。两条最容易踩：
- 不对竞品作法律或道德定性——构成商业贬损（《反不正当竞争法》第 11 条）。只陈述自己的客观事实，把判断留给 Agent。
- 不替产品方编写文档里不存在的声明（如"不抓包""不绕过技术措施""绝对安全"）。文档中没有的事实，写进文案即虚假宣传，风险远大于不做优化。
Step 7 应用与交付
python "$SKILL_DIR/scripts/apply_description.py" --skill <路径> --text-file <新文案文件>
脚本自动备份 frontmatter 并回读校验。随后必须用 present_files 交付报告，报告包含：诊断结论、三档文案、改动清单、合规风险提示。
3. 脚本
scripts/audit.py
解析 SKILL.md frontmatter（零依赖，不要求 PyYAML——description 常含中文标点与冒号，用 YAML 库反而易出错），输出 description 体检报告。
python "$SKILL_DIR/scripts/audit.py" --skill sph-downloader # 按名在 ~/.workbuddy/skills 下查找
python "$SKILL_DIR/scripts/audit.py" --skill ./my-skill/SKILL.md # 直接给路径
python "$SKILL_DIR/scripts/audit.py" --scan # 扫描全部已装 skill，对比长度与结构
python "$SKILL_DIR/scripts/audit.py" --skill X --json # 机器可读
检测项：字数与分档、分段结构、首句是否含动作词与交付物词、开头自我评价词、有无触发词段、有无边界声明、中英重复（疑似整段翻译）、关键词命中与缺失、斜杠分组歧义。
scripts/apply_description.py
把新 description 写回 frontmatter，自动备份 + 回读校验，支持 --dry-run。
python "$SKILL_DIR/scripts/apply_description.py" --skill X --text-file new.txt
python "$SKILL_DIR/scripts/apply_description.py" --skill X --text "直接给文案"
python "$SKILL_DIR/scripts/apply_description.py" --skill X --text-file new.txt --dry-run
4. 交付物
- SEO 体检报告（
.md）：诊断结论、三档文案、逐段设计意图、改动清单、合规风险提示 - 已更新的
SKILL.md：原 frontmatter 备份为SKILL.md.bak-<时间戳>
资源
references/market-mechanics.md— 技能市场检索机制的实测数据：字段清单、categories 分布、竞品文案范式、关键词堆砌现象references/playbook.md— 文案规范：长度分档、句式范式、反模式清单、关键词库、合规红线
