SkillHub SEO 与评分优化器

对目标 SKILL 执行上架前的 SEO 优化与评分提升，系统性提升搜索发现率与质量评级。

何时触发

• "帮我把这个 SKILL 发布到 skillhub" / "上架这个技能"
• "优化这个 SKILL 的 SEO" / "提升搜索排名" / "让技能更容易被搜到"
• "提升这个 SKILL 的评分" / "冲击 S 级" / "优化质量评级"
• "发布前检查一下这个 SKILL" / "上架前自检"
• 用户即将执行 skillhub publish，或刚创建/修改完一个 SKILL 准备发布

何时不触发

• 用户只是编辑 SKILL 的业务逻辑（非上架场景）——直接帮编辑即可
• 用户要安装别人的 SKILL——用 skillhub install 流程，与本技能无关
• 用户要删除 SKILL——不涉及 SEO
• 用户在 skillhub 上搜索技能想找现成的——直接帮搜索即可，不触发优化
• 用户想修改已发布 SKILL 的业务逻辑但不重新上架——直接帮改代码，不需要 SEO

能力边界

能做：
- 按五维度评估目标 SKILL 当前得分，输出优化建议
- 优化 frontmatter（tags 扩充、description 前置、补必需字段）
- 优化正文结构（新增评分相关章节）
- 指导补充 references（usage-examples.md 等）
- 执行打包 → dry-run → 发布全流程
- 生成优化前后对照报告

不能做：
- 不能保证具体排名名次（服务端排序算法部分黑盒）
- 不能替用户决定业务逻辑或工作流设计
- 不能编造虚假评分数据
- 不能绕过 skillhub 的安全审核
- 不能自动获取真实用户的评分反馈数据（需技能上架后由用户产生）

输入输出规范

输入：
- 目标 SKILL 的目录路径（必需）——指向包含 SKILL.md 的目录
- SkillHub API token（发布时必需）——skh_ 开头，用于 publish
- 优化偏好（可选）——如"只优化不发布""目标评级 S 级"等

输出：
- 优化后的 SKILL.md（原地修改，保留原有逻辑）
- 新增的 references 文件（如 usage-examples.md）
- 优化前后对照报告（五维度评分对比）
- 打包产物 zip（位于指定输出目录）
- 发布结果（skillId + 版本号 + 审核状态）

输出位置：
- SKILL.md 修改：原地（目标 SKILL 目录）
- 新增 references：目标 SKILL 的 references/ 目录
- 打包 zip：用户指定的输出目录（默认与源目录同级）
- 发布结果：SkillHub 平台（审核通过后公开上架）

工作流

Step 1：读取并评估目标 SKILL 现状

1. 读取目标 SKILL 的 SKILL.md 完整内容
2. 如存在 references/ 目录，列出其中文件
3. 按五维度评估当前状态（加载 references/skillhub-rating-rules.md 获取详细评分标准）：
   - 描述清晰度（25%）：description 是否前置功能+触发条件？是否覆盖高频搜索词？
   - 指令质量（30%）：工作流是否分步编号？复用资源是否渐进式披露？
   - 资源完整度（20%）：references 数量？是否含 usage-examples？
   - 触发精度（15%）：是否有"何时触发"+"何时不触发"+"能力边界"？
   - 维护状态（10%）：version 是否 SemVer？是否有 changelog？是否有 homepage？
4. 输出当前预估评级（S/A/B/C）和各维度得分

Step 2：优化 frontmatter（SEO 核心）

1. tags 扩充至 12-15 个，覆盖四类搜索词：
   - 场景词（用户会搜的功能场景）
   - 平台词（涉及的平台/工具名）
   - 英文词（对应英文关键词）
   - 功能词（品类词如"办公自动化""生产力"）
2. description 前置"功能 + 触发条件"：先说做什么，再说何时触发，最后说差异点。覆盖高频搜索词。
3. summary 一句话说清价值主张：用户能获得什么、省多少时间。
4. 补必需字段：slug（kebab-case 全局唯一）、displayName、version（SemVer 严格）、license、platforms、homepage。
5. 关键约束：description 必须单行字符串，禁用 YAML 多行 >- 语法（package_skill.py 不兼容）。

Step 3：优化正文结构（评分相关章节）

1. 保留原有工作流逻辑——不改动业务步骤，只补评分章节。
2. 新增/强化以下章节（加载 references/seo-publish-checklist.md 获取详细模板）：
   - "何时触发"——扩充触发词，覆盖用户可能用的各种表述
   - "何时不触发"——≥5 种排除场景（提升触发精度 15%）
   - "能力边界"——能做/不能做各 5 项（提升 Adaptability）
   - "输入输出规范"——明确输入要求和输出格式（提升 Convention）
3. 复用资源改为渐进式披露表格：列出每个 reference 文件、用途、加载时机。
4. 重要约束映射 TRACE 五维：每条约束标注对应维度（如"外发确认→Trust""异常反馈→Reliability""平台中立→Adaptability"）。

Step 4：补充 references（资源完整度 20%）

1. 确认是否已有 usage-examples.md——若无则创建，含 ≥3 个完整场景示例 + 最佳实践 + FAQ。
2. 确认 references 总数 ≥2-3 个（除 usage-examples 外，按需补 conversion-strategy / api-docs / schemas 等）。
3. 确保 SKILL.md 正文中引用了所有 references 文件（渐进式披露表格）。

Step 5：打包与 dry-run 校验

1. 用 skill-creator 的 package_skill.py 打包（会校验 frontmatter + 结构 + 文件类型）：
   bash PY="C:/Users/adam/.workbuddy/binaries/python/versions/3.13.12/python.exe" PKG="C:/Users/adam/AppData/Local/Programs/WorkBuddy/resources/app.asar.unpacked/resources/builtin-skills/skill-creator/scripts/package_skill.py" "$PY" "$PKG" <skill-src-dir> <output-dir>
2. 用 skillhub CLI dry-run 校验（不需登录）：
   bash CLI="C:/Users/adam/.skillhub/skills_store_cli.py" "$PY" "$CLI" publish <zip-path> --dry-run
3. dry-run 失败则按错误信息修复（常见：缺 slug/displayName/version、description 含尖括号、version 非 SemVer）。

Step 6：发布（需用户 token）

1. 确认用户已登录（~/.skillhub/credentials.json 存在）。未登录则提示用户执行 login --key skh_xxx。
2. 发布：
   bash "$PY" "$CLI" publish <zip-path> --changelog "<本次变更说明>"
3. slug 冲突时换备选 slug（displayName 不变），重新打包发布。
4. 发新版时 version 必须递增（如 1.0.0 → 1.1.0）。

复用资源

重要约束

• 不编造评分：评估结果基于实际文件内容，不杜撰分数或评级承诺（→ Trust）
• 不绕过审核：不尝试绕过 skillhub 的安全检测，dry-run 失败必须修复后再发布（→ Trust）
• 保留原有逻辑：优化只补评分章节、扩 tags、改 description 表述，不改动 SKILL 的核心工作流和业务逻辑（→ Reliability）
• version 必须递增：发新版时 version 必须高于已发布版本（→ Reliability）
• description 单行：禁用 YAML 多行 >- 语法，package_skill.py 不兼容（→ Convention）
• TRACE 映射务实：重要约束章节每条标注对应 TRACE 维度，但不为凑维度而编造约束（→ Convention）