---
name: bundle-zip
description: Use when Codex needs to create a zip archive from an explicit file list while preserving source-relative paths, especially for GPT/CCRA review bundles, handoff packages, changed-file bundles, or Windows-safe packaging where PowerShell Compress-Archive may flatten paths. Use for newline-delimited file lists, root-marker-based zip entry names, overwrite-safe zip creation, and zip readback validation.
---

# Bundle Zip

## Purpose

Create a zip archive from an explicit newline-delimited file list while preserving paths relative to a named root path segment. Use the bundled Python script instead of PowerShell `Compress-Archive` when exact zip entry names matter.

The script uses Python standard-library `zipfile`; it does not implement compression itself.

## Command

Run from the repository or working directory that should resolve relative file-list entries:

```powershell
conda run -n skills-vault python .\scripts\bundle_zip.py `
  --file-list C:\path\files.txt `
  --relative-root-marker repo-name `
  --output C:\path\bundle.zip `
  --verify `
  --json
```

If the Skill is installed under `C:\Users\wangq\.agents\skills\bundle-zip`, use that installed script path or run from the installed Skill directory.

## Inputs

- `--file-list`: UTF-8 text file with one source file per line. Blank lines are ignored.
- `--relative-root-marker`: exact path segment that defines where zip entry names start. If a source path contains the marker zero times or more than once, fail.
- `--output`: destination zip path. The parent directory must already exist.
- `--verify`: accepted for explicit workflows; readback verification is always performed.
- `--json`: print machine-readable summary JSON to stdout.
- `--json-output`: optionally write the same validation summary to a JSON file.

File-list entries may be absolute paths or paths relative to the current working directory. Zip entry names always use `/`.

## Safety

- Validate all sources before replacing an existing output zip.
- Reject missing files, directories, duplicate zip entries, and an output path that is also a source file.
- Package only explicitly listed files; do not recursively package directories.
- Write a temporary zip next to the output, verify it, then replace the requested output zip.
- Do not modify source files.

## Validation

After editing the script, run:

```powershell
conda run -n skills-vault python -B -m unittest discover -s skills/bundle-zip/tests -v
```

For full repository confidence, also run relevant neighboring Skill tests when shared code or install behavior changes.