Repomix Unmixer Skill for Claude

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.