Repomix Unmixer

Overview

This skill extracts files from repomix-packed repositories and restores their original directory structure. Repomix packs entire repositories into single AI-friendly files (XML, Markdown, or JSON), and this skill reverses that process to restore individual files.

When to Use This Skill

This skill activates when:

• Unmixing a repomix output file (.xml, .md, *.json)

• Extracting files from a packed repository

• Restoring original directory structure from repomix format

• Reviewing or validating repomix-packed content

• Converting repomix output back to usable files

Core Workflow

Standard Unmixing Process

Extract all files from a repomix file and restore the original directory structure using the bundled unmix_repomix.py script:

python3 scripts/unmix_repomix.py \

  "<path_to_repomix_file>" \

  "<output_directory>"

Parameters:

• <path_to_repomix_file>: Path to the repomix output file (XML, Markdown, or JSON)

• <output_directory>: Directory where files will be extracted (will be created if doesn't exist)

Example:

python3 scripts/unmix_repomix.py \

  "/path/to/repomix-output.xml" \

  "/tmp/extracted-files"

What the Script Does

• Parses the repomix file format (XML, Markdown, or JSON)

• Extracts each file path and content

• Creates the original directory structure

• Writes each file to its original location

• Reports extraction progress and statistics

Output

The script will:

• Create all necessary parent directories

• Extract all files maintaining their paths

• Print extraction progress for each file

• Display total count of extracted files

Example output:

Unmixing /path/to/skill.xml...

Output directory: /tmp/extracted-files

✓ Extracted: github-ops/SKILL.md

✓ Extracted: github-ops/references/api_reference.md

✓ Extracted: markdown-tools/SKILL.md

...

✅ Successfully extracted 20 files!

Extracted files are in: /tmp/extracted-files

Supported Formats

XML Format (default)

Repomix XML format structure:

<file path="relative/path/to/file.ext">

file content here

</file>

The script uses regex to match <file path="...">content</file> blocks.

Markdown Format

For markdown-style repomix output with file markers:

## File: relative/path/to/file.ext

file content

Refer to references/repomix-format.md for detailed format specifications.

JSON Format

For JSON-style repomix output:

{

  "files": [

    {

      "path": "relative/path/to/file.ext",

      "content": "file content here"

    }

  ]

}

Common Use Cases

Use Case 1: Unmix Claude Skills

Extract skills that were shared as a repomix file:

python3 scripts/unmix_repomix.py \

  "/path/to/skills.xml" \

  "/tmp/unmixed-skills"

Then review, validate, or install the extracted skills.

Use Case 2: Extract Repository for Review

Extract a packed repository to review its structure and contents:

python3 scripts/unmix_repomix.py \

  "/path/to/repo-output.xml" \

  "/tmp/review-repo"

# Review the structure

tree /tmp/review-repo

Use Case 3: Restore Working Files

Restore files from a repomix backup to a working directory:

python3 scripts/unmix_repomix.py \

  "/path/to/backup.xml" \

  "~/workspace/restored-project"

Validation Workflow

After unmixing, validate the extracted files are correct:

• Check file count: Verify the number of extracted files matches expectations

• Review structure: Use tree or ls -R to inspect directory layout

• Spot check content: Read a few key files to verify content integrity

• Run validation: For skills, use the skill-creator validation tools

Refer to references/validation-workflow.md for detailed validation procedures, especially for unmixing Claude skills.

Important Principles

Always Specify Output Directory

Always provide an output directory to avoid cluttering the current working directory:

# Good: Explicit output directory

python3 scripts/unmix_repomix.py \

  "input.xml" "/tmp/output"

# Avoid: Default output (may clutter current directory)

python3 scripts/unmix_repomix.py "input.xml"

Use Temporary Directories for Review

Extract to temporary directories first for review:

# Extract to /tmp for review

python3 scripts/unmix_repomix.py \

  "skills.xml" "/tmp/review-skills"

# Review the contents

tree /tmp/review-skills

# If satisfied, copy to final destination

cp -r /tmp/review-skills ~/.claude/skills/

Verify Before Overwriting

Never extract directly to important directories without review:

# Bad: Might overwrite existing files

python3 scripts/unmix_repomix.py \

  "repo.xml" "~/workspace/my-project"

# Good: Extract to temp, review, then move

python3 scripts/unmix_repomix.py \

  "repo.xml" "/tmp/extracted"

# Review, then:

mv /tmp/extracted ~/workspace/my-project

Troubleshooting

No Files Extracted

Issue: Script completes but no files are extracted.

Possible causes:

• Wrong file format (not a repomix file)

• Unsupported repomix format version

• File path pattern doesn't match

Solution:

• Verify the input file is a repomix output file

• Check the format (XML/Markdown/JSON)

• Examine the file structure manually

• Refer to references/repomix-format.md for format details

Permission Errors

Issue: Cannot write to output directory.

Solution:

# Ensure output directory is writable

mkdir -p /tmp/output

chmod 755 /tmp/output

# Or use a directory you own

python3 scripts/unmix_repomix.py \

  "input.xml" "$HOME/extracted"

Encoding Issues

Issue: Special characters appear garbled in extracted files.

Solution:

The script uses UTF-8 encoding by default. If issues persist:

• Check the original repomix file encoding

• Verify the file was created correctly

• Report the issue with specific character examples

Path Already Exists

Issue: Files exist at extraction path.

Solution:

# Option 1: Use a fresh output directory

python3 scripts/unmix_repomix.py \

  "input.xml" "/tmp/output-$(date +%s)"

# Option 2: Clear the directory first

rm -rf /tmp/output && mkdir /tmp/output

python3 scripts/unmix_repomix.py \

  "input.xml" "/tmp/output"

Best Practices

• Extract to temp directories - Always extract to /tmp or similar for initial review

• Verify file count - Check that extracted file count matches expectations

• Review structure - Use tree to inspect directory layout before use

• Check content - Spot-check a few files to ensure content is intact

• Use validation tools - For skills, use skill-creator validation after unmixing

• Preserve originals - Keep the original repomix file as backup

Resources

scripts/unmix_repomix.py

Main unmixing script that:

• Parses repomix XML/Markdown/JSON formats

• Extracts file paths and content using regex

• Creates directory structures automatically

• Writes files to their original locations

• Reports extraction progress and statistics

The script is self-contained and requires only Python 3 standard library.

references/repomix-format.md

Comprehensive documentation of repomix file formats including:

• XML format structure and examples

• Markdown format patterns

• JSON format schema

• File path encoding rules

• Content extraction patterns

• Format version differences

Load this reference when dealing with format-specific issues or supporting new repomix versions.

references/validation-workflow.md

Detailed validation procedures for extracted content including:

• File count verification steps

• Directory structure validation

• Content integrity checks

• Skill-specific validation using skill-creator tools

• Quality assurance checklists

Load this reference when users need to validate unmixed skills or verify extraction quality.