How to use the Batch Script Progress agent skill

What is an agent skill?

An agent skill is a folder containing a SKILL.md file with instructions, plus optional reference notes, examples and tests. When a skill is installed, a compatible agent can read it and follow its guidance when a task matches the skill's description. You do not need to run the skill yourself; you ask the agent for a task and the skill shapes how it works.

What the skill makes the agent do

When the agent edits a batch script, the skill guides it to add four kinds of output: a start line with the operation name and total, periodic progress lines with counters and elapsed time, a line for each per-item failure, and a final summary with completed, partial, failed or cancelled status and the exit status. Results stay on stdout, while progress and diagnostics go to stderr by default. The agent is told to keep the existing exit codes and retry, parallelism and failure policy unchanged.

The skill also states limits. It does not cover UI progress bars, front-end loading indicators, monitoring infrastructure or progress updates in the AI conversation. Where the output contract cannot change, the agent is told to stop and ask.

• Start: operation name, total or an explicit unknown, and initial counters
• Progress: processed, succeeded, failed, skipped, total or unknown, and elapsed time
• Item failure: a safe identifier, a sanitized reason, and whether processing continues
• Summary: final counters, elapsed time, unprocessed count if known, and the exit status

Install the skill

Download the ZIP file for batch-script-progress from this page. Then choose one of the two options below.

For a personal install that applies to all your projects, unzip the file into ~/.claude/skills/ so that the batch-script-progress folder with SKILL.md sits inside it. For a single project, unzip it into the .claude/skills/ folder inside that project.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

Trigger the skill with natural requests

You do not need a special command. Describe the script and the problem in plain words. The skill's description lists the situations it covers, such as batch scripts, bulk operations, silent long-running loops, progress reporting, per-item failures, final counts, stdout separation and exit-status consistency.

Mention the language and the file if you have them. The agent will read the existing script, its callers and nearby tests before editing, as the skill instructs.

• Add progress output to this Python script that processes the CSV files in ./input so I can see it is still running.
• This PowerShell script loops over 5,000 records calling an API and runs silently. Add start, periodic progress and per-item failure messages without changing the output.
• Make the Node.js import script report failures for each row and print a final count of succeeded, failed and skipped items.
• Review this batch job and check that its exit code still matches what the caller expects after adding logging.

Examples and tests included in the skill

The skill folder includes example scripts in Python and Node.js, plus a PowerShell reference in the notes, and a test file, tests/verify-examples.mjs, that runs the probes with harmless fixtures. The examples are output-contract probes, not production processors, so the agent is told to adapt their logging and counting to your code instead of copying their failure policy.

The test file refers to examples/batch.ps1. That PowerShell example was not included in the provided files, so the cross-language test cannot run fully from this package as supplied.

• examples/batch.py: Python probe using the standard library, with no external data access
• examples/batch.mjs: Node.js probe and test runner target
• references/language-notes.md: per-language stream and exit rules
• references/verification.md: test cases for normal, partial-failure, zero-item, unknown-total, fail-fast and cancellation runs
• tests/verify-examples.mjs: cross-language verifier

What you need

Python 3 is needed for the Python example and its tests. PowerShell (pwsh) is needed for the PowerShell example. Node.js is needed for the Node.js example and the test runner. The skill runs scripts when verifying them, and it does not use the network.

• Python 3
• PowerShell (pwsh), for the PowerShell example
• Node.js, for the Node.js example and test runner

Safety notes

The skill runs scripts during verification, so review what the agent executes, especially when working on real data. The bundled examples are designed to use harmless fixtures and do not read external data. The agent is instructed to redact credentials, query parameters, personal data and sensitive paths from logged output, and not to dump raw exceptions or whole input records by default.

Check that your logs contain no secrets before sharing them. Note that forced termination, process crashes and broken output pipes can stop final reporting.

Tips for good results

Tell the agent which callers read your script's output and what exit codes they expect. If a caller treats any stderr text as failure, the skill says to stop and ask rather than change the output channel.

Ask for periodic progress by item count or elapsed time, not for a line per item, to keep logs readable. For a long single item, the skill notes that a blocking step cannot print periodic updates, so the agent should report that gap instead of promising a heartbeat.

• State the existing exit-code contract up front
• Keep retry, parallelism and failure policy as they are; the skill will not change them
• Expect an honest 'unknown total' when input is a lazy stream