宝玉 Skills 实战教程：从安装到搭建 AI 内容工作流

写完一篇技术文章，真正耗时的部分往往还没结束：整理标题、调 Markdown 格式、做封面、画解释图、压缩图片，再分别准备博客、公众号和分享材料。

宝玉的 baoyu-skills 把这些重复工作整理成了 Agent 能读取并执行的技能。你给它文章和约束，它根据技能里的流程、参考资料与脚本完成任务。最值得学会的，不是记住二十多个名字，而是把适合自己的几个技能串起来。

这篇教程面向已经能使用 Codex 或 Claude Code、但还没有形成 Skills 工作习惯的读者。完成前半部分，你就能安装一个技能并验证输出；继续往下，可以把同一篇文章加工成博客稿、封面、知识卡片和分享幻灯片。

版本说明：核对日期为 2026 年 10 月 15 日。本文基于仓库提交 1567581c26，插件市场清单版本为 2.5.2。实际执行了技能发现命令并核对脚本与配置；图片生成及社交发布案例是操作示例，不代表已经替读者调用付费接口或发布内容。

一、先理解三个角色：Agent、Skill、工具

假设你对 AI 说：“把这篇文章做成一套小红书知识卡片。”

只有一句提示词时，AI 需要临时决定怎么分段、选什么风格、每张卡写多少字、把文件放在哪里。Skill 则把这些约定提前写好了，例如先分析内容、给出大纲、固定视觉风格、保存提示词，再生成图片。

一个技能通常不只是单独的提示词文件：

1
2
3
4

baoyu-format-markdown/
├── SKILL.md       # 什么时候使用，以及执行步骤
├── references/    # 按需读取的规则、示例与配置说明
└── scripts/       # 需要实际运行的辅助程序

因此，安装时要保留整个技能目录。只复制 SKILL.md，可能会在执行到脚本或参考文件时失败。

还有一个常见误解：安装 Skills 并不等于给模型增加了新接口权限。没有浏览器访问能力，它就不能自动操作网页；没有可用图片后端，配图流程也不会凭空生成图片。

Codex 对 Skills 采用渐进式加载：先读取名称和描述等元信息，使用时再加载详细说明。因此，“装得越多，每次都把所有 SKILL.md 全文塞进上下文”并不准确；但技能过多仍会增加发现和选择负担。入门阶段按需安装更容易定位问题。参见 Codex 官方 Skills 文档。

二、先挑技能，不急着全装

下面按任务分组，重点看“最后拿到什么”。每个技能都有一篇独立教程，点击技能名即可阅读完整的前置条件、操作案例、配置和验收方法。

阅读导航：这篇总教程负责安装与组合工作流，下面的 21 篇负责单项技能实战。在 Obsidian 中，表格使用相对 Markdown 链接打开本地笔记；发布到 Hexo 时，发布器会把链接转换为目标文章的固定地址。两端共用一份原稿，不需要手工维护两套正文。

上述范围是核对版本中的 21 个 baoyu-* 技能，不包含用于维护技能仓库本身的 release-skills。完整目录见 仓库技能目录。

我的起步建议：第一天只安装 baoyu-format-markdown。等它能正确读取文件、生成结果，再加封面或网页采集技能。一次只增加一个依赖，排错会轻松很多。

三、安装：分清终端命令和聊天指令

本文中的代码块分为两类：

• 标为 bash 或 powershell 的命令，在电脑终端执行。
• 标为 text 的技能请求，发送给 Codex 或 Claude Code。

尤其不要把 /plugin 或 /baoyu-format-markdown 当成操作系统命令粘贴到 PowerShell。

3.1 检查基础环境

仓库 README 要求已安装 Node.js，并能运行 npx bun。先执行：

1
2
3

node --version
npm --version
npx --yes bun --version

三个命令都输出版本号后，再往下走。初次运行 npx 可能需要下载依赖；连接失败和“技能写错了”是两类问题。

baoyu-url-to-markdown 的具体技能说明要求 Bun 可执行文件。准备使用它时，再检查：

1

bun --version

若没有安装，可以按 Bun 官方安装文档 配置。其他技能究竟使用 bun 还是 npx -y bun，应以各自 SKILL.md 为准，不要假设整套技能的依赖完全一致。

3.2 通用方式：使用 skills CLI 按需安装

先进入准备写文章的项目目录，再列出可发现的技能：

1

npx skills add jimliu/baoyu-skills --list

这一步只列目录，不安装技能。本次核对时，CLI 发现了 22 项，其中 21 项是 baoyu-* 内容及工具技能，另外还发现了仓库开发使用的 release-skills。列表比 README 中的“20+”多一项，不代表安装失败。

只为当前项目的 Codex 安装排版技能：

1

npx skills add jimliu/baoyu-skills --skill baoyu-format-markdown --agent codex

希望多个项目都能使用，加上全局参数：

1

npx skills add jimliu/baoyu-skills --skill baoyu-format-markdown --agent codex --global

若要给 Claude Code 安装，同一位置的 Agent 名称使用 claude-code：

1

npx skills add jimliu/baoyu-skills --skill baoyu-format-markdown --agent claude-code

以后按需安装多个技能，可以在同一个 —skill 后列出多个名称：

1

npx skills add jimliu/baoyu-skills --skill baoyu-cover-image baoyu-article-illustrator baoyu-compress-image --agent codex

检查安装结果：

1
2

npx skills list --agent codex
npx skills list --global --agent codex

第一条看项目级，第二条看全局。安装在哪个范围，就到哪个范围检查。 不加 —global 时，默认是项目级安装。

以上参数对照了 skills CLI 说明，并在本次写作环境的 1.7.2 版本帮助输出中核实。将来行为变化时，以 npx skills —help 为准。

3.3 Claude Code 用户：也可以通过插件市场安装

在 Claude Code 会话中执行：

1
2

/plugin marketplace add JimLiu/baoyu-skills
/plugin install baoyu-skills@baoyu-skills

这是 Claude Code 的插件命令，不是所有 Agent 共用的指令。当前仓库的市场清单只提供一个 baoyu-skills 插件，里面注册多个技能，不要照旧教程寻找已经变化的插件分组。

按需安装更适合精简项目；统一插件更适合希望集中管理整套技能的用户。选一条路径即可，避免同一技能在多个入口重复注册。依据：当前插件市场清单。

3.4 Codex 用户：项目目录应该长什么样

官方文档列出的项目级目录是 .agents/skills；用户级目录是 ~/.agents/skills。一个最小项目可以是：

1
2
3
4
5
6
7
8

writing-lab/
├── .agents/
│   └── skills/
│       └── baoyu-format-markdown/
│           ├── SKILL.md
│           ├── references/
│           └── scripts/
└── article.md

Windows PowerShell 下，可以这样检查项目级入口：

1

Test-Path ".\.agents\skills\baoyu-format-markdown\SKILL.md"

应返回 True。不同安装方式可能使用软链接或复制文件，关键是 Agent 能看到完整目录。

文件存在但会话仍然找不到技能时，先检查是否打开了正确项目，再新建会话或重启客户端重试。Codex 还支持通过 $技能名显式选择技能；自然语言中直接点名也便于排查。依据：Codex Skills 的发现与调用机制。

四、第一个练习：用一篇短文验证安装

先在项目中创建 article.md，放入下面这段练习素材。它只是排版练习，不需要联网或图片 API。

1
2
3
4
5
6
7
8
9
10
11
12

# 我的第一篇 AI 工作流笔记

我准备把写文章分成三个阶段：收集资料、整理正文、检查发布结果。

收集资料时保存原始链接，整理正文时统一标题和列表，发布前检查代码块与图片。

几个约定：
- 原始素材放到 sources 目录
- 文章正文放到 article.md
- 图片放到 images 目录

命令示例：node --version

向 Agent 发送：

1
2
3
4
5
6

请使用 baoyu-format-markdown 处理当前目录的 article.md。

保留原文事实和所有命令，只优化排版与明显错字。
保留现有标题，自动选择合适的摘要。
输出 article-formatted.md，保留 article.md。
完成后告诉我生成了哪些文件。

Claude Code 用户也可以按仓库示例使用：

1

/baoyu-format-markdown article.md

第一次调用可能出现格式优化选项；明确要求“优化排版，保留源文件”即可。技能的流程包括内容分析、结构处理和机械排版脚本，不只是运行一个 formatter。

怎么判断它真的成功了

不要只看聊天里那句“已完成”，检查文件：

1. article.md 仍然存在，原始素材没有被覆盖。
2. article-formatted.md 真实存在，标题、列表和命令仍然完整。
3. frontmatter、正文层级、代码格式能正常显示。
4. 如果执行了完整分析流程，可能还有 article-analysis.md。

一个重要区别：技能工作流会安排输出文件；直接运行其 scripts/main.ts 是机械排版入口，会处理传入的文件。不要把脚本直接作用于唯一原稿，然后期待它自动完成备份、标题选择和内容分析。

想补充事实、重写论证或增加案例，应另提写作要求。该技能本身要求保留内容，不能因为排版精致就把未经核实的新内容混进去。依据：baoyu-format-markdown 的实际流程。

五、把第一篇文章扩展成内容工作流

接下来用一篇“Git 常见操作”文章做例子。假设你已经有 article.md，所有示例都围绕这份原稿进行。

5.1 收集资料：保留来源，再整理内容

安装 baoyu-url-to-markdown 后，可以这样请求：

1
2
3

请使用 baoyu-url-to-markdown，把 https://git-scm.com/docs/git-status
保存为本地 Markdown 素材，保留原始来源地址。
不下载页面媒体，输出到 sources 目录。

这个技能底层使用基于 Chrome CDP 的 baoyu-fetch，并针对部分站点提供适配器。首次运行会配置媒体处理和默认输出目录。登录或验证码页面可能需要用户完成交互，技能并不保证所有网站都能自动读取。

素材文件应保留原文链接、采集日期和引用边界。把网页保存下来不等于完成事实核查，更不等于可以全文转载。写原创教程时，提炼与本次主题相关的知识，再用自己的案例验证。

依据：URL 转 Markdown 技能说明。

5.2 整理稿件：把内容写作和排版分成两个步骤

先让 Agent 根据你提供的素材与验证记录完成文章，再调用 baoyu-format-markdown。这样可以分别检查“内容有没有问题”和“排版是否清楚”。

一条比“帮我优化一下”更可靠的请求是：

1
2
3
4

请使用 baoyu-format-markdown 整理 article.md。
保留所有 Git 命令，不改写参数，不新增未经验证的结论。
统一二级、三级标题，把操作顺序改为有序列表。
保留原稿，输出 article-formatted.md。

命令类教程尤其要保护代码块。排版后的文章更好看，但读者复制命令能不能执行，仍需单独检查。

5.3 封面和插图：先决定图片要解释什么

封面负责表达主题，正文插图负责帮助理解。先确定用途，才值得花时间生成。

1
2
3

请使用 baoyu-cover-image 为 article-formatted.md 生成一张 16:9 封面。
主题是 Git 常见操作，采用 blueprint 风格，不在图片里放长段文字。
先读取已有偏好和可用图片后端，再按技能流程执行。

正文配图可以这样写：

1
2
3

请使用 baoyu-article-illustrator 分析 article-formatted.md。
只选择最多 3 个值得配图的位置，优先解释工作区、暂存区与提交之间的关系。
先给出位置和每张图要说明的内容，整组保持相同视觉风格。

baoyu-cover-image 使用类型、配色、渲染、文字与氛围等维度；baoyu-article-illustrator 会保存插图计划和提示词，再调用可用图片后端。两者本身并不是免费图片服务。是否需要 API Key、使用哪个模型，取决于当前 Agent 能用的后端。

下图为本文新制作的工作流示意图，先明确每个技能处理的输入、输出和验收位置，再决定是否需要额外配图。它不是官方界面截图，也不是已经执行的任务记录。

技能依据：封面、正文配图。

5.4 技术图、知识卡片、幻灯片怎么选

如果要解释精确的连接关系，用 baoyu-diagram 生成 SVG；需要面向社交平台的视觉化知识总结，考虑 baoyu-xhs-images 或 baoyu-infographic。

Claude Code 调用示例：

1
2
3

/baoyu-diagram "Git 工作区、暂存区和提交历史的关系" --type structural --lang zh
/baoyu-xhs-images article-formatted.md --style notion --layout list
/baoyu-slide-deck article-formatted.md --style chalkboard --slides 8 --outline-only

在 Codex 中，用自然语言点名技能，并保留相同输入、风格和输出要求即可。

不同视觉产物服务于不同阅读方式。下图为本文独立绘制的选型说明：精确关系适合技术图，连续阅读适合知识卡片，逐页讲述适合幻灯片；它不模仿具体平台界面。

幻灯片先用 —outline-only 检查结构，确认每页要讲什么，再生成图片。该技能的 PPTX 合成代码把页面图片放进幻灯片，不能把输出的 PPTX 理解为所有文字、图表都可独立编辑的原生演示文稿。需要后续逐字编辑时，应提前改用适合生成原生幻灯片元素的工具。

来源：卡片技能、幻灯片技能、PPTX 合成实现。

5.5 图片压缩：明确要求保留原图

1
2
3

请使用 baoyu-compress-image 压缩 images 目录。
输出 WebP，质量 80，递归处理，并保留原图。
报告压缩前后体积，检查最终图片能否打开。

对需要手工调用脚本的情况，下面是 Codex 项目级安装后的 PowerShell 示例：

1
2

$skillDir = Join-Path (Get-Location) ".agents\skills\baoyu-compress-image"
npx -y bun "$skillDir/scripts/main.ts" ".\images" --recursive --quality 80 --keep

这里的 —keep 很重要：当前技能默认 keep 为 false。脚本也会选择可用压缩器，缺少依赖时应按实际错误补齐。不要只看压缩比例，还要检查代码截图的小字、细线和透明背景是否受损。依据：图片压缩参数。

六、配置一次：EXTEND.md 和 .env 各管什么

这两种文件容易混淆。记住：EXTEND.md 保存工作偏好，.env 保存接口环境变量和凭证。

6.1 最简单的 EXTEND.md

如果每次排版都希望自动选标题和摘要，可以在项目中建立：

1

.baoyu-skills/baoyu-format-markdown/EXTEND.md

内容：

1
2
3

---
auto_select: true
---

这只是排版技能的配置字段。其他技能有自己的 schema，不能把 auto_select 复制到所有技能，就期待它们都跳过确认。

本文核对的多个 SKILL.md 约定先查项目目录，再查 XDG 配置目录，最后查用户主目录：

1. 项目/.baoyu-skills/技能名/EXTEND.md
2. XDG_CONFIG_HOME/baoyu-skills/技能名/EXTEND.md（未设置 XDG_CONFIG_HOME 时使用 ~/.config）
3. ~/.baoyu-skills/技能名/EXTEND.md

跨平台入门时优先使用项目级路径，容易看见，也更方便排错。

还要注意：这是技能工作流的查找约定，直接调用某个脚本时，脚本实现未必支持完全相同的搜索路径。例如本文版本的 image-gen 主脚本与 SKILL.md 在 XDG 路径处理上就有差异。直接跑脚本遇到配置不生效，先检查它真正读取的路径。

来源：排版技能配置、image-gen 主脚本。

6.2 图片生成先选后端，再配密钥

建议先向 Agent 发这条请求：

1
2
3
4

请检查 baoyu-image-gen 当前支持的后端和我的可用环境。
列出可选提供商、需要的凭证和配置文件位置。
完成默认提供商、模型、比例的初始化后，再生成一张测试图。
不要输出任何密钥值。

这样做比照抄一年前的模型名称可靠。图片服务的型号、权限和计费会变化，不要把仓库里的默认模型当成你账户必然可用的模型。

如果选择 OpenAI API 路径，项目级 .env 的最小形态是：

1

OPENAI_API_KEY=replace-with-your-own-api-key

这是占位示例。真正的密钥保留在本机，项目的 .gitignore 加上：

1

.baoyu-skills/.env

baoyu-image-gen 的模型选择可受命令行 —model、EXTEND.md 的 default_model、环境变量及内置默认值影响。配置了多个位置时，先检查优先级，避免出现“改了环境变量却没有换模型”的误判。

该仓库还提供 codex-cli 路径，但 Codex/ChatGPT 登录态不是 OPENAI_API_KEY。需要 API Key 的路径和依赖 Codex 登录的路径应分别配置，不能互相替代凭证。当前运行环境若提供原生图片工具，也应先按技能的后端选择规则判断是否可用。

来源：image-gen 使用说明、偏好 schema、仓库对 OAuth 与 API Key 的说明。

七、最后一公里：博客、公众号和“已发布”不是同一件事

7.1 发布到 Hexo：继续使用 Markdown 源稿

Hexo 本身会渲染 Markdown。因此，将 article-formatted.md 配上 Hexo frontmatter 后放到 source/_posts 即可，没有必要先转成公众号 HTML 再喂给 Hexo。

一个示例：

1
2
3
4
5
6
7
8
9
10

---
title: 我的 Git 工作流
date: 2026-10-15 19:30:00
tags:
  - Git
  - AI
categories:
  - 技术笔记
description: 用具体案例理解工作区、暂存区和提交历史。
---

正文里的图片可以使用站点公开路径：

1

![Git 工作区关系图](/img/posts/git-workflow/worktree.webp)

对应文件应放到 Hexo 项目的：

1

source/img/posts/git-workflow/worktree.webp

注意，cover 不是所有 Hexo 主题都通用的字段；是否显示封面要看当前主题。图片进入 source 目录后，也需要随站点一起生成和部署。

在已经安装依赖的 Hexo 项目根目录执行：

1
2

npx hexo generate
npx hexo server

本地检查完成后，按已有部署配置执行：

1

npx hexo deploy

其中 generate 负责生成静态文件，server 用于预览，deploy 使用你已配置的部署器。仓库没配置部署目标时，运行 deploy 不会自动替你开通托管平台。

如果你通过 Obsidian 写作，publish、package、note_type 等字段可能是自己的同步脚本约定，不是 Hexo 默认发布开关。这篇文章使用的就是“Obsidian 原稿 → 本地导出脚本 → Hexo 源文件 → 静态站点”的方式；换到其他博客时，应替换为该项目自己的发布流程。

依据：Hexo 写作、生成、部署。

7.2 公众号：优先把 Markdown 直接交给发布技能

baoyu-post-to-wechat 已内置 Markdown 到公众号内容的处理。当前说明明确要求不要提前把 Markdown 转成 HTML 再套同一发布链路，因为浏览器路径和 API 路径处理图片的方式不同。

1
2
3
4

请使用 baoyu-post-to-wechat 处理 article-formatted.md。
使用当前已配置的公众号账户，检查标题、摘要、作者和封面。
本次只创建公众号草稿，不群发。
完成后返回草稿标识和检查结果。

API 路径涉及公众号凭证、IP 白名单和 draft/add 等接口；浏览器路径则依赖 Chrome 与有效登录状态。草稿创建成功不等于已经向读者群发。 验收时要明确结果属于哪一个阶段。

只有你需要单独交付带样式 HTML 文件时，再使用 baoyu-markdown-to-html。它和公众号发布技能是不同用途，不必强行串联。

依据：公众号发布技能。

八、排错：按“发现、执行、输出”三层检查

Windows 还要留意命令所在环境。PowerShell 中的环境变量写法是 $env:NAME = “value”，不能直接套用 Bash 的 NAME=value command；目录含空格时要加引号。教程里出现占位路径时，应替换成实际路径，不能原样执行。

名称中带 danger 的工具，仓库说明涉及非官方或逆向网页接口，使用前应阅读其说明并考虑账户、稳定性和平台限制。它们适合有明确需求时评估，不适合作为入门教程默认依赖。依据：项目免责声明。

九、更新维护：保持可复现，比追新更重要

用 skills CLI 安装的技能，可以查看和更新：

1
2

npx skills list --agent codex
npx skills update --project

如果装在全局：

1
2

npx skills list --global --agent codex
npx skills update --global

用 Claude Code 插件市场安装的，就通过 /plugin 的 Marketplaces 界面更新该市场。不要把“更新 Git 克隆”“更新插件市场”和“更新 skills CLI 的安装副本”当成同一个动作。

对长期写作项目，我建议保留三种记录：

1. 技能来源与版本或提交号。
2. 项目级 EXTEND.md 中的非敏感偏好。
3. 原稿、最终提示词和最终输出文件。

更新后先跑本文的短文排版练习，确认读写与输出路径正常，再处理正式文章。每次只增加少量技能，也方便判断是安装、配置还是内容本身出了问题。

维护命令依据：skills CLI；插件更新路径依据：仓库安装与更新说明。

十、可直接复用的文章加工请求

当你已经完成安装、偏好和图片后端初始化后，可以用下面的请求处理正式文章：

1
2
3
4
5
6
7
8
9
10
11
12

请处理当前项目的 article.md，目标是发布一篇技术博客教程。

1. 核对提供的来源与示例命令，记录不能确认的地方。
2. 使用 baoyu-format-markdown 整理结构，保留代码与原始事实。
3. 使用 baoyu-cover-image 生成 16:9 封面。
4. 使用 baoyu-article-illustrator 选择最多 3 个必要的配图位置。
5. 使用 baoyu-compress-image 输出 WebP，并保留所有原图。
6. 将最终 Markdown 和图片放到当前博客约定的位置。
7. 运行博客已有构建命令，检查代码块、图片、目录和移动端排版。

最终交付源稿路径、图片清单、构建结果。
本次仅生成和检查，不执行公开发布。

最后一句是模板的操作边界：你确认需要上线时，再明确要求发布，并让 Agent 返回真实文章地址及访问验证结果。

学会这套流程后，真正值得积累的是自己的素材与质量标准。技能把重复步骤固定下来，你就可以把更多精力放在文章是否讲清楚了问题、案例能不能复现，以及读者做完后是否获得了一个真实可用的结果。

参考资料与图片署名

• baoyu-skills 仓库，作者 Jim Liu（宝玉）。
• 本文核对的中文 README 快照。
• Skills 安装器。
• Codex 官方 Skills 文档。
• Hexo 官方文档。
• 本文封面、工作流图和视觉选型图为本次独立绘制的 SVG，转换为 WebP 用于网页展示，同时保留 SVG 与 PNG 原件；不是技能官方截图，不复用本站其他文章的封面。