技能橱窗 · 上架优化

> 【使用前必读】请先在 SkillHub 下载并安装本技能，装完才能在对话里触发：
> 搜索「技能橱窗」点「安装」，或执行 skillhub install skillhub-listing-optimizer

给你的技能写一份「用户三秒看懂、AI 也检索得到」的介绍——名字好记，概述说人话，详情页把价值讲透。

适用什么场景

• 技能刚做完，准备上架，介绍不知道怎么下笔
• 技能已经上架，但曝光少、点开的人不多
• 介绍是从技术文档里抄的，满屏术语，自己读着都费劲
• 想把同一份介绍复用到多个平台，但不知道哪些话该说、哪些该藏
• 想让技能被搜到（用户搜什么词能找到我），又不确定关键词往哪放

解决什么问题

技能介绍写不好，多数死在四件事上：

• 术语堆砌：满屏 pywinauto、CF_DIB、remarkGfm——用户看不懂，直接划走
• 不说人话：只讲「基于什么技术实现的」，不讲「能帮我避免什么麻烦」
• 排版一坨：整段纯文本不分层，内容再好也像说明书
• 位置放错：把详情页塞进不支持换行的地方，把技术细节甩给普通用户

介绍写不好，用户根本没机会知道你的技能好不好用。

优势点

独有的部分：平台各块「能放什么、会不会被吃掉」是实测出来的，不是猜的——

• 顶部概述区不支持换行，写 ##、-、换行都会原样显示或被折叠
• 概览页正文渲染的是 SKILL.md 正文，支持完整 Markdown（标题 / 列表 / 表格 / 代码块）
• 官方命令行工具解析 frontmatter 有 bug：多行概述和标签根本传不上去，发了等于没发

这三条决定了介绍该「写在哪一块」，是本技能和网上通用文案教程最大的区别。

怎么调用 / 触发

第一步：先拿到它

在 SkillHub 搜「技能橱窗」，点「安装」；或命令行：

skillhub install skillhub-listing-optimizer

装完常驻在你自己的技能目录，以后在对话里说话就能触发，不用每次重装。

第二步：在对话里直接说

• 「帮我优化这个技能的介绍」
• 「我的技能没人下载，介绍怎么写」
• 「给这个 skill 起个好搜的名字」
• 「按上架规范改一份 SKILL.md 并发布」

AI 会加载本技能，按下面的流程走：

1. 定位三层 —— 货架一句话（概述）、概览正文（详情页）、技术文档，各放各的内容
2. 重写 —— 名字按同行下载量数据定（短、有画面、不撞名），概述压到两句话，正文按五段框架重排，功能词全部下沉到 tags
3. 自检 —— 跑一次检查脚本，确认字段、字数、结构都合规
4. 发布 —— 用自带工具发布（自动带图标和分类），再验证平台实际生效的内容

第三步：装了和没装差在哪

不装，AI 也能帮你润色一段介绍，但它是凭通用文案感觉写的——不知道这个平台哪一块能换行、哪一块会吃掉 Markdown，也不知道官方发布工具的 frontmatter 解析有 bug，写完发上去照样缺字段。
装了，直接按实测过的规则来：三层内容各归各位、五段框架照着填、自检脚本先跑一遍再发，发完还能验证平台实际生效了什么。

边界

• 解决的是介绍怎么写、怎么发，不改变技能本身的功能和质量——技能不好用，文案救不回来
• 平台渲染规则基于当前实测，平台改版后需重新核对
• 发布工具依赖 SkillHub 账号与 API Token（skh_ 开头）
• 名字只能在合理范围内优化，不能承诺搜索排名
• 文案方法来自电商详情页的成熟打法，需结合你的技能实际调整，不套模板硬填

实施细节（给 AI 与开发者）

平台渲染规则（实测结论，先搞清「哪里能放什么」）

> 最容易踩的坑：把详情页写进 description 还用 Markdown 排版——用户看到的是「## 这是什么」原样字符 + 一坨文字。

写作方法：四个原则

1. 先定「第一购买理由」

> 对于处于【具体场景】的【目标人群】，本技能凭借【可验证能力】，帮他避免【具体事故】/得到【可感知结果】。

写不出这句，说明还没想清楚卖什么；写出来了，全文围绕它。

2. 把「效率」翻译成「事故」

用户为「省 20 分钟」付费的意愿，远低于为「避免发错群、避免发错钱」付费。
先列 3 条不加这个技能会出的事故（症状 + 后果），效率放在最后一条带过。

3. 卖点讲清「对你意味着」

每条卖点落到具体场景的结果：「20 家门店，点一次，你去倒杯水」，而不是「提升效率」。

4. 说人话 ≠ 牺牲 AI 检索

AI 靠具体名词和动词理解与检索，不靠术语堆砌——「自动把账单发到微信群」比「基于 pywinauto 的 UI 自动化方案」对 AI 更友好。
兼容做法：概述和正文的人话部分写具体对象 + 具体动作，技术术语（库名、API 名、协议名）放进正文技术章节和 tags，作为 AI 的检索钩子。人和 AI 各取所需，不冲突。

命名：名字留白，检索词下沉

先说结论：名字和检索词是两个岗位，别让名字去扛检索。

• 名字的岗位 = 被记住、被复述。 别人向同事推荐时会说出口的那几个字。
• 检索词的岗位 = 被搜到。 这件事交给 tags、summary 和正文，不靠名字。

同类 skill 的真实下载量对比：

同类里，功能罗列式命名全在三位数以下，唯一有记忆点的那个是它们的 500 倍。

道理不复杂：功能词（技能 / 上架 / 优化 / skill）在平台上遍地都是，堆进名字等于没区分度，口头传播时对方也记不住。名字留白，功能词全塞进 tags 和概述——「鲁班.skill」就是这么干的：名字只有 5 个字符，summary 里塞满「优化skill / skill评分 / 帮我改skill」等触发词。

怎么选名字（有数据可依，别拍脑袋）

1. 搜 3-5 个同类关键词（如「技能上架」「技能优化」），拿到同行列表
2. 查每个同行的下载量——平台的 skill 对象里就有：
   bash curl -s "https://api.skillhub.cn/api/v1/skills/<slug>" | grep -o '"downloads":[0-9]*'
   对应字段是 skill.stats.downloads / skill.stats.stars
3. 看哪种命名风格赢——下载量最高的那个名字长什么样
4. 避开已被高频占用的词（「技能上架」下已挤了多个同行），选一个没人占、又有画面的词
5. 名字定完，把舍弃掉的功能词全部下沉到 tags + summary + 正文的小标题里

好名字的四条标准

• 短：≤20 字，越短越好复述
• 有画面：能让人脑子里看见一个东西（橱窗 / 医生 / 门面 / 招牌）
• 说场景，不说实现：名字回答「什么时候用」，不回答「怎么做的」。
  搜索者永远按场景搜，不会按你的实现方案搜。
• 反例：「整行点击上传凭证（大热区交互）」——「整行点击」「大热区」是你代码里的方案，
  没人会这么搜；改成「表格传图 · 批量贴凭证」，场景一眼可见。
• 同理：「基于 pywinauto 的 UI 自动化」→「微信自动发送」。
• 一句话自检：把这名字念给同事听，他能不能立刻反应出「哦，是干那个用的」？
• 不撞名：先搜一遍，别跟已有 skill 重名或近名

反例：「XX 自动化框架 v2」「SkillHub-Listing-Optimizer」，以及功能词直接拼接——本技能旧名「技能上架优化」就是典型，三个通用词拼在一起，在数据里输给「鲁班.skill」500 倍。

> 折中做法（本技能在用）：「记忆点 + 检索词」双段式，如「技能橱窗 · 上架优化」——前半段负责被记住，后半段保底可搜。适合已经有流量但怕搜不到的场景；纯新品建议先用纯记忆点名字。

概述与标签公式

• summary（货架一句话）：≤60 字，说清「做什么 + 核心差异」，不含 Markdown 符号。这里可以放 1-2 个检索词。
• description（顶部概述）：两句话，第一句讲做什么，第二句讲防住什么 / 得到什么；不含任何 Markdown 语法、不含换行；开头必须用【】给出「使用前请先下载并安装本技能」的显著提示，结尾给安装方法（搜什么名字，或 skillhub install <slug>）——详情页读者是没装过的人，不写他会以为打开就能用。
• tags（检索词的真正载体）：4-8 个，把用户会搜的词全都放这里——通用词（技能上架、上架优化）+ 具体词（技能介绍、详情页文案）+ 技术钩子（SkillHub、skill）。名字里省掉的功能词，在这里补回来。

概览正文：五段框架（SKILL.md 正文，直接套）

# 技能名（一句定位）

> **【使用前必读】请先在 SkillHub 下载并安装本技能**，装完才能在对话里触发：
> 搜索「<短名>」点「安装」，或执行 `skillhub install <slug>`

**一句人话说清它做什么。**

## 适用什么场景
（4-6 条：什么人在什么情况下会需要它）

## 解决什么问题
（3-4 条，每条 = 症状 + 后果。收一句「不做这件事的代价」）

## 优势点
（对比表：凭感觉做 vs 用本技能；再写 1-2 条独有信息）

## 怎么调用 / 触发
（三段式：先讲怎么拿到 → 再讲装完说什么 → 最后讲装与不装差在哪）

## 边界
（诚实说 4-5 条：不支持什么、依赖什么、不承诺什么）

---

# 实施细节（给 AI 与开发者）
（架构、关键代码、坑与解法、故障速查——术语放这里）

> 五段框架的排序就是用户的决策顺序：这跟我有关吗 → 我有什么麻烦 → 它凭什么更好 → 我怎么用上 → 有什么限制。别打乱。

第 4 段「怎么调用」怎么写：先教获取，再教触发

最容易写崩的一段。 作者写的时候自己早就装了，顺手就写成「直接说这句话就行」——但详情页的读者是还没装的人，他连第一步该干什么都不知道，读完更迷糊。

平台的真实链路是：用户安装 → 技能落到本地技能目录 → 之后在对话里说触发词，AI 才会加载这份 SKILL.md 并按里面的方法执行。 不装，AI 只能凭通用能力临场发挥，每次结果都不一样——这正是「为什么要装」的理由，必须写出来。

所以这段固定三段，顺序不能反：

## 怎么调用 / 触发

**第一步：先拿到它**
在 [平台] 搜「<技能名>」，点「安装」；或命令行：
\`\`\`bash
skillhub install <slug>
\`\`\`
装完就一直在，不用每次重装。

**第二步：在对话里直接说**
- 「<用户会说的原话 1>」
- 「<用户会说的原话 2>」
- 「<用户会说的原话 3>」

AI 会加载本技能，按这个流程走：<1→2→3→4 步>

**第三步：装了和没装差在哪**
不装，AI 也能照着做，但每次凭临场理解，结果不稳定；
装了，走的是下面这套沉淀好的方法——<具体差异：踩过的坑 / 固定流程 / 校验规则>。

三条硬要求：

1. 必须出现「安装 / 获取」动作，并给出 slug（用户搜不到就只能放弃）
2. 触发话术写「用户的原话」，不是「本技能支持 X 功能」——用户是照着念的，句子要能直接说出口
3. 必须有「装了 vs 没装」的对照。这是全段唯一的转化推力，缺了它，读者会觉得「不装好像也行」

> 特例：技能若自带独立的软件/脚本（用户不装技能也能直接跑），要分开写成两条路径——「只想用这个能力 → 装技能，对话触发」/「已经在用配套系统 → 直接点界面按钮，技能是来学怎么做的」。混在一起写，读者会以为自相矛盾。

上线自检清单（scripts/listing_lint.py 一键检查）

• [ ] frontmatter 8 字段齐全：name / slug / displayName / summary / description / tags / license / version
• [ ] slug 为 kebab-case（小写字母数字连字符），version 为 SemVer（如 1.0.0）
• [ ] displayName 短（≤20 字）、有画面、不撞名；不靠名字扛检索词（检索词下沉到 tags）
• [ ] summary ≤ 60 字、无 Markdown 符号
• [ ] description 是两句话，无 #/-/|/换行，篇幅 80-320 字
• [ ] 正文有 1 个 H1 + 五段 H2（适用场景 / 解决什么问题 / 优势点 / 怎么调用 / 边界）
• [ ] 「怎么调用」段是三段式：写了怎么安装（含 slug）→ 用户的原话触发词 → 装了 vs 没装的差别
• [ ] tags 4-8 个，覆盖用户会搜的词（含 2-3 个技术钩子词）
• [ ] 图标（512px PNG）与分类已设置

python scripts/listing_lint.py <skill目录>

发布流程与坑

# 1. 自检
python scripts/listing_lint.py <skill目录>
# 2. 发布（自动传图标 + 带 category/iconUrl/tags/description）
python scripts/publish.py <skill目录> <版本号> <icon.png> "changelog 文本"
# 3. 验证平台生效内容
python scripts/publish.py --verify <slug> [等待秒]

实测坑（每条都踩过）：

1. 官方 CLI 的 frontmatter 解析器不支持 YAML 块标量——description: | 多行内容会被解析成字符串 |、tags 列表解析为空，导致 description 和 tags 从未上传成功。必须用本技能 scripts 里的解析器。
2. 版本号会被平台「预占」：报 VERSION_EXISTS 但版本列表里查不到 → 直接跳号（1.0.1 → 1.0.2）。
3. 连续发布会 429 限流：隔约 75 秒重试。
4. 发布成功 ≠ 立即可见：安全扫描 + 图标审核 + 索引，实测 2-5 分钟，期间 latestVersion 卡旧版本、新版本号查不到，都正常，用 --verify 轮询。
5. 图标和分类 CLI 发不了：图标走 POST /api/v1/community/skill-icons/upload（multipart 字段 file），分类和 iconUrl 要放进发布 payload（scripts/publish.py 已做）。
6. 分类 key 查 GET /api/v1/categories（办公效率 = office-efficiency）。

包含什么