zip-bundling

name	zip-bundling
description	Create technical ZIP bundles of code, design, and documentation for external review or context sharing. Use when you need to package multiple project files into a portable `.zip` archive instead of a single Markdown file.
version	1.0.0

ZIP Context Bundling Skill 📦

Overview

This skill centralizes the knowledge and workflows for creating compressed ZIP "Context Bundles." These bundles are essential for compiling large amounts of code and design files into their native formats, compressed into a single portable .zip file for human review or agent ingestion.

🎯 Primary Directive

Curate, Consolidate, and Archive. You do not just run the zip command; you architect context. You ensure that any bundle you create is:

1. Complete: Contains all required dependencies, documentation, and source code files.
2. Documented: The archiver automatically injects a _manifest_notes.md file inside the ZIP. You must populate the manifest's JSON "note" fields with rich explanations so this metadata is passed onto the reviewers.

Core Workflow: Generating a ZIP Bundle

The ZIP context bundler operates through the exact same JSON manifest pattern as the Markdown bundler.

1. Analyze the Intent

Before bundling, determine what the user is trying to accomplish:

• Code Review: Include implementation files and overarching logic.
• Red Team / Security: Include architecture diagrams and security protocols.
• Handoffs: Include README, .env.example, and structural scaffolding.

2. Formulate the Manifest Schema

You must generate a file-manifest.json containing the exact files to be bundled.

{
  "title": "Bundle Title",
  "description": "Short explanation of the bundle's goal.",
  "files": [
    {
      "path": "docs/architecture.md",
      "note": "Primary design document. Look closely at the Auth flow chart."
    },
    {
      "path": "src/main.py",
      "note": "Core implementation logic"
    }
  ]
}

3. Generate the ZIP Archive

Once the file-manifest.json is safely written to disk, invoke the native bundler script explicitly requesting a .zip output destination:

python3 "./scripts/bundle_zip.py" --manifest "file-manifest.json" --bundle "output_bundle.zip"

The script will automatically parse your JSON notes and generate a _manifest_notes.md root document explaining the archive contents to whoever unzips it.

Conditional Step Inclusion & Error Handling

If a file requested in the manifest does not exist or raises a permissions error:

1. Do not abort the entire archive generation.
2. Ensure the bundler script injects an explicit failure warning into the _manifest_notes.md root document:

   > 🔴 **NOT INCLUDED**: `missing/file.py` could not be read.
   

3. Proceed archiving the remaining valid files.

Best Practices & Anti-Patterns

1. Always Provide Notes: The note field in the manifest JSON is crucial for ZIP files because it becomes the only context passing through to the recipient's _manifest_notes.md index.
2. Directory Handling: If you pass a directory path like "path": "src/" in the manifest schema, the Python script will recursively expand it and include all valid, readable contents.

Common Bundling Mistakes

• Binary/Media Bloat: Including image assets without explicitly verifying if the downstream recipient can parse them.
• Silent Exclusion: Filtering out an unreadable file without explicitly declaring it missing in the manifest notes.