repomix unmixer
- Repo stars 0
- Author updated Aug 24, 2026, 07:33 AM
- Author repo claude-code-skills
- Domain
- Documentation
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @daymade · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Always Specify Output 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"
# 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:
```bash
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:**
```bash
python3 scripts/unmix_repomix.py \
"/path/to/repomix-output.xml" \
"/tmp/extracted-files"
```
### What the Script Does
1. **Parses** the repomix file format (XML, Markdown, or JSON)
2. **Extracts** each file path and content
3. **Creates** the original directory structure
4. **Writes** each file to its original location
5. **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:
```xml
<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:
```markdown
## 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:
```json
{
"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:
```bash
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:
```bash
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:
```bash
python3 scripts/unmix_repomix.py \
"/path/to/backup.xml" \
"~/workspace/restored-project"
```
## Validation Workflow
After unmixing, validate the extracted files are correct:
1. **Check file count**: Verify the number of extracted files matches expectations
2. **Review structure**: Use `tree` or `ls -R` to inspect directory layout
3. **Spot check content**: Read a few key files to verify content integrity
4. **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:
```bash
# 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:
```bash
# 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:
```bash
# 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:**
1. Verify the input file is a repomix output file
2. Check the format (XML/Markdown/JSON)
3. Examine the file structure manually
4. Refer to `references/repomix-format.md` for format details
### Permission Errors
**Issue**: Cannot write to output directory.
**Solution:**
```bash
# 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:**
```bash
# 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
1. **Extract to temp directories** - Always extract to `/tmp` or similar for initial review
2. **Verify file count** - Check that extracted file count matches expectations
3. **Review structure** - Use `tree` to inspect directory layout before use
4. **Check content** - Spot-check a few files to ensure content is intact
5. **Use validation tools** - For skills, use skill-creator validation after unmixing
6. **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.
Sections and files
Listed in source order.
sections -> Overview → When to Use This Skill → Core Workflow → Standard Unmixing Process → What the Script Does → Output
terms -> Parameters · Example · Parses · Extracts · Creates · Writes · Reports · Example output
files/cmd -> unmix_repomix.py · <path_to_repomix_file> · <output_directory> · <file path="...">content</file> · references/repomix-format.md · tree · ls -R · references/validation-workflow.md
body sha256 -> 6000ad74be71
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
Standard Unmixing Process
Extract all files from a repomix file and restore the original directory structure using the bundled
unmix_repomix.pyscript: 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: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