tjxj/z-skills: a local Agent Skills library for Chinese content workflows

What tjxj/z-skills is, and who ends up using it

The repository is a collection of folders, not a package. Each folder is one skill: a SKILL.md that declares a name, a description and trigger phrases, plus optional scripts, assets, references, tests and evals. The README lists eighteen of them, covering web clipping, video download, video study pages, document parsing, mail reading, spreadsheet editing, Markdown to Word, Markdown to PDF, Markdown tables to Excel, docx format transfer, handwritten slide decks, handwritten animation video, grounded source QA, expense policy QA, a first-person voice simulation, interactive science visualisation and four-panel panda comics.

The intended reader is someone who runs an agent that supports Skills, places the folders under .agent/skills/, and wants recurring workflows to behave the same way each time instead of being re-explained in every conversation. The README states the skills are aimed at Chinese-language creation, knowledge management and automation tasks. That is a real constraint, not a detail: the trigger phrases, the output conventions and the reference material are written in Chinese, so the matching between what you type and which skill fires depends on Chinese phrasing.

There is no homepage, no release and no stated licence in what the repository exposes. That shapes who should use it. It suits an individual or a small team willing to read each SKILL.md and treat the scripts as source they own. It does not suit anyone who needs a supported dependency with a version number and a licence file.

How the skill folders actually execute

The mechanism is filesystem discovery plus script execution. You copy a skill directory into your agent's skills folder. At the start of a new session, the agent reads the name and description from each SKILL.md and matches them against your request. Once a skill is selected, the workflow inside that SKILL.md runs, and where the skill ships scripts, the scripts do the work.

The README is explicit about that last part: prefer scripts over manual repetition. So the real logic lives in Python files under each skill's scripts/ directory, and SKILL.md is the contract around them. z-web-pack writes a fixed set of Markdown artifacts into an output root: README.md, 00-research-brief.md, 01-link-inventory.md, 02-image-inventory.md, 03-reading-map.md and 04-media-inventory.md. Those filenames are the interface. Downstream skills read them.

The clearest example of a deliberate boundary is between z-web-pack and z-video-downloader. When z-web-pack finds a video, it only records it in 04-media-inventory.md. It does not download it. To get the file, you pass the Source URL from that inventory to z-video-downloader. The README gives the reason: keeping discovery and download separate keeps each skill smaller and avoids pulling large files while you are collecting reading material. That is a sensible split, and it means a two-step habit: collect, then decide what is worth downloading.

Installing a skill and running a first collection

Installation is a copy. There is no package manager step for the skills themselves. Pick one skill and copy its directory into the skills folder your agent reads:

cp -R z-xkcd-panda-comic "/path/to/your/.agent/skills/"

To install everything at once, the README gives a glob copy:

cp -R z-* "/path/to/your/.agent/skills/"

After that, the README states that a new session will match trigger phrases against each SKILL.md automatically. There is no registration command and no daemon.

For a first real run, use z-web-pack to turn one article into a local material pack:

/Users/zz/miniconda3/bin/python3 z-web-pack/scripts/collect_web_pack.py \
  --out-root "/Users/zz/Library/Mobile Documents/iCloud~md~obsidian/Documents/zhangAI/Clippings/Reading" \
  --title "主题名" \
  --max-depth 0 \
  --max-pages 1 \
  "https://example.com/article"

The paths and the interpreter path are the README's own example, so substitute your own. What you should see afterwards, in the output root, is the six-file set described above. Check 04-media-inventory.md for video links; if you want one of those files locally, hand the Source URL to the downloader:

/Users/zz/miniconda3/bin/python3 z-video-downloader/scripts/download_video.py \
  --title "主题名" \
  "https://www.bilibili.com/video/BV..."

One skill installs outside the copy model. z-grounded-source-qa is published through the skills CLI:

npx skills add tjxj/z-skills --skill z-grounded-source-qa

The README notes that dependency installation is not described anywhere. If a script fails on an import, that is the gap you are standing in.

The docx format brush shows the project at its most opinionated

z-docx-format-brush is the skill where the design is most visible, and it is worth reading as a signal for the rest. The problem it targets is real: documents produced by pandoc or by a model tend to come out with mixed fonts, coloured headings, borderless tables and reversed quotation marks. The skill's approach is to measure formatting from a template rather than describe it. It extracts a fingerprint, applies it, then verifies.

The workflow has three stages, and the README frames the last one as the completion condition:

# 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. 验证收敛度，退出码 0 才算完成
python3 z-docx-format-brush/scripts/verify_format.py 目标.docx

The five layers named in the comment are styles, paragraphs, cover, tables and text. The idea that formatting parameters are extracted from the template and applied through a single exit point is stated in the README as the core of the skill. The verify step returning exit code 0 as the only acceptable result is a stronger completion contract than most of the other skills offer, and it is the reason this one is easier to trust in a pipeline. The README points to z-docx-format-brush/README.md for the methodology and the recorded pitfalls, which suggests the interesting failure cases are documented there rather than in the top-level file.

Where the collection is thin, and when it is the wrong tool

The licence is not stated. That is the first thing to resolve, because it determines whether you can ship a generated document, bundle a script into a product, or contribute a fix back. Nothing in the README answers it.

Dependencies are undocumented at the collection level. Each script clearly needs something (the video downloader wraps platform downloads, z-smart-xparse wraps xparse-cli, the video study skill calls Qwen multimodal analysis), but the top-level README does not list Python packages, external binaries, API keys or environment variables. The README does note that WeChat Channels share links are resolved through an online parsing service with nothing extra to install, which tells you some skills depend on remote services you do not control. If a service changes or rate-limits you, the skill stops working and there is no fallback described.

The skills are also not portable across agents in the way a library would be. They assume a host that reads SKILL.md, matches Chinese trigger phrases and lets scripts run against local files. An agent without Skills support gets nothing from this repository. And the scope is narrow on purpose: Chinese creative and document workflows. If your content is English, the trigger matching and the output conventions will fight you.

Finally, verification is uneven. z-docx-format-brush defines an exit code. The README's general advice is to actually open or run what you generated, which is honest but leaves the checking to you. For a batch of PDFs or a folder of Word files, that is manual work the project does not remove.

What it replaces, and what it does not

The nearest alternative for the document side is Pandoc. Pandoc converts Markdown to docx and PDF from a single command and is a general-purpose converter with a documented CLI and a long release history. The difference in approach matters. Pandoc maps your Markdown onto a reference docx you supply, and it does not measure the template and then verify that the output converged. z-docx-format-brush extracts a fingerprint from a template, applies it across five layers, and gates completion on verify_format.py exiting 0. If your problem is that pandoc output looks wrong in ways you keep fixing by hand, the fingerprint approach addresses that directly. If your problem is simply converting a file, Pandoc is the smaller tool and you already know how to call it.

For web collection, the alternative is a reader-mode extension or a clipping service that saves an article to your notes app. Those give you one file. z-web-pack gives you a directory of inventories, a reading map and a media list, and it deliberately refuses to download media. That is more structure than most people want for a single article and less convenient than a browser button. It pays off when you are assembling material for a longer piece and need to know what links and images you have.

For video, the underlying downloader in most setups is yt-dlp. The README does not present z-video-downloader as a replacement for it; it describes a wrapper that adds resume via .part files, batch inventories, subtitles, covers and a download history, and that stops before creating an empty directory when the input is invalid. The value is the wrapper's conventions, not a new download engine.

Editorial conclusion

Adopt tjxj/z-skills if you already run Codex, Claude Code or another Skills-aware agent and your work is Chinese writing, knowledge management or document conversion, because the skills are folders you copy and each one carries its own SKILL.md. Do not adopt it if you need a packaged, versioned dependency with a stated licence, or if your agent does not read SKILL.md files. Verify three things before committing: the licence, since the repository does not state one; the Python dependencies and external services each script needs, since the README does not list them; and whether z-docx-format-brush/scripts/verify_format.py exits 0 on a sample of your own docx files, because that exit code is the only completion signal the project defines.

Frequently asked questions

Official sources

1. Issues
2. README
3. tjxj/z-skills on GitHub