rayskills · builder 实战工具箱
8 个从真实业务中沉淀的 AI Skill：默认替你判断下一步，也能把稳定流程连续跑完。
本地知识库 · 长文 · 口播 · 封面 · 解说视频 · 平台草稿
rayskills 是一套给 Claude Code、Codex 等 AI Agent 使用的 builder 工具箱。它不是一堆“应该怎么想”的提示词，而是把真实工作中反复出现、容易犯错的流程，收敛成可以直接执行、可以验证、可以恢复的 Skill。
不用先记住 8 个名字。把处境交给 /ray：
- 下一步还不稳定时，它只选择此刻最该做的一步。
- 终点已经明确、阶段之间有正式交接时，它连续执行整条管线。
- 涉及删除、发布、生产修改等高影响动作时，仍然守住确认边界。
你：这篇英文文章写得很好，想翻译过来发公众号
→ /ray-writer 译介模式先过授权与署名两道门
→ source_permission 没放行就停在本地译文
→ 拿到许可后再进平台草稿
你：把这个 idea 写成文章，做公众号和 X 封面，再放进两个平台的草稿箱
→ /ray-writer 完成长文与质量检查
→ /ray-cover 生成各平台封面
→ /ray-wechat 确认排版并更新公众号原草稿
→ /ray-x-article 保存并验证草稿
→ 停在草稿，不自动发布
你：把这篇定稿继续做成一条口播视频
→ /ray-kb 重新选择一个视频判断
→ 以 Ray 口吻生成逐字稿，拿不准的内容列进「待确认」
→ 要做成解说视频时再交给 /ray-explainer
你：我刚有一个企业 AI 的灵感，查完资料就想直接录
→ /ray-kb 按需检索素材，以你的口吻直接写
→ 只建立一份快速口播母稿，拿不准的内容列进「待确认」
→ 录制后对照实际表达，发布后进入反馈回流
🎯 你交给它什么，它替你完成什么
| 你手上的 | rayskills 完成的 | 入口 |
|---|---|---|
| 一个空目录或已有 Obsidian 库 | 安全建立资料、知识、候选选题、写作任务、母稿、发布反馈与回流骨架 | /ray-obsidian |
| 一个 idea、剪藏或旧草稿 | 读者收获、事实边界、Ray 语气、连续自然的中文长文 | /ray-writer |
| 一个能在一条视频讲清的灵感，或一篇已经核验的长文 | 生成唯一快速口播母稿，或重新选角度生成完整口播内容包 | /ray-kb |
| 一篇已经定稿的文章或视频 | 文章：按内容写封面文案、选一种风格，按黑白灰 + 墨绿 IP 分别输出公众号、普通 X、X Article 封面；视频：Ray 真人照片 + 大标题的 9:16 / 3:4 竖封面 | /ray-cover |
| 定稿文章、公众号封面与排版偏好 | 手机端富文本预览、原草稿更新、UTF-8 回读验收 | /ray-wechat |
| 一篇文章或剪藏，想做成知识讲解视频 | 1.5–3 分钟竖屏解说片：从手绘套路和 8 种解说语法（动态文字、Kurzgesagt、白板、3b1b……）里整期只选一种画法，可穿插真实照片 / 历史影像，本人复刻音色配音，Whisper 逐字卡点；左下角卡通数字人主持人默认按拼音对口型，大机位（Kling 生成手势）要先报价确认。想要每期专属风格时走 HyperFrames 模式：真实截图当证据、本机实跑工具的真实输出、配乐与音效、并行做场景，发布包直接并进口播母稿 | /ray-explainer |
| 长文与 5:2 封面 | 查重或恢复原草稿，写入 X Articles，检查预览与保存 | /ray-x-article |
| 别人写的好文章 | 译介模式：授权与署名两道门，全文翻译或编译，不洗稿 | /ray-writer（译介模式） |
| 不知道从哪里开始 | 读取当前处境，替你选下一步或正式管线 | /ray |
🧭 一张图看懂
flowchart TD
RAY(["/ray · 主路由与阶段编排"]):::hub
RAY --> KNOWLEDGE["🗂 本地知识库<br/>obsidian"]
RAY --> CONTENT["✍️ 内容 / IP<br/>writer（长文 · 译介） · kb（口播）<br/>cover · wechat · x-article · explainer"]
OBSIDIAN["ray-obsidian<br/>资料 · 知识 · 候选 · 写作任务 · 母稿"] --> WRITER["ray-writer<br/>长文 · 译介"]
WRITER --> COVER["ray-cover<br/>封面文案 · IP 风格 · 平台封面"]
OBSIDIAN --> KB["ray-kb<br/>快速口播 · 长文再分发"]
WRITER --> KB
OBSIDIAN --> EXPLAINER["ray-explainer<br/>解说视频 · 数字人主持"]
KB --> EXPLAINER
COVER --> WECHAT["ray-wechat<br/>公众号排版 · 草稿回读"]
COVER --> XARTICLE["ray-x-article<br/>查重 · 预览 · 草稿"]
classDef hub fill:#b8553a,stroke:#7a3320,color:#fff,font-weight:bold;
更细的交接关系见 skill 关系图。
🏭 已跑通的长文生产管线
这条管线来自一次完整的真实生产过程，不是把三个 Skill 用箭头连起来就算完成。
| 阶段 | 负责什么 | 必须通过的门控 |
|---|---|---|
ray-obsidian（按需） |
新建或适配用户自己的本地知识库 | 先预演；已有文件零覆盖、零移动；结构检查为 ready |
ray-writer |
从 idea、资料或草稿生成中文长文 | 表达先行，以作者口吻说满观点；拿不准或编补的内容进「待确认」由作者决定；长文通过格式检查 |
ray-cover |
按内容写三层封面文案，从 Punk 风格库（MIT 版）选一种风格，套 Ray 的黑白灰 + 墨绿 IP | Codex CLI 调 Image 2 按公众号、普通 X、5:2 Article 各自生成；逐字与颜色验收，不跨平台裁切复用 |
ray-kb（按需） |
从灵感直接做唯一口播母稿，或把定稿母稿改编成口播内容包 | 表达先行，编补内容进「待确认」；快速模式不制造额外任务；长文模式绑定母稿指纹；口播检查通过 |
ray-wechat |
把定稿与公众号封面送进微信草稿箱 | 先确认手机预览；优先更新原草稿；标题、摘要、封面、全文、署名和 UTF-8 回读通过 |
ray-x-article |
把本地成稿送进登录中的 X Articles | 优先恢复原草稿；富文本保留标题与加粗；空白段落为零；封面、首尾、预览和保存状态全部核对 |
管线支持中断恢复。例如浏览器暂时不能读取本地封面时，会保留同一草稿并记录 draft-needs-cover；权限恢复后只补封面，不重新建稿，也不重复写正文。
完整门控与恢复规则见 Ray 长文生产管线。
🗂 Skill 全目录（8）
| 线 | Skill | 干什么 |
|---|---|---|
| 🧭 路由 | /ray |
读取处境，选择下一步；终点明确时编排正式管线 |
| 🗂 知识库 | /ray-obsidian |
新建、检查或增量适配本地 Obsidian 内容知识库 |
| ✍️ 内容 | /ray-writer |
idea / 资料 / 草稿 → 中文长文；他人文章 → 译介稿 |
/ray-kb |
灵感与检索 → 唯一快速口播母稿；定稿长文 → 绑定母稿指纹的完整口播内容包 | |
/ray-cover |
定稿文章 → 公众号、普通 X、X Article 封面；视频 → 9:16 / 3:4 竖封面 | |
/ray-explainer |
文章 / 剪藏 → 代码绘制的解说视频（手绘套路或一种 huashu 解说语法，一期只用一种画法、复刻音色配音、逐字卡点、左下角数字人主持人）；或 HyperFrames 专属风格模式（每期单独设计，真实截图 / 录屏 / 实跑输出） | |
/ray-wechat |
定稿文章与公众号封面 → 已验证的微信公众号草稿 | |
/ray-x-article |
长文与 5:2 封面 → 已验证的 X Articles 草稿 |
/ray-post（公众号热点、选题、写作与发布）仍在独立仓库 WeWrite。ray-writer 处理证据型长文，ray-wechat 只接收定稿并负责排版与草稿验收；三者不混用。
📊 实测与验证
rayskills 把“文档写完”与“Skill 真能防错”分开检查。
| 检查 | 当前结果 | 含义 |
|---|---|---|
| Skill 数量 | 8 | 包含 /ray 主路由与 7 个成员 |
| 场景测试 | 66 | 正常、边界与失败场景均记录在各 Skill 的 evals/evals.json，部分 Skill 使用更细分类 |
| 结构校验 | 8 / 8 通过 | 名称、目录、frontmatter 与资源结构有效 |
| 对照实测 | 15 / 15 skill-helps | v1 基准的 15 个 Skill 均明显优于裸模型（历史口径） |
| 带 Skill 满足断言 | 100% | v1 对照实测口径 |
| 裸模型满足断言 | 35.7% | v1 对照实测口径 |
v2 做过一轮成熟度精简：删除了 ray-tweet、ray-idea、ray-cleanup、ray-weekly，把 ray-diagnose + ray-proposal 合并为 ray-consult、ray-vpsinit + ray-nodecheck 合并为 ray-vps、ray-thread 并入 ray-writer 的 thread 骨架模式（后已移除）。
v3 按真实使用频率再收敛一轮：ray-benchmark、ray-launch、ray-metrics、ray-report、ray-vps 移出到独立仓库 ray-skills（按需独立使用的 Skill 集，不依赖 /ray 路由）——它们自 v1 以来没有产生真实调用记录，与高频的内容生产管线也没有阶段交接；ray-consult 当时经复核保留。方法论没有丢：移出的 Skill 完整保留全部流程与 eval 场景。v1 对照实测报告按当时的成员名单记录，作为历史证据保留，不随精简改写。
v4（2026-10-13）用同样的标准再收敛一轮：ray-consult、ray-multimodel、ray-trend-search、ray-broll 移到 ray-skills。统计 Claude Code 与 Codex 的会话记录，它们近 30 天几乎没有真实调用（解说视频由 ray-explainer 接手，拼贴 B-roll 不再是主线）；/ray 在本机装了它们时仍会路由过去。老用户升级请看 从旧版本升级。
最能体现 Skill 价值的不是文风，而是防住真实损害：
| Skill | 防住的问题 |
|---|---|
/ray-obsidian |
不覆盖、移动或批量改写用户已有笔记 |
/ray-writer |
不在正文里自保，也不交付没有阅读锚点的长文 |
/ray-writer 译介模式 |
不把别人的文章洗成自己的原创，授权没落地不进平台草稿 |
/ray-kb |
不让快速口播变成重流程，也不在逐字稿里自保 |
/ray-wechat |
不重复建微信草稿、不把中文乱码或接口成功码误判成完成 |
/ray-x-article |
不重复建稿、不丢富文本格式、不把输入完成当成保存完成 |
/ray-explainer |
不把语气指令念进配音，不把年份按数值念（2019 不会变成“两千零一十九”），不在画面里编具体金额和名称，不在没看过静帧的情况下出片，不在没报价、没确认时生成数字人 |
完整的 15 项带 / 不带 Skill 记分卡见 对照实测报告（历史成员名单）。
✅ 适合 / ❌ 不适合
适合：
- 一个人或小团队同时处理基建、内容、咨询、产品和运营。
- 想把真实实践沉淀成可复用、可验证流程的 builder。
- 使用 Claude Code、Codex 等 Agent 完成真实业务，而不只是问答。
- 需要 Agent 既能主动做完，又能在发布、删除和生产修改前守住边界。
不适合：
- 只需要一个领域的超深度专用工具。
- 纯陪聊、纯灵感或无需验证的一次性问答。
- 希望 Agent 无条件自动发布、自动删除或绕过确认。
- 不在这些真实工作流中的通用任务。
🚀 安装
安装全部 Skill：
npx -y skills add imraywang/rayskills -g --all
国内访问 GitHub 慢时，可以从 Gitee 镜像拿代码（与 GitHub 同步更新）：
git clone https://gitee.com/imraywang/rayskills.git
安装后可以从 /ray 开始，也可以直接调用具体 Skill：
/ray 我有个客户想上 AI 客服，不知道该先做什么
/ray 把这个 idea 走完整条内容管线，做到 X Articles 草稿，不要发布
/ray-obsidian 在这个本地目录搭一套可以接写作管线的知识库
/ray-writer 把这条剪藏发展成一篇公众号长文
/ray-kb 我有一个现场观察，直接做成快速口播
/ray-kb 把这篇定稿改成一条 2 到 3 分钟的口播视频稿
/ray-cover 给这篇定稿文章做公众号和 X Article 封面
/ray-wechat 把定稿排版并更新到已有公众号草稿，先预览再写入
/ray-x-article 把文章和 5:2 封面保存到 X 后台，不要发布
/ray-explainer 把这篇剪藏做成 2 分钟竖屏解说视频，用我的声音
/ray-explainer 这期别套固定风格，要真实截图和录屏，配上数字人
第一次使用建议先看 新手入门。
已有 ray-content-v1 知识库不需要搬家：ray-obsidian 会先预演，再补齐现行结构并保留全部旧目录和文件。
从旧版本升级
装过 v1（21 个 skill）、v2（14 个 skill）或 v3（13 个 skill）的用户注意：重新执行 skills add 只会新增和刷新现存的 8 个成员，不会删除远端已经不存在的旧 skill。旧目录会以过期副本留在本地，其中 ray-diagnose、ray-thread 等还会和现有成员抢触发，建议先清理再更新：
for s in ray-tweet ray-idea ray-cleanup ray-weekly ray-thread ray-diagnose ray-proposal ray-vpsinit ray-nodecheck ray-benchmark ray-launch ray-metrics ray-report ray-vps ray-cover-editorial ray-consult ray-multimodel ray-trend-search ray-broll; do npx -y skills remove "$s" -g; done && npx -y skills add imraywang/rayskills -g --all
旧成员去向对照：
| 旧成员 | 去处 |
|---|---|
ray-diagnose / ray-proposal |
v2 合并为 ray-consult（诊断段 → 方案段），v4 移出到 ray-skills |
ray-vpsinit / ray-nodecheck |
v2 合并为 ray-vps，v3 移出到 ray-skills |
ray-thread |
v2 曾并入 /ray-writer，现已移除；方法论保留在 git 历史，需要时直接向 Agent 描述任务即可 |
ray-cover-editorial |
2026-10-13 并入 /ray-cover：固定版画风格停用，封面改为 Punk 风格库 + Ray 的黑白灰 + 墨绿 IP |
ray-tweet · ray-idea · ray-cleanup · ray-weekly |
v2 已删除，需要时直接向 Agent 描述任务即可 |
ray-benchmark · ray-launch · ray-metrics · ray-report · ray-vps |
v3 按使用频率移出到 ray-skills，完整保留、按需独立使用 |
ray-consult · ray-multimodel · ray-trend-search · ray-broll |
v4（2026-10-13）按使用频率移出到 ray-skills，完整保留；需要时单独安装 |
WorkBuddy
运行 bash tools/build.sh 后，dist/workbuddy/ 会生成每个 Skill 的独立 ZIP。进入 WorkBuddy 的技能页，选择“添加技能 → 上传技能”，直接导入所需 ZIP；包内的 SKILL.md、参考资料、脚本和模板会一起保留。
ray-writer 已在 WorkBuddy 5.2.3 完成真实导入、自动选择和调用验证；ray-obsidian 也已完成真实安装识别和独立旧库迁移验证。ray-wechat 的本地检查和草稿脚本只依赖 Python 标准库，外部排版器按宿主实际安装状态调用；没有公众号凭证或网络权限时停在本地预览，不冒充已经写入草稿。ray-x-article 会选择当前宿主可用的浏览器或电脑控制能力，没有这类能力时会停在本地交付包。
豆包
豆包当前没有本地 SKILL.md 技能包导入入口，因此不能直接安装 rayskills。纯文字型成员可以人工转成智能体提示词，但脚本、浏览器操作、数据连接和多模型调度不会随提示词迁移；仓库仍以标准 Skill 包为唯一真源，不维护一套容易漂移的豆包副本。
🏛 架构与纪律
| 原则 | 做法 |
|---|---|
| 单一真源 | monorepo 是 Skill 唯一真源，不维护分叉副本 |
| 渐进披露 | SKILL.md 只保留工作流骨架，详细规则进入 references/，重复操作进入 scripts/ |
| 明确自由度 | 判断型任务保留空间；上传、清理、部署等脆弱流程使用严格顺序和验收门控 |
| 可恢复 | 中断后优先读取本地状态和已有 URL，续写原任务，不制造重复项 |
| 可验证 | 每个 Skill 都有场景测试；脚本必须实际运行；高风险结果必须保留可核对证据 |
| 不越权 | 不自动发布；编补的经历和数据必须列进「待确认」由作者决定；删除与生产改动遵守确认边界 |
| 构建门控 | tools/build.sh 校验目录名与 Skill 名称，beta Skill 不进入产物 |
ray-cover 内置的 Punk 风格库按 MIT 协议保留原版权与许可（见 skills/ray-cover/assets/punk/NOTICE.md）；其余 rayskills 内容遵循仓库根目录的 CC BY-NC 4.0。
📚 文档
- 新手入门 — 第一次怎么用与完整目录
- Skill 关系图 — 成员之间的常见衔接
- 长文生产管线 — Writer → Cover → WeChat / X Article 的交接与恢复
- 公众号排版契约 — 移动端层级、署名策略与外部排版器边界
- 本地知识库结构 — 资料、知识、创作、发布与回流的目录职责
- 对照实测报告 — 15 项带 / 不带 Skill 逐条记分卡