awesome-copilot/skills/batch-files/SKILL.md

name, description

name

description

batch-files

Expert-level Windows batch file (.bat/.cmd) skill for writing, debugging, and maintaining CMD scripts. Use when asked to "create a batch file", "write a .bat script", "automate a Windows task", "CMD scripting", "batch automation", "scheduled task script", "Windows shell script", or when working with .bat/.cmd files in the workspace. Covers cmd.exe syntax, environment variables, control flow, string processing, error handling, and integration with system tools.

Batch Files

A comprehensive skill for creating, editing, debugging, and maintaining Windows batch files (.bat/.cmd) using cmd.exe. Applies to CLI tool development, system administration automation, scheduled tasks, file operations scripting, and PATH-based executable scripts.

When to Use This Skill

• Creating or editing .bat or .cmd files
• Automating Windows tasks (file operations, deployments, backups)
• Building CLI tools intended for a bin/ folder on PATH
• Writing scheduled task scripts (SCHTASKS, Task Scheduler)
• Debugging batch script issues (variable expansion, error levels, quoting)
• Integrating batch scripts with external tools (curl, git, Node.js, Python)
• Scaffolding new batch-based projects with structured templates

Prerequisites

• Windows NT-based OS (Windows 7 or later)
• cmd.exe (built-in)
• Optional: a bin/ directory on PATH for distributing scripts as commands
• Optional: PATHEXT configured to include .BAT;.CMD (default on Windows)

Command Interpretation

cmd.exe processes each line through four stages in order:

1. Variable substitution — %VAR% tokens are replaced with environment variable values. %0–%9 reference batch arguments. %* expands to all arguments.
2. Quoting and escaping — Caret ^ escapes special characters (& | < > ^). Quotation marks prevent interpretation of enclosed special characters. In batch files, %% yields a literal %.
3. Syntax parsing — Lines are split into pipelines (|), compound commands (&, &&, ||), and parenthesized groups ( ).
4. Redirection — > overwrites, >> appends, < reads input, 2> redirects stderr, 2>&1 merges stderr into stdout, >NUL discards output.

Variables

Environment Variables

set _MY_VAR=Hello World
echo %_MY_VAR%
set _MY_VAR=

• set with no arguments lists all variables
• set _PREFIX lists variables starting with _PREFIX
• No spaces around = — set name = val sets variable "name " to " val"

Special Variables

Variable	Value
%CD%	Current directory
%DATE%	System date (locale-dependent)
%TIME%	System time HH:MM:SS.mm
%RANDOM%	Pseudorandom number 0–32767
%ERRORLEVEL%	Exit code of last command
%USERNAME%	Current user name
%USERPROFILE%	Current user profile path
%TEMP% / %TMP%	Temporary file directory
%PATHEXT%	Executable extensions list
%COMSPEC%	Path to cmd.exe

Scoping with SETLOCAL / ENDLOCAL

setlocal
set _LOCAL_VAR=scoped value
endlocal
REM _LOCAL_VAR is no longer defined here

To return a value from a scoped block:

endlocal & set _RESULT=%_LOCAL_VAR%

Delayed Expansion

Variables inside parenthesized blocks are expanded at parse time. Use delayed expansion for runtime evaluation:

setlocal EnableDelayedExpansion
set _COUNT=0
for /l %%i in (1,1,5) do (
    set /a _COUNT+=1
    echo !_COUNT!
)
endlocal

• !VAR! expands at execution time (delayed)
• %VAR% expands at parse time (immediate)

Control Flow

Conditional Execution

if exist "output.txt" echo File found
if not defined _MY_VAR echo Variable not set
if "%_STATUS%"=="ready" (echo Go) else (echo Wait)
if %ERRORLEVEL% neq 0 echo Command failed

Comparison operators: equ, neq, lss, leq, gtr, geq. Use /i for case-insensitive string comparison.

Compound Commands

command1 & command2        & REM Always run both
command1 && command2       & REM Run command2 only if command1 succeeds
command1 || command2       & REM Run command2 only if command1 fails

FOR Loops

REM Iterate over a set of values
for %%i in (alpha beta gamma) do echo %%i

REM Numeric range: start, step, end
for /l %%i in (1,1,10) do echo %%i

REM Files in a directory
for %%f in (*.txt) do echo %%f

REM Recursive file search
for /r %%f in (*.log) do echo %%f

REM Directories only
for /d %%d in (*) do echo %%d

REM Parse command output
for /f "tokens=1,2 delims=:" %%a in ('ipconfig ^| findstr "IPv4"') do echo %%b

REM Parse file lines
for /f "usebackq tokens=*" %%a in ("data.txt") do echo %%a

GOTO and Labels

goto :main_logic
:usage
echo Usage: %~nx0 [options]
exit /b 1

:main_logic
echo Running main logic...
goto :eof

goto :eof exits the current batch or subroutine. Labels start with :.

Command-Line Arguments

Syntax	Value
%0	Script name as invoked
%1–%9	Positional arguments
%*	All arguments (unaffected by SHIFT)
%~1	Argument 1 with enclosing quotes removed
%~f1	Full path of argument 1
%~d1	Drive letter of argument 1
%~p1	Path (without drive) of argument 1
%~n1	File name (no extension) of argument 1
%~x1	Extension of argument 1
%~dp0	Drive and path of the batch file itself
%~nx0	File name with extension of the batch file
%~z1	File size of argument 1
%~$PATH:1	Search PATH for argument 1

Argument Parsing Pattern

:parse_args
if "%~1"=="" goto :args_done
if /i "%~1"=="--help" goto :usage
if /i "%~1"=="--output" (
    set "_OUTPUT_DIR=%~2"
    shift
)
shift
goto :parse_args
:args_done

String Processing

Substrings

set _STR=Hello World
echo %_STR:~0,5%       & REM "Hello"
echo %_STR:~6%         & REM "World"
echo %_STR:~-5%        & REM "World"
echo %_STR:~0,-6%      & REM "Hello"

Search and Replace

set _STR=Hello World
echo %_STR:World=Earth%       & REM "Hello Earth"
echo %_STR:Hello=%            & REM " World" (remove "Hello")

Substring Containment Test

if not "%_STR:World=%"=="%_STR%" echo Contains "World"

Functions

Functions use labels, CALL, and SETLOCAL/ENDLOCAL:

@echo off
call :greet "Jane Doe"
echo Result: %_GREETING%
exit /b 0

:greet
setlocal
set "_MSG=Hello, %~1"
endlocal & set "_GREETING=%_MSG%"
exit /b 0

• call :label args invokes a function
• exit /b returns from the function (not the script)
• Use the endlocal & set trick to pass values out of a scoped block

Arithmetic

set /a performs 32-bit signed integer arithmetic:

set /a _RESULT=10 * 5 + 3
set /a _COUNTER+=1
set /a _REMAINDER=14 %% 3       & REM Use %% for modulo in batch files
set /a _BITS="255 & 0x0F"       & REM Bitwise AND

Supported operators: + - * / %% ( ) and bitwise & | ^ ~ << >>.

Hexadecimal (0xFF) and octal (077) literals are supported.

Error Handling

Error Level Conventions

• 0 = success
• Non-zero = failure (typically 1)

mycommand.exe
if %ERRORLEVEL% neq 0 (
    echo ERROR: mycommand failed with code %ERRORLEVEL%
    exit /b %ERRORLEVEL%
)

Fail-Fast Pattern

command1 || (echo command1 failed & exit /b 1)
command2 || (echo command2 failed & exit /b 1)

Setting Exit Codes

exit /b 0        & REM Return success from a batch/function
exit /b 1        & REM Return failure
cmd /c "exit /b 42"   & REM Set ERRORLEVEL to 42 inline

Essential Commands Reference

File Operations

Command	Purpose
DIR	List directory contents
COPY	Copy files
XCOPY	Extended copy with subdirectories (legacy)
ROBOCOPY	Robust copy with retry, mirror, logging
MOVE	Move or rename files
DEL	Delete files
REN	Rename files
MD / MKDIR	Create directories
RD / RMDIR	Remove directories
MKLINK	Create symbolic or hard links
ATTRIB	View or set file attributes
TYPE	Print file contents
MORE	Paginated file display
TREE	Display directory structure
REPLACE	Replace files in destination with source
COMPACT	Show or set NTFS compression
EXPAND	Extract from .cab files
MAKECAB	Create .cab archives
TAR	Create or extract tar archives

Text Search and Processing

Command	Purpose
FIND	Search for literal strings
FINDSTR	Search with limited regular expressions
SORT	Sort lines alphabetically
CLIP	Copy piped input to clipboard
FC	Compare two files
COMP	Binary file comparison
CERTUTIL	Encode/decode Base64, compute hashes

System Information

Command	Purpose
SYSTEMINFO	Full system configuration
HOSTNAME	Display computer name
VER	Windows version
WHOAMI	Current user and group info
TASKLIST	List running processes
TASKKILL	Terminate processes
WMIC	WMI queries (drives, OS, memory)
SC	Service control (query, start, stop)
DRIVERQUERY	List installed drivers
REG	Registry operations (query, add, delete)
SETX	Set persistent environment variables

Network

Command	Purpose
PING	Test network connectivity
IPCONFIG	IP configuration
NSLOOKUP	DNS lookup
NETSTAT	Network connections and ports
TRACERT	Trace route to host
NET USE	Map/disconnect network drives
NET USER	Manage user accounts
NETSH	Network configuration utility
ARP	ARP cache management
ROUTE	Routing table management
CURL	HTTP requests (Windows 10+)
SSH	Secure shell (Windows 10+)

Scheduling and Automation

Command	Purpose
SCHTASKS	Create and manage scheduled tasks
TIMEOUT	Wait N seconds (Vista+)
START	Launch programs asynchronously
RUNAS	Run as different user
SHUTDOWN	Shutdown or restart
FORFILES	Find files by date and execute commands

Shell Utilities

Command	Purpose
WHERE	Locate executables in PATH
DOSKEY	Create command macros
CHOICE	Prompt for single-key input
MODE	Configure console size and ports
SUBST	Map folder to drive letter
CHCP	Get or set console code page
COLOR	Set console colors
TITLE	Set console window title
ASSOC / FTYPE	File type associations

Shell Syntax and Expressions

Parentheses for Grouping

Parentheses turn compound commands into a single unit for redirection or conditional execution:

(echo Line 1 & echo Line 2) > output.txt
if exist "data.csv" (
    echo Processing...
    call :process "data.csv"
) else (
    echo No data found.
)

Escape Characters

The caret ^ escapes the next character:

echo Total ^& Summary          & REM Outputs: Total & Summary
echo 100%% complete            & REM Outputs: 100% complete (in batch)
echo Line one^
Line two                       & REM Caret escapes the newline

After a pipe, triple caret is needed: echo x ^^^& y | findstr x

Wildcards

• * matches any sequence of characters
• ? matches a single character (or zero at end of period-free segment)

dir *.txt           & REM All .txt files
ren *.jpeg *.jpg    & REM Bulk rename

Redirection Summary

command > file.txt          & REM Overwrite stdout to file
command >> file.txt         & REM Append stdout to file
command 2> errors.log       & REM Redirect stderr
command > all.log 2>&1      & REM Merge stderr into stdout
command < input.txt         & REM Read stdin from file
command > NUL 2>&1          & REM Discard all output

Writing Production-Quality Batch Files

Standard Script Structure

@echo off
setlocal EnableDelayedExpansion

REM ============================================================
REM  Script: example.bat
REM  Purpose: Describe what this script does
REM ============================================================

call :main %*
exit /b %ERRORLEVEL%

:main
    call :parse_args %*
    if not defined _TARGET (
        echo ERROR: --target is required. 1>&2
        call :usage
        exit /b 1
    )
    echo Processing: %_TARGET%
    exit /b 0

:parse_args
    if "%~1"=="" exit /b 0
    if /i "%~1"=="--target" set "_TARGET=%~2" & shift
    if /i "%~1"=="--help"   call :usage & exit /b 0
    shift
    goto :parse_args

:usage
    echo Usage: %~nx0 --target ^<path^> [--help]
    echo.
    echo Options:
    echo   --target   Path to process (required)
    echo   --help     Show this help message
    exit /b 0

Best Practices

1. Always start with @echo off and setlocal — Prevents noisy output and variable leakage to the caller.
2. Validate inputs before processing — Check required arguments and file existence early. Use if not defined and if not exist.
3. Quote paths and variables — Use "%~1" and "%_MY_PATH%" to handle spaces and special characters safely.
4. Use exit /b instead of exit — Avoids closing the parent console window.
5. Return meaningful exit codes — exit /b 0 for success, non-zero for specific failures.
6. Use %~dp0 for script-relative paths — Ensures the script works regardless of the caller's working directory.
7. Prefer ROBOCOPY over XCOPY — More reliable, supports retry, mirroring, and logging.
8. Use EnableDelayedExpansion when modifying variables inside loops or parenthesized blocks.
9. Write errors to stderr — echo ERROR: message 1>&2 keeps stdout clean for piping.
10. Use REM for comments — :: can cause issues inside FOR loop bodies.

Security Considerations

• Never store credentials in batch files — Use environment variables, credential stores, or prompts.
• Validate user input — Unquoted variables containing &, |, or > can inject commands. Always quote: "%_USER_INPUT%".
• Use SETLOCAL — Prevents variable values from leaking to parent processes.
• Sanitize file paths — Validate paths before passing to DEL, RD, or ROBOCOPY to prevent unintended deletion.
• Avoid SET /P for sensitive input — Input is visible and stored in console history. Use a dedicated credential tool when possible.

Debugging and Troubleshooting

Technique	How
Trace execution	Remove @echo off or use @echo on temporarily
Step through	Add PAUSE between sections
Check error level	echo Exit code: %ERRORLEVEL% after each command
Inspect variables	set _MY_ to list all variables starting with _MY_
Delayed expansion issues	Variable inside ( ) block not updating? Enable !VAR! syntax
FOR loop %% vs %	Use %%i in batch files, %i on the command line
Spaces in SET	set name=value not set name = value
Caret in pipes	After a pipe, use ^^^ to escape special chars
Parentheses in SET /A	Escape with ^( and ^) inside if blocks, or use quotes
Double percent for modulo	set /a r=14 %% 3 in batch files

Cross-Platform and Extended Tools

When batch scripting reaches its limits, these tools extend cmd.exe capabilities:

Tool	Purpose
Cygwin	Full POSIX environment on Windows (grep, sed, awk, ssh)
MSYS2	Lightweight Unix tools and package manager (pacman)
WSL	Windows Subsystem for Linux — run native Linux binaries
GnuWin32	Individual GNU utilities as native Windows executables
PowerShell	Modern Windows scripting with .NET integration

Use batch when you need: fast startup, simple file operations, PATH-based CLI tools, or Task Scheduler integration. Consider PowerShell or WSL for complex data processing, REST APIs, or object-oriented scripting.

CMD Keyboard Shortcuts

Shortcut	Action
Tab	Auto-complete file/folder names
Up / Down	Navigate command history
F7	Show command history popup
F3	Repeat last command
Esc	Clear current line
Ctrl+C	Cancel running command
Alt+F7	Clear command history

Reference Files

The references/ folder contains detailed documentation:

File	Contents
tools-and-resources.md	Windows tools, utilities, package managers, terminals
batch-files-and-functions.md	Example scripts, techniques, best practices links
windows-commands.md	Comprehensive A-Z Windows command reference
cygwin.md	Cygwin user guide and FAQ
msys2.md	MSYS2 installation, packages, and environments
windows-subsystem-on-linux.md	WSL setup, commands, and documentation

Asset Templates

The assets/ folder contains starter batch file template data, but as text files:

Template	Purpose
executable.txt	Standalone CLI tool with argument parsing
library.txt	Reusable function library with CALL-able labels
task.txt	Scheduled task / automation script