z-skills

z-skills 是一组可复用的本地 Agent Skills，用来把常见工作流沉淀成稳定能力：网页素材采集、视频下载、视频学习网页、全景音频生成、文档解析、邮件读取、表格处理、Markdown 转 Word/PDF、诗词与技术文章成书、互动科普网页、证据型资料问答、docx 模板格式刷、手写幻灯片、手写 HTML 动画、会动的解析图，以及文章四格漫画配图

这些 Skill 面向中文创作、知识管理和自动化任务，可按需安装到支持 Agent Skills 的环境中。当前共 19 个 Skill，另有 z-life-hub 家庭生活管理后台技能组（日记、读书笔记、健康档案、凭证、电脑管理），具体能力、依赖与执行流程以各目录的 SKILL.md 为准。

快速安装 · Skills 一览 · 「动」悉万物 · 诗词与技术文章成书 · 使用建议

快速安装

通过 npx skills 按需安装

需要 Node.js / npm。以通用证据问答和全景音频为例：

npx skills add tjxj/z-skills --skill z-grounded-source-qa
npx skills add tjxj/z-skills --skill z-qwen-audio-studio

按安装器提示选择目标 Agent。目录名与 Skill 的 name 不一定相同，例如 z-poetry-book 的 Skill 名为 poetry-book，其专用安装方式见下文。

克隆后手动安装

git clone https://github.com/tjxj/z-skills.git
cd z-skills

# 示例目标目录；请替换为你的 Agent 实际读取的 skills 目录
mkdir -p "/path/to/your/.agent/skills"

# 安装一个 Skill，保留整个目录及其资源
cp -R z-xkcd-panda-comic "/path/to/your/.agent/skills/"

# 或安装全部 Skill
cp -R z-* "/path/to/your/.agent/skills/"

安装后按宿主要求刷新 Skills 或开启新会话，再用自然语言描述任务，也可明确点名 Skill。复制目录只安装工作流与资源，Python 包、系统工具和模型 API 仍需按各 Skill 的说明配置。

下文脚本命令均从克隆后的仓库根目录运行；若已安装到其他目录，请相应调整脚本路径。python3 应指向已安装所需依赖的环境。

Skills 一览

「动」悉万物：会动的解析图

z-dongxi 把有过程、有数字的内容演出来：RAG 的数据怎么流、HTTPS 怎么握手、钱花在哪、流量去了哪、两周排期卡在哪、几个模型谁强谁弱。给主题和内容，Agent 自动选图型和风格、写 spec、渲染、lint、截帧自检。

npx skills add tjxj/z-skills --skill z-dongxi
python3 z-dongxi/scripts/render.py --spec z-dongxi/demos/specs/rag.json --style sketch --out rag.svg --png rag.png

z-web-pack 与 z-video-downloader 边界

z-web-pack 负责网页素材包采集，包含正文、正文相关链接、图片、本地阅读地图、媒体链接清单，以及受限来源恢复说明

z-video-downloader 负责视频下载，包含 YouTube、Bilibili、Vimeo、X/Twitter、TikTok、抖音、Instagram、Facebook、微信视频号、m3u8 和常见视频直链，并支持断点续传、批量清单、字幕、封面和下载历史。视频号分享链接（weixin.qq.com/sph/）通过在线解析服务自动获取视频地址，无需额外安装

z-web-pack 发现视频时只写入 04-media-inventory.md。如果要把视频保存到本地，把清单中的 Source URL 交给 z-video-downloader

采集网页素材

先在所用 Python 环境安装 requests、beautifulsoup4、readability-lxml 等依赖，完整流程见 z-web-pack。

python3 z-web-pack/scripts/collect_web_pack.py \
  --out-root "./Clippings/Reading" \
  --title "主题名" \
  --max-depth 0 \
  --max-pages 1 \
  "https://example.com/article"

输出里重点看：

• README.md
• 00-research-brief.md
• 01-link-inventory.md
• 02-image-inventory.md
• 03-reading-map.md
• 04-media-inventory.md

下载视频

需要 Python 的 requests，平台视频另需 yt-dlp，音视频合并需 ffmpeg。平台可用性受登录态、风控和解析服务状态影响，详细策略见 z-video-downloader。

python3 z-video-downloader/scripts/download_video.py \
  --out-root "./Video/Downloads" \
  --title "主题名" \
  "https://www.bilibili.com/video/BV..."

如果视频链接来自网页素材包，使用 04-media-inventory.md 里的 Source URL

也可以直接读取媒体清单：

python3 z-video-downloader/scripts/download_video.py \
  --inventory "/path/to/04-media-inventory.md"

Qwen Audio Next 全景音频 Skill

z-qwen-audio-studio 调用阿里云百炼 qwen-audio-3.1-tts-next，支持：

• 单人叙事、商业广告、双人或多人播客、广播剧
• 环境声、动作音效和背景音乐
• 最多 3 条参考音频，通过 @voice1、@voice2、@voice3 引用
• WAV、MP3、PCM 输出，最高 48kHz 双声道
• 下载后自动执行 ffprobe 和 ffmpeg 完整解码验收
• API Key、Workspace ID、参考音频 Base64 和接口域名脱敏

首次使用前需准备：

1. 在阿里云百炼华北 2（北京）地域开通 qwen-audio-3.1-tts-next
2. 创建该地域可用的 API Key
3. 获取 API Key 所在业务空间的 Workspace ID
4. 安装 Python 3.9+、requests、ffmpeg 和 ffprobe
5. 在私有终端会话设置环境变量

export DASHSCOPE_API_KEY="your-api-key"
export SFM_WORKSPACE_ID="your-workspace-id"
python3 z-qwen-audio-studio/scripts/qwen_audio_studio.py doctor

doctor 只显示依赖和环境变量是否已配置，不显示凭据内容。完整准备流程见 环境准备说明。

Markdown 转 Word Skill

z-md-to-word 用来把本地 Markdown 文章转换成 Word 文档，适合公众号文章、Obsidian 笔记、商单稿件和需要交付 .doc / .docx 的场景。

它会自动处理几个常见问题：

• 保留 Markdown 标题、作者和日期
• 写入远程图片和本地图片
• 跳过空上传占位符
• 修正常见列表识别问题
• 生成后检查文档是否能打开和渲染

默认输出：

output/doc/.docx
output/doc/.doc

诗词与技术文章成书

z-poetry-book 将诗词、古籍资料、Markdown 技术文章和课程讲义制作成有出处、可重建的 LaTeX PDF，保留来源清单、图片、构建文件、校验报告与预览图。

默认简体中文横排。诗词书稿使用带来源的结构化 JSON；技术文章可直接读取受支持的 Markdown 结构。

专用安装器默认安装到 ~/.agents/skills/poetry-book/：

# 在仓库根目录运行
python3 z-poetry-book/scripts/install.py

先按 环境要求 配置 latexmk、LuaLaTeX、Ghostscript、中文字体和 Python 依赖，再从仓库根目录构建：

# 诗词或文集：使用仓库自带示例
python3 z-poetry-book/scripts/render_book.py \
  --input "z-poetry-book/examples/book.json" \
  --theme song-mist \
  --output "./output/poetry-demo"

# 技术文章：替换为你的 Markdown 文件
python3 z-poetry-book/scripts/render_article.py \
  --input "/absolute/path/article.md" \
  --theme celadon \
  --title "文章主标题" \
  --author "作者或栏目名" \
  --output "./output/article-demo"

输出目录须为空或不存在。交付前应确认 validation-report.json 的 passed 为 true，并查看封面和代表页面。当前 Markdown 模式的范围与限制、离线重建和完整案例见 详细说明。

docx 格式刷 Skill

z-docx-format-brush 用来把一份模板 docx 的格式"刷"到另一份 docx 上，核心思想是格式参数从模板实测提取、收敛到唯一出口应用

典型场景：

• 修复 pandoc / 大模型产出的格式混乱 docx（字体混排、标题带蓝色、表格无边框、引号反向）
• 参照模板从零生成格式一致的公文类文档
• 诊断两份 docx 的格式差异

三步工作流：

# 1. 解剖模板 → 格式指纹 JSON
python3 z-docx-format-brush/scripts/extract_fingerprint.py 模板.docx --json fp.json

# 2A. 从零新建：结构化内容统一经过格式工厂
python3 z-docx-format-brush/scripts/gen_from_template.py content.json --config fp.json --out 新文档.docx

# 2B. 修复已有文档：五层格式刷（样式/段落/封面/表格/文字）
python3 z-docx-format-brush/scripts/apply_format.py 目标.docx --config fp.json

# 3. 执行基础格式检查；模板一致性还需结合格式指纹和渲染结果复核
python3 z-docx-format-brush/scripts/verify_format.py 目标.docx

详细方法论和踩坑记录见 docx 格式刷说明

熊猫四格漫画 Skill

z-xkcd-panda-comic 用来把文章或主题变成一张 2x2 四格漫画，默认风格是：

• 黑白手绘漫画
• 金馆长熊猫表情味 / 金教授熊猫脸
• 中文短对白
• xkcd 式冷幽默节奏
• 适合插入公众号、Obsidian、Markdown 文章

它会先提炼文章核心观点，再设计四格节奏：

1. 设定痛点或误会
2. 普通办法暴露荒诞
3. 熊猫角色给出解决动作
4. 用一句话收束核心观点

目录内包含一张参考风格图：

z-xkcd-panda-comic/assets/reference-codex-computer-housekeeper-panda-comic.png

z-life-hub 家庭生活管理后台

z-life-hub/ 是一组生活类 Skill，在 WorkBuddy 上实测，数据全部存进腾讯文档「生活后台」文件夹，手机上随时能看能记：personal-diary（日记）、family-ledger（记账）、reading-notes（读书笔记）、family-health-archive（健康档案）、voucher-vault（各种凭证）、mac-butler（电脑管理）

npx skills add tjxj/z-skills --skill personal-diary

使用建议

部分 Skill 保留了作者本机的路径和外部能力约定。首次使用时，应把 /Users/zz/... 等路径替换为自己的工作区、Python 环境与输出目录；被引用的外部 Skill 或服务需另行准备。本仓库没有统一的一键依赖安装脚本。

• 每个 skill 都以自己的 SKILL.md 为准
• 有脚本的 skill 优先使用脚本，避免手工重复操作
• 处理外部文件、邮件、视频和网页时，先确认路径、链接和权限
• 生成文章或图片后，尽量做一次实际查看或运行验证
• 网页素材采集和视频下载分开维护，降低单个 skill 的复杂度
• 视频平台风控、cookie、画质、播放列表等逻辑统一放在 z-video-downloader
• z-web-pack 的媒体清单只做发现和转交提示，避免采集资料时意外下载大文件
• 单篇新闻默认使用保守采集模式；遇到付费墙或验证码时保留受限说明，再补公开来源
• 视频下载支持 .part 续传；输入无效时会在创建空目录前停止

目录结构

z-skills/
  docs/
    index.html
  z-poetry-book/
    SKILL.md
    README.md
    assets/
    scripts/
    examples/
    tests/
    docs/
  z-wanghong-handwritten-ppt/
    SKILL.md
    templates/
    assets/
    examples/
    references/
    scripts/
    evals/
  z-wanghong-handwritten-video/
    SKILL.md
    scripts/
    examples/
    references/
    tests/
    evals/
  z-xkcd-panda-comic/
    SKILL.md
    assets/
    evals/
  z-docx-format-brush/
    SKILL.md
    README.md
    scripts/
  z-md-to-word/
    SKILL.md
    README.md
    scripts/
    evals/
  z-video-downloader/
    SKILL.md
    scripts/
    tests/
  z-video-study-webpage-qwen/
    SKILL.md
    scripts/
    tests/
  z-qwen-audio-studio/
    SKILL.md
    agents/
    references/
    scripts/
    tests/
    evals/
  z-grounded-source-qa/
    SKILL.md
    README.md
    scripts/
    references/
    tests/
    evals/
  z-expense-policy-qa/
    SKILL.md
    references/
    scripts/
    examples/
    tests/
    evals/
  ...

维护方式

新增 skill 时建议包含：

• SKILL.md：触发词、执行流程、输出规范
• scripts/：可复用脚本
• assets/：参考图、模板或固定素材
• evals/：示例输入和评估用例
• README.md：复杂 skill 可单独补充说明

更新 Skill 时，同步核对本页的目录入口、用途、安装示例与依赖说明；命令示例使用可替换路径，避免把个人凭据或本机配置写入公开文档。

保持触发词清楚、流程可执行、输出可验证，是这个库的核心原则。