How to use the Batch File Operations agent skill (/batch)

What the batch skill makes the agent do

The skill is a set of instructions (SKILL.md) that tells the agent how to run a batch operation. You type /batch followed by an operation and a file pattern. The agent then parses your request, discovers matching files with glob, splits them into chunks and launches worker agents to process the chunks in parallel.

When the workers finish, the agent collects their results into a summary that lists successes, failures and skips per file.

• Finds files that match a glob pattern such as src/**/*.ts
• Skips common noise: node_modules, dist, build, .git, test files, lock files, minified JS, binary files and files over 500KB
• Splits the remaining files into chunks; workers run independently and at most 5 run at once
• Reports each file as SUCCESS, FAILED or SKIPPED

Install the batch skill

Download the ZIP file from this page and unzip it. The skill is a folder that contains SKILL.md, so the folder must end up in one of the locations below.

For a personal skill available in all your projects, unzip it into ~/.claude/skills/. For a skill that only applies to one project, unzip it into that project's .claude/skills/ folder.

In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with a natural request

Start your request with /batch, then state the operation and the file pattern. Be specific about which files you mean. If you leave the pattern out, the agent is told to infer it from context or ask you.

The skill accepts an argument hint of the form <operation> <file-pattern>, so keep both parts in the same request.

• Good: /batch Add Apache 2.0 license header to all .ts files in src/
• Good: /batch Convert all .js files in utils/ to TypeScript
• Vague: /batch fix stuff (no pattern, the agent will have to ask)

Worked examples

The source includes three example requests. In the first, the agent globs src/**/*.ts, finds 45 files, splits them into 4 chunks and runs 4 agents in parallel, each adding the header to its own files.

In the second, a JavaScript-to-TypeScript conversion over utils/ finds 12 files and splits them into 2 chunks. Two files can fail on complex dynamic patterns, and the summary reports them with reasons instead of stopping the batch.

In the third, the agent uses grep_search to find files containing ': any' in src/ and has workers replace the any types with proper types for a specific lint rule.

• License headers: uniform change across many files
• Format conversion: some files may fail and are reported individually
• Lint fixes: search first, then fix only the matching files

What it needs and safety notes

The skill needs Qwen Code or a compatible agent runtime that supports the tools it lists: glob, grep_search, read_file, edit, write_file, run_shell_command, task and ask_user_question. The source says the skill runs scripts and does not use the network.

The skill edits files in place and can write to disk and run shell commands. Commit your work or make a backup before running it, and review the summary and the diff afterwards. Do not rely on it for edits that depend on each other across files, because workers run independently and may conflict.

If more than 50 files match, the agent reports the exact count and file list before continuing. If more than 100 match, it warns you and asks for a more specific pattern.

• Use version control so every change can be reverted
• Keep patterns narrow for your first run
• Check the per-file report for failures and skips

Tips for better results

Write the operation as a single, checkable rule, such as 'Add JSDoc comments to all exported functions'. Workers are told to make minimal changes and to preserve existing style, so a clear rule gives the most predictable output.

For a large batch of independent one-shot transforms, such as translating or extracting each file into a new file, the skill may suggest that you type /batch-api yourself for the asynchronous Batch API. The agent cannot start that command itself, and it is not suited to in-place edits or tasks that need tool feedback.

• Test on one directory before running on the whole repo
• Name the exact file extension in the pattern
• Read the failed-files list and rerun only those files with a narrower request