Repomix Unmixer

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

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:

<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:

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:

# 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: 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:

# 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

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.

Repomix Unmixer Skill

A Claude Code skill for extracting files from repomix-packed repositories and restoring their original directory structure.

Overview

Repomix packs entire repositories into single AI-friendly files (XML, Markdown, or JSON). This skill reverses that process, extracting all files and restoring the original directory structure.

Quick Start

Installation

1. Download repomix-unmixer.zip 2. Extract to ~/.claude/skills/repomix-unmixer/ 3. Restart Claude Code

Basic Usage

Extract a repomix file:

python3 ~/.claude/skills/repomix-unmixer/scripts/unmix_repomix.py \
  "<path_to_repomix_file>" \
  "<output_directory>"

Example:

python3 ~/.claude/skills/repomix-unmixer/scripts/unmix_repomix.py \
  "/path/to/skills.xml" \
  "/tmp/extracted-skills"

Features

• Multi-format support: XML (default), Markdown, and JSON repomix formats
• Auto-detection: Automatically detects repomix format
• Structure preservation: Restores original directory structure
• UTF-8 encoding: Handles international characters correctly
• Progress reporting: Shows extraction progress and statistics
• Validation workflows: Includes comprehensive validation guides

Supported Formats

XML Format (default)

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

Markdown Format

````markdown

File: relative/path/to/file.ext

content here

````

JSON Format

{
  "files": [
    {"path": "file.ext", "content": "content here"}
  ]
}

Bundled Resources

scripts/unmix_repomix.py

Main unmixing script with:

• Format auto-detection
• Multi-format parsing (XML, Markdown, JSON)
• Directory structure creation
• Progress reporting

references/repomix-format.md

Comprehensive format documentation:

• XML, Markdown, and JSON format specifications
• Extraction patterns and regex
• Edge cases and examples
• Format detection logic

references/validation-workflow.md

Detailed validation procedures:

• File count verification
• Directory structure validation
• Content integrity checks
• Skill-specific validation for Claude Code skills
• Quality assurance checklists

Common Use Cases

Unmix Claude Skills

python3 ~/.claude/skills/repomix-unmixer/scripts/unmix_repomix.py \
  "skills.xml" "/tmp/review-skills"

# Review and validate
tree /tmp/review-skills

# Install if valid
cp -r /tmp/review-skills/* ~/.claude/skills/

Extract Repository for Review

python3 ~/.claude/skills/repomix-unmixer/scripts/unmix_repomix.py \
  "repo-output.xml" "/tmp/review-repo"

# Review structure
tree /tmp/review-repo

Restore from Backup

python3 ~/.claude/skills/repomix-unmixer/scripts/unmix_repomix.py \
  "backup.xml" "~/workspace/restored-project"

Validation

After extraction, validate the results:

1. Check file count: Verify extracted count matches expected 2. Review structure: Use tree to inspect directory layout 3. Spot check content: Read a few files to verify integrity 4. Run validation: For skills, use skill-creator validation

For detailed validation procedures, see references/validation-workflow.md.

Requirements

• Python 3.6 or higher
• Standard library only (no external dependencies)

Skill Activation

This skill activates when:

• Unmixing a repomix output file
• Extracting files from a packed repository
• Restoring original directory structure
• Reviewing repomix-packed content
• Converting repomix output back to usable files

Best Practices

1. Extract to temp directories - Always extract to /tmp for initial review 2. Verify file count - Check extracted count matches expectations 3. Review structure - Inspect directory layout before use 4. Check content - Spot-check files for integrity 5. Use validation tools - For skills, use skill-creator validation 6. Preserve originals - Keep the repomix file as backup

Troubleshooting

No Files Extracted

• Verify input file is a valid repomix file
• Check format (XML/Markdown/JSON)
• Refer to references/repomix-format.md

Permission Errors

• Ensure output directory is writable
• Use mkdir -p to create directory first
• Check file permissions

Encoding Issues

• Script uses UTF-8 by default
• Verify repomix file encoding
• Check for special characters

Version

• Version: 1.0.0
• Created: 2025-10-22
• Last Updated: 2025-10-22

License

This skill follows the same license as Claude Code.

Support

For issues or questions: 1. Check references/repomix-format.md for format details 2. Review references/validation-workflow.md for validation help 3. Inspect the script source code at scripts/unmix_repomix.py 4. Report issues to the skill creator

Credits

Created using the skill-creator skill for Claude Code.

Repomix File Format Reference

This document provides comprehensive documentation of repomix output formats for accurate file extraction.

Overview

Repomix can generate output in three formats: 1. XML (default) - Most common, uses XML tags 2. Markdown - Human-readable, uses markdown code blocks 3. JSON - Structured data format

XML Format

Structure

The XML format is the default and most common repomix output:

<file_summary>
  [Summary and metadata about the packed repository]
</file_summary>

<directory_structure>
  [Text-based directory tree visualization]
</directory_structure>

<files>
  <file path="relative/path/to/file1.ext">
  content of file1
  </file>

  <file path="relative/path/to/file2.ext">
  content of file2
  </file>
</files>

File Block Pattern

Each file is enclosed in a <file> tag with a path attribute:

<file path="src/main.py">
#!/usr/bin/env python3

def main():
    print("Hello, world!")

if __name__ == "__main__":
    main()
</file>

Key Characteristics

• File path is in the path attribute (relative path)
• Content starts on the line after the opening tag
• Content ends on the line before the closing tag
• No leading/trailing blank lines in content (content is trimmed)

Extraction Pattern

The unmixing script uses this regex pattern:

r'<file path="([^"]+)">\n(.*?)\n</file>'

Pattern breakdown:

• <file path="([^"]+)"> - Captures the file path from the path attribute
• \n - Expects a newline after opening tag
• (.*?) - Captures file content (non-greedy, allows multiline)
• \n</file> - Expects newline before closing tag

Markdown Format

Structure

The Markdown format uses code blocks to delimit file content:

````markdown

Repository Summary

[Summary content]

Directory Structure

directory/
  file1.txt
  file2.txt

Files

File: relative/path/to/file1.ext

# File content here
def example():
    pass

File: relative/path/to/file2.ext

// Another file
console.log("Hello");

````

File Block Pattern

Each file uses a level-3 heading with "File:" prefix and code block:

````markdown

File: src/main.py

#!/usr/bin/env python3

def main():
    print("Hello, world!")

````

Key Characteristics

• File path follows "### File: " heading
• Content is within a code block (triple backticks)
• Language hint may be included after opening backticks
• Content preserves original formatting

Extraction Pattern

r'## File: ([^\n]+)\n```[^\n]*\n(.*?)\n```'

Pattern breakdown:

• ## File: ([^\n]+) - Captures file path from heading
• \n - Newline after heading
• `` [^\n]* `` - Opening code block with optional language
• \n(.*?)\n - Captures content between backticks
• `` `` `` - Closing backticks

JSON Format

Structure

The JSON format provides structured data:

{
  "metadata": {
    "repository": "owner/repo",
    "timestamp": "2025-10-22T19:00:00Z"
  },
  "directoryStructure": "directory/\n  file1.txt\n  file2.txt\n",
  "files": [
    {
      "path": "relative/path/to/file1.ext",
      "content": "content of file1\n"
    },
    {
      "path": "relative/path/to/file2.ext",
      "content": "content of file2\n"
    }
  ]
}

File Entry Structure

Each file is an object in the files array:

{
  "path": "src/main.py",
  "content": "#!/usr/bin/env python3\n\ndef main():\n    print(\"Hello, world!\")\n\nif __name__ == \"__main__\":\n    main()\n"
}

Key Characteristics

• Files are in a files array
• Each file has path and content keys
• Content includes literal \n for newlines
• Content is JSON-escaped (quotes, backslashes)

Extraction Approach

data = json.loads(content)
files = data.get('files', [])
for file_entry in files:
    file_path = file_entry.get('path')
    file_content = file_entry.get('content', '')

Format Detection

Detection Logic

The unmixing script auto-detects format using these checks:

1. XML: Contains <file path= and </file> 2. JSON: Starts with { and contains "files" 3. Markdown: Contains ## File:

Detection Priority

1. Check XML markers first (most common) 2. Check JSON structure second 3. Check Markdown markers last 4. Return None if no format matches

Example Detection Code

def detect_format(content):
    if '<file path=' in content and '</file>' in content:
        return 'xml'
    if content.strip().startswith('{') and '"files"' in content:
        return 'json'
    if '## File:' in content:
        return 'markdown'
    return None

File Path Encoding

Relative Paths

All file paths in repomix output are relative to the repository root:

src/components/Header.tsx
docs/README.md
package.json

Special Characters

File paths may contain:

• Spaces: "My Documents/file.txt"
• Hyphens: "some-file.md"
• Underscores: "my_script.py"
• Dots: "config.local.json"

Paths are preserved exactly as they appear in the original repository.

Directory Separators

• Always forward slashes (/) regardless of platform
• No leading slash (relative paths)
• No trailing slash for files

Content Encoding

Character Encoding

All formats use UTF-8 encoding for both the container file and extracted content.

Special Characters

• XML: Content may contain XML-escaped characters (<, >, &)
• Markdown: Content is plain text within code blocks
• JSON: Content uses JSON string escaping (\", \\, \n)

Line Endings

• Original line endings are preserved
• May be \n (Unix), \r\n (Windows), or \r (old Mac)
• Extraction preserves original endings

Edge Cases

Empty Files

XML:

<file path="empty.txt">
</file>

Markdown: ````markdown

File: empty.txt

````

JSON:

{"path": "empty.txt", "content": ""}

Binary Files

Binary files are typically not included in repomix output. The directory structure may list them, but they won't have content blocks.

Large Files

Some repomix configurations may truncate or exclude large files. Check the file summary section for exclusion notes.

Version Differences

Repomix v1.x

• Uses XML format by default
• File blocks have consistent structure
• No automatic format version marker

Repomix v2.x

• Adds JSON and Markdown format support
• May include version metadata in output
• Maintains backward compatibility with v1 XML

Validation

Successful Extraction Indicators

After extraction, verify: 1. File count matches expected number 2. Directory structure matches the <directory_structure> section 3. Content integrity - spot-check a few files 4. No empty directories unless explicitly included

Common Format Issues

Issue: Files not extracted

• Cause: Format pattern mismatch
• Solution: Check format manually, verify repomix version

Issue: Partial content extraction

• Cause: Incorrect regex pattern (too greedy or not greedy enough)
• Solution: Check for nested tags or malformed blocks

Issue: Encoding errors

• Cause: Non-UTF-8 content in repomix file
• Solution: Verify source file encoding

Examples

Complete XML Example

<file_summary>
This is a packed repository.
</file_summary>

<directory_structure>
my-skill/
  SKILL.md
  scripts/
    helper.py
</directory_structure>

<files>
<file path="my-skill/SKILL.md">
---
name: my-skill
description: Example skill
---

# My Skill

This is an example.
</file>

<file path="my-skill/scripts/helper.py">
#!/usr/bin/env python3

def help():
    print("Helping!")
</file>
</files>

Complete Markdown Example

````markdown

Repository: my-skill

Directory Structure

my-skill/
  SKILL.md
  scripts/
    helper.py

Files

File: my-skill/SKILL.md

---
name: my-skill
description: Example skill
---

# My Skill

This is an example.

File: my-skill/scripts/helper.py

#!/usr/bin/env python3

def help():
    print("Helping!")

````

Complete JSON Example

{
  "metadata": {
    "repository": "my-skill"
  },
  "directoryStructure": "my-skill/\n  SKILL.md\n  scripts/\n    helper.py\n",
  "files": [
    {
      "path": "my-skill/SKILL.md",
      "content": "---\nname: my-skill\ndescription: Example skill\n---\n\n# My Skill\n\nThis is an example.\n"
    },
    {
      "path": "my-skill/scripts/helper.py",
      "content": "#!/usr/bin/env python3\n\ndef help():\n    print(\"Helping!\")\n"
    }
  ]
}

References

• Repomix documentation: https://github.com/yamadashy/repomix
• Repomix output examples: Check the repomix repository for sample outputs
• XML specification: https://www.w3.org/XML/
• JSON specification: https://www.json.org/

Validation Workflow for Unmixed Content

This guide provides detailed validation procedures for verifying the quality and correctness of unmixed repomix content, with special focus on Claude Code skills.

Overview

After unmixing a repomix file, validation ensures:

• All files were extracted correctly
• Directory structure is intact
• Content integrity is preserved
• Skills (if applicable) meet Claude Code requirements

General Validation Workflow

Step 1: File Count Verification

Compare the extracted file count with the expected count.

Check extraction output:

✅ Successfully extracted 20 files!

Verify against directory structure:

# Count files in the repomix directory structure section
grep -c "^  " repomix-file.xml

# Count extracted files
find /tmp/extracted -type f | wc -l

Expected result: Counts should match (accounting for any excluded binary files).

Step 2: Directory Structure Validation

Compare the extracted structure with the repomix directory structure section.

Extract directory structure from repomix file:

# For XML format
sed -n '/<directory_structure>/,/<\/directory_structure>/p' repomix-file.xml

Compare with extracted structure:

tree /tmp/extracted
# or
ls -R /tmp/extracted

Validation checks:

• [ ] All directories present
• [ ] Nesting levels match
• [ ] No unexpected directories

Step 3: Content Integrity Spot Checks

Randomly select 3-5 files to verify content integrity.

Check file size:

# Compare sizes (should be reasonable)
ls -lh /tmp/extracted/path/to/file.txt

Check content:

# Read the file and verify it looks correct
cat /tmp/extracted/path/to/file.txt

Validation checks:

• [ ] Content is readable (UTF-8 encoded)
• [ ] No obvious truncation
• [ ] Code/markup is properly formatted
• [ ] No XML/JSON escape artifacts (e.g., < instead of <)

Step 4: File Type Distribution

Verify that expected file types are present.

Check file types:

# List all file extensions
find /tmp/extracted -type f | sed 's/.*\.//' | sort | uniq -c

Expected distributions:

• Skills: .md, .py, .sh, .json, etc.
• Projects: Language-specific extensions
• Documentation: .md, .txt, .pdf, etc.

Skill-Specific Validation

For Claude Code skills extracted from repomix files, perform additional validation.

Step 1: Verify Skill Structure

Check that each skill has the required SKILL.md file.

Find all SKILL.md files:

find /tmp/extracted -name "SKILL.md"

Expected result: One SKILL.md per skill directory.

Step 2: Validate YAML Frontmatter

Each SKILL.md must have valid YAML frontmatter with name and description.

Check frontmatter:

head -n 5 /tmp/extracted/skill-name/SKILL.md

Expected format:

---
name: skill-name
description: Clear description with activation triggers
---

Validation checks:

• [ ] Opening --- on line 1
• [ ] name: field present
• [ ] description: field present
• [ ] Closing --- present
• [ ] Description mentions when to activate

Step 3: Verify Resource Organization

Check that bundled resources follow the proper structure.

Check directory structure:

tree /tmp/extracted/skill-name

Expected structure:

skill-name/
├── SKILL.md (required)
├── scripts/ (optional)
│   └── *.py, *.sh
├── references/ (optional)
│   └── *.md
└── assets/ (optional)
    └── templates, images, etc.

Validation checks:

• [ ] SKILL.md exists at root
• [ ] Resources organized in proper directories
• [ ] No unexpected directories (e.g., __pycache__, .git)

Step 4: Validate with skill-creator

Use the skill-creator validation tools for comprehensive validation.

Run quick validation:

~/.claude/plugins/marketplaces/anthropics-skills/skill-creator/scripts/quick_validate.py \
  /tmp/extracted/skill-name

Expected output:

✅ Skill structure is valid
✅ YAML frontmatter is valid
✅ Description is informative
✅ All resource references are valid

Common validation errors:

• Missing or malformed YAML frontmatter
• Description too short or missing activation criteria
• References to non-existent files
• Improper directory structure

Step 5: Content Quality Checks

Verify the content quality of each skill.

Check SKILL.md length:

wc -l /tmp/extracted/skill-name/SKILL.md

Recommended: 100-500 lines for most skills (lean, with details in references).

Check for TODOs:

grep -i "TODO" /tmp/extracted/skill-name/SKILL.md

Expected result: No TODOs (unless intentional).

Check writing style:

# Should use imperative/infinitive form
head -n 50 /tmp/extracted/skill-name/SKILL.md

Validation checks:

• [ ] Uses imperative form ("Extract files from..." not "You extract files...")
• [ ] Clear section headings
• [ ] Code examples properly formatted
• [ ] Resources properly referenced

Step 6: Bundled Resource Validation

Verify bundled scripts, references, and assets are intact.

Check scripts are executable:

ls -l /tmp/extracted/skill-name/scripts/

Check for shebang in Python/Bash scripts:

head -n 1 /tmp/extracted/skill-name/scripts/*.py
head -n 1 /tmp/extracted/skill-name/scripts/*.sh

Expected: #!/usr/bin/env python3 or #!/bin/bash

Verify references are markdown:

file /tmp/extracted/skill-name/references/*.md

Expected: All files are text/UTF-8

Validation checks:

• [ ] Scripts have proper shebangs
• [ ] Scripts are executable (or will be made executable)
• [ ] References are readable markdown
• [ ] Assets are in expected formats

Automated Validation Script

For batch validation of multiple skills:

#!/bin/bash
# validate_all_skills.sh

EXTRACTED_DIR="/tmp/extracted"
SKILL_CREATOR_VALIDATOR="$HOME/.claude/plugins/marketplaces/anthropics-skills/skill-creator/scripts/quick_validate.py"

echo "Validating all skills in $EXTRACTED_DIR..."

for skill_dir in "$EXTRACTED_DIR"/*; do
    if [ -d "$skill_dir" ] && [ -f "$skill_dir/SKILL.md" ]; then
        skill_name=$(basename "$skill_dir")
        echo ""
        echo "=== Validating: $skill_name ==="

        # Run quick validation
        if [ -f "$SKILL_CREATOR_VALIDATOR" ]; then
            python3 "$SKILL_CREATOR_VALIDATOR" "$skill_dir"
        else
            echo "⚠️  Skill creator validator not found, skipping automated validation"
        fi

        # Check for TODOs
        if grep -q "TODO" "$skill_dir/SKILL.md"; then
            echo "⚠️  Warning: Found TODOs in SKILL.md"
        fi

        # Count files
        file_count=$(find "$skill_dir" -type f | wc -l)
        echo "📁 Files: $file_count"
    fi
done

echo ""
echo "✅ Validation complete!"

Usage:

bash validate_all_skills.sh

Quality Assurance Checklist

Use this checklist after unmixing:

General Extraction Quality

• [ ] File count matches expected count
• [ ] Directory structure matches repomix directory listing
• [ ] No extraction errors in console output
• [ ] All files are UTF-8 encoded and readable
• [ ] No binary files incorrectly extracted as text

Skill Quality (if applicable)

• [ ] Each skill has a valid SKILL.md
• [ ] YAML frontmatter is well-formed
• [ ] Description includes activation triggers
• [ ] Writing style is imperative/infinitive
• [ ] Resources are properly organized (scripts/, references/, assets/)
• [ ] No TODOs or placeholder text
• [ ] Scripts have proper shebangs and permissions
• [ ] References are informative markdown
• [ ] skill-creator validation passes

Content Integrity

• [ ] Random spot-checks show correct content
• [ ] Code examples are properly formatted
• [ ] No XML/JSON escape artifacts
• [ ] File sizes are reasonable
• [ ] No truncated files

Ready for Use

• [ ] Extracted to appropriate location
• [ ] Scripts made executable (if needed)
• [ ] Skills ready for installation to ~/.claude/skills/
• [ ] Documentation reviewed and understood

Common Issues and Solutions

Issue: File Count Mismatch

Symptom: Fewer files extracted than expected.

Possible causes:

• Binary files excluded (expected)
• Malformed file blocks in repomix file
• Wrong format detection

Solution: 1. Check repomix <file_summary> section for exclusion notes 2. Manually inspect repomix file for file blocks 3. Verify format detection was correct

Issue: Malformed YAML Frontmatter

Symptom: skill-creator validation fails on YAML.

Possible causes:

• Extraction didn't preserve line breaks correctly
• Content had literal --- that broke frontmatter

Solution: 1. Manually inspect SKILL.md frontmatter 2. Ensure opening --- is on line 1 3. Ensure closing --- is on its own line 4. Check for stray --- in description

Issue: Missing Resource Files

Symptom: References to scripts/references not found.

Possible causes:

• Resource files excluded from repomix
• Extraction path mismatch

Solution: 1. Check repomix file for resource file blocks 2. Verify resource was in original packed content 3. Check extraction console output for errors

Issue: Permission Errors on Scripts

Symptom: Scripts not executable.

Possible causes:

• Permissions not preserved during extraction
• Scripts need to be marked executable

Solution:

# Make all scripts executable
find /tmp/extracted -name "*.py" -exec chmod +x {} \;
find /tmp/extracted -name "*.sh" -exec chmod +x {} \;

Issue: Encoding Problems

Symptom: Special characters appear garbled.

Possible causes:

• Repomix file not UTF-8
• Extraction script encoding mismatch

Solution: 1. Verify repomix file encoding: file -i repomix-file.xml 2. Re-extract with explicit UTF-8 encoding 3. Check original files for encoding issues

Post-Validation Actions

For Valid Skills

Install to Claude Code:

# Copy to skills directory
cp -r /tmp/extracted/skill-name ~/.claude/skills/

# Restart Claude Code to load the skill

Package for distribution:

~/.claude/plugins/marketplaces/anthropics-skills/skill-creator/scripts/package_skill.py \
  /tmp/extracted/skill-name

For Invalid Skills

Document issues:

• Create an issues list
• Note specific validation failures
• Identify required fixes

Fix issues:

• Manually edit extracted files
• Re-validate after fixes
• Document changes made

Re-package if needed:

• Once fixed, re-validate
• Package for distribution
• Test in Claude Code

Best Practices

1. Always validate before use - Don't skip validation steps 2. Extract to temp first - Review before installing 3. Use automated tools - skill-creator validation for skills 4. Document findings - Keep notes on any issues 5. Preserve originals - Keep the repomix file as backup 6. Spot-check content - Don't rely solely on automated checks 7. Test in isolation - Install one skill at a time for testing

References

• Skill creator documentation: ~/.claude/plugins/marketplaces/anthropics-skills/skill-creator/SKILL.md
• Skill authoring best practices: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices.md
• Claude Code skills directory: ~/.claude/skills/