Skip to content
Get packs

Guide · Agent skill

How to use the Document Translator agent skill (baoyu-translate)

Updated · written with AI from the project's own documentation and checked against our catalogue data

baoyu-translate is an agent skill that lets an AI agent translate text, articles and documents into a target language, by default Simplified Chinese. This guide is for readers who have never used an agent skill: it explains what the skill does, how to install it, how to ask for a translation in plain language, and what to check before you rely on the output. By the end you will be able to set up preferences, pick a translation mode and run a translation.

Document TranslatorJimLiu/baoyu-skills · MIT

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it so the baoyu-translate folder is inside ~/.claude/skills/ or a project's .claude/skills/ folder.
  2. 2Confirm bun or npx is available. The scripts need bun or npx to run TypeScript. If bun is installed the skill uses it directly; otherwise it uses npx.
  3. 3Make a translation request. Ask the agent in plain language, for example to translate an article to Chinese, and include the URL or file path.
  4. 4Answer the setup questions. On first use with no EXTEND.md, answer the target language, mode, audience, style and save location questions so preferences are saved.
  5. 5Review translation.md. Open the translation in the output folder next to the source file, and check the analysis and draft files if you used normal or refined mode.
  6. 6Refine if needed. After a normal-mode run, reply 继续润色 or refine to run review and polish on the same output.

What the skill makes the agent do

An agent skill is a folder of instructions and scripts that an AI agent loads when a task matches its description. Once baoyu-translate is installed, the agent handles translation requests using one of three modes: quick (direct translation), normal (analyze the content first, then translate) and refined (translate, review and polish).

The skill also keeps your preferences in an EXTEND.md file, can apply a built-in English-to-Chinese glossary or your own terms, and can split long markdown files into chunks so long documents are handled piece by piece.

  • Quick mode: translate directly.
  • Normal mode (default): analyze, then translate.
  • Refined mode: analyze, translate, review and polish.
  • Output goes to a folder named after the source file and target language, with the final file always called translation.md.

Install the skill from the ZIP or the Claude apps

Download the ZIP of the skill from this page and unzip it. For Claude Code, place the skill folder in ~/.claude/skills/ to make it available for all your projects, or in a project's .claude/skills/ folder to limit it to that project.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills

Check what the skill needs to run

The scripts are TypeScript files, so the skill needs either bun or npx available on your machine. The chunking script also uses the markdown-it npm package. The skill runs scripts and uses the network, so review it before installing if that matters to you.

  • bun or npx (runs the TypeScript scripts)
  • markdown-it npm package (used by scripts/chunk.ts)

Ask for a translation in plain language

You do not need a special command. The skill triggers on requests such as translate, translate to Chinese, translate to English, localize, refined translation, or quick translation, and also when you give a URL or file together with translation intent. You can name the mode in your request: say 快翻 or quick for quick mode, 精翻, refined or proofread for refined mode.

The first time you run it and no EXTEND.md preferences file exists, the skill asks you a set of setup questions (target language, mode, audience, style and where to save the file) before it translates anything. Your answers are saved to EXTEND.md.

  • "Translate this article to Chinese: [URL or file path]"
  • "快翻这篇文章" for a quick translation
  • "Do a refined translation of this document and proofread it"
  • "Translate to English, audience: business, style: conversational"

Set preferences and use glossaries

Preferences live in EXTEND.md. The skill checks three locations in order and uses the first one it finds: .baoyu-skills/baoyu-translate/EXTEND.md in the project, then ${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-translate/EXTEND.md, then $HOME/.baoyu-skills/baoyu-translate/EXTEND.md. EXTEND.md is written in YAML and can set the default target language, default mode, audience, style, chunk settings and glossary entries.

Glossary entries are merged from EXTEND.md inline entries, external glossary files, the built-in English-to-Chinese glossary, and any --glossary file passed on the command line, which overrides the others. Each entry has a from term, a to term and an optional note, for example keeping Transformer in English.

  • Defaults: target zh-CN, mode normal, audience general, style storytelling, chunk threshold 4000 words, chunk max 5000 words.
  • Style presets include formal, technical, literal, academic, business, humorous, conversational and elegant, or a custom description.
  • Audience presets: general, technical, academic, business, or a custom description.
target_language: zh-CN default_mode: normal # quick | normal | refined glossary: - from: "Transformer" to: "Transformer" note: "Keep English"

Understand the output files

Every run writes its files into an output directory, named {source-dir}/{source-basename}-{target-lang}/. The final translation is always translation.md. Normal and refined modes also keep an analysis file and the assembled prompt, and refined mode keeps the initial draft before review, so you can see how the result was produced.

  • translation.md: final translation (all modes)
  • 01-analysis.md: content analysis with domain, tone and terminology (normal, refined)
  • 02-prompt.md: assembled translation prompt (normal, refined)
  • 03-draft.md: initial draft before review (refined)

Safety notes and limits

The output is unreviewed machine translation. For certified or legal translations, a human translator must verify accuracy. Do not use the skill on very sensitive confidential documents: content may be sent to the model and, if you provide URLs that are fetched, to the internet.

In normal mode, when the translation finishes the skill offers to refine it further. Reply 继续润色 or refine to run the review and polish steps on the existing output.

  • Not suitable for certified or legal translation without human review.
  • Content may be sent to the model; URLs may be fetched from the internet.
  • Scripts run locally through bun or npx.

What people use it for

  • Translating a blog post into Simplified Chinese with the storytelling style.
  • Translating a long markdown document in chunks so each section is handled separately.
  • Keeping AI terms such as Transformer or Hallucination consistent across a series of articles using the built-in glossary.
  • Producing a proofread, publication-quality English or Chinese version of an important article with refined mode.

Frequently asked questions

How do I install the baoyu-translate skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder. In the Claude apps, go to Settings, Capabilities, then Skills and upload it there.

What do I need to run baoyu-translate?

You need bun or npx to run the TypeScript scripts, and the markdown-it npm package is used by the chunking script. The skill runs scripts and uses the network.

Is baoyu-translate free to use?

The skill is published under the MIT licence. This page does not state any price, so check the project's repository for its terms.

Can I use it for certified or legal translation?

No, not without a human check. The output is unreviewed machine translation, so a human translator must verify accuracy for certified or legal work.

Is it safe to translate confidential documents with this skill?

Be cautious. Content may be sent to the model and, if you give URLs that are fetched, to the internet. Avoid very sensitive documents.

How does it compare to other translation tools?

The source does not compare it with other tools. Its distinguishing features are the three modes, EXTEND.md preferences, glossary merging and chunking for long markdown files.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

baoyu-translate suits bloggers and translators who want consistent, glossary-aware Chinese or English versions of articles, and who can review the output. Skip it for certified or legal translation, or for very sensitive confidential documents, where a human translator or a local workflow is the safer choice.

Download the skill