Guide · Agent skill
How to use the Batch API Document Transform agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The batch-api skill is a bundled agent skill for Qwen Code that turns a large set of independent document tasks, such as translating or rewriting many files under one style guide, into a plan that is sent to the asynchronous DashScope Batch API at roughly half the realtime price. This guide explains what agent skills are, how to install this one, how to trigger it, and when it is the wrong tool. By the end you will know how to decide whether a job suits a slow, cheaper background run and how to approve one safely.
Batch API Document TransformQwenLM/qwen-code · Apache-2.0 Download the skill Quick start
- 1Install the skill. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Confirm requirements. Make sure you have the Qwen Code CLI with batch subcommands, a DashScope API key or equivalent Batch modelProviders entry, and network access. Do not use Qwen OAuth.
- 3Describe the task. Type /batch-api followed by a many-file, single-turn job such as translating a folder under a style guide.
- 4Let the agent run the readiness check. The agent runs the batch check command, which proves credentials and the Batch route work without a billed request.
- 5Review the dry-run preview. Read the item count, model line, cost estimate and digest the preview prints before deciding.
- 6Approve the exact snapshot. Approve the submission only for the previewed batch; the agent submits with the digest so nothing changes in between.
- 7Collect results later. Wait for the background notification, then check the delivered target files and any held or failed items.
What an agent skill is and what batch-api makes the agent do
An agent skill is a folder containing a SKILL.md file that gives an AI coding agent a set of instructions for one kind of task. This skill is invoked explicitly by typing /batch-api followed by your task, so it does not run on its own.
When you use it, the agent first checks that the Qwen CLI has its batch subcommands and that credentials and the Batch route work. If the job suits a slow background run, it writes a plan file listing your input and output files plus shared rules. It then previews the batch with a cost estimate and submits only after you approve that exact preview. Results arrive as new files hours later rather than in the chat.
Install the batch-api skill from the ZIP
Download the ZIP for the skill from this page and unzip it. The skill folder contains SKILL.md and SKILL.test.ts. Place the unzipped folder in one of these locations:
- Personal use across projects: ~/.claude/skills/
- Single project: the .claude/skills/ folder inside that project
- Claude apps: upload the skill under Settings → Capabilities → Skills
Check the requirements before you start
The skill needs the Qwen Code CLI with batch subcommands, a DashScope API key or an equivalent modelProviders entry configured for Batch, and network access to the provider's Batch endpoint. The skill runs scripts and uses the network. Qwen OAuth has no Batch route, so the readiness check will fail with that login method.
- Qwen Code CLI with batch subcommands
- DashScope API key or equivalent modelProviders entry configured for Batch
- Network access to the provider's Batch endpoint
Trigger the skill with a task
Type /batch-api and describe a many-file, single-turn job. The skill is suited to tasks where each file can be handled independently and all the input is available now. Good examples are translating a set of documents under a fixed style guide, rewriting files into a new format, or extracting structured data from each file in a set.
- /batch-api translate every file in docs/zh into English under our style guide, writing to docs/en
- /batch-api extract title, date and author as JSON from each file in reports/
- /batch-api rewrite these 300 product descriptions into our new format
Review the preview and approve the submission
The agent first runs a dry-run preview. It shows the item count, the frozen model, thinking and output-limit line, the cost estimate and a snapshot digest, and it uploads nothing and bills nothing. Read these lines before you approve. The agent then submits exactly that snapshot with the digest from the preview. If the batch changes after the preview, the agent runs the preview again and shows you the new one.
After submission, a background waiter polls the provider without calling a model. When the batch settles, the results are written to your target files, and the agent reports which targets were delivered and which items are held or failed.
qwen batch run .qwen/batch/plans/<slug>.json --dry-runKnow when not to use it
The skill is the wrong choice for debugging, run-test-fix loops or exploratory refactors, because each step depends on results that do not exist yet. It also saves nothing for a handful of files or for any job you need soon, since the wait adds delay. If the task is unsuitable, the agent will say so and stop. It will not quietly do the work at full realtime price; it may offer that as a choice.
What people use it for
- Translating a large set of independent documents into another language under one terminology list
- Rewriting many files into a new format where each file can be processed alone
- Extracting structured fields such as titles, dates or authors from a folder of documents
Frequently asked questions
What is the batch-api skill?
It is a bundled agent skill in Qwen Code that prepares a many-file, single-turn transform as a plan and submits it to the asynchronous, half-price DashScope Batch API. You invoke it explicitly with /batch-api. Results come back as new files hours later.
How do I install the batch-api skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
What do I need to run it?
You need the Qwen Code CLI with batch subcommands, a DashScope API key or equivalent modelProviders entry configured for Batch, and network access to the provider's Batch endpoint. The skill runs scripts and uses the network.
Is the batch-api skill free?
The skill is licensed under Apache-2.0. The Batch API bills requests at 50% of the realtime list price, and the readiness check does not make a billed request, but the source does not give a price for your account, so check your provider's pricing.
Why does the check fail with Qwen OAuth?
Qwen OAuth has no Batch route, so the readiness check cannot succeed. Configure a DashScope API key or an equivalent modelProviders entry for Batch instead.
Can I use batch-api for debugging or a few files?
No. Debugging and run-test-fix loops need results from earlier steps, and a handful of files gains nothing from the wait. Use a normal realtime session for those tasks.
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
Use batch-api if you have a large set of independent documents to translate, rewrite or extract, and you can wait hours for results in exchange for roughly half the realtime price. Pick a realtime workflow if you need answers soon, are working on a small set of files, or are debugging or iterating on code.
Download the skill