claude-code-skills-reference/repomix-unmixer/references/validation-workflow.md

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/