Skills Consolidator

Expert skill for merging, organizing, and maintaining large collections of Claude Code skills with intelligent conflict resolution and structure optimization.

Purpose

Consolidate skills from multiple sources into a well-organized, conflict-free collection. Handles directory flattening, naming conflicts, metadata preservation, documentation generation, and repository maintenance.

When to Use

• Merging skills from multiple repositories
• Organizing chaotic skill collections
• Preparing skills for distribution
• Maintaining a curated skills library
• Resolving naming conflicts across sources

Capabilities

1. Collection Management

#### Directory Flattening

• Extract skills from nested structures
• Preserve skill integrity
• Maintain internal file relationships
• Handle multiple source patterns:
• repo/.claude/skills/skill-name/
• repo/skills/skill-name/
• repo/category/skill-name/

#### Naming Strategy

• Add source suffixes to prevent conflicts
• Normalize naming conventions
• Handle special characters
• Preserve semantic meaning

#### Structure Validation

• Verify SKILL.md presence
• Check for required files
• Validate skill completeness
• Report structural issues

2. Conflict Resolution

#### Naming Conflicts

Conflict: Two skills named "code-review"
Source 1: obra/superpowers
Source 2: mrgoonie/claudekit-skills

Resolution:
- code-review_obra
- code-review_mrgoonie

Keep both for user choice.

#### Content Conflicts

• Detect identical skills from different sources
• Use duplicate detector to identify
• Keep most comprehensive version
• Archive alternatives

#### Metadata Conflicts

• Merge compatible metadata
• Preserve all source attributions
• Combine feature lists
• Aggregate documentation

3. Organization Strategies

#### By Source (Default)

/skills/
├── skill-name_obra/
├── skill-name_mrgoonie/
├── another-skill_diet103/
└── ...

#### By Category

/skills/
├── development/
│   ├── debugging/
│   ├── testing/
│   └── code-review/
├── infrastructure/
│   ├── docker/
│   └── kubernetes/
└── scientific/
    ├── databases/
    └── analysis/

#### Hybrid Approach

/skills/
├── core/              # Essential, curated skills
├── specialized/       # Domain-specific skills
├── experimental/      # New or untested skills
└── archived/          # Deprecated or superseded

4. Documentation Generation

#### Collection README

• Inventory of all skills
• Source attribution
• Installation instructions
• Usage examples
• License information

#### Category Indices

• Skills grouped by purpose
• Quick reference guides
• Search-optimized metadata
• Cross-references

#### Attribution Files

• License compliance
• Author credits
• Source repository links
• Contribution guidelines

Usage Instructions

Basic Consolidation

Use the skills-consolidator skill to:
1. Analyze all skills in /skills directory
2. Flatten any nested structures
3. Resolve naming conflicts with source suffixes
4. Generate comprehensive documentation

Advanced Organization

Use the skills-consolidator skill to reorganize skills by category:
- Development tools → /skills/development/
- Scientific computing → /skills/scientific/
- Infrastructure → /skills/infrastructure/
- General purpose → /skills/general/

Maintain source attributions and generate category README files.

Merge New Repository

Use the skills-consolidator skill to merge skills from new-repo into existing collection:
1. Extract skills from new-repo
2. Check for conflicts with existing skills
3. Add source suffix: _new-repo
4. Update main documentation
5. Generate merge report

Consolidation Workflow

Phase 1: Discovery & Analysis

1. Scan source directories
2. Identify all skills
3. Validate structure
4. Detect conflicts
5. Generate analysis report

Phase 2: Organization

1. Create target structure
2. Flatten nested directories
3. Apply naming strategy
4. Resolve conflicts
5. Preserve metadata

Phase 3: Validation

1. Verify all skills moved correctly
2. Check SKILL.md integrity
3. Validate file permissions
4. Test skill references
5. Confirm completeness

Phase 4: Documentation

1. Generate main README
2. Create category indices
3. Build attribution files
4. Update changelogs
5. Create search indices

Phase 5: Cleanup

1. Remove empty directories
2. Delete temporary files
3. Archive old structures
4. Optimize file organization
5. Commit changes

Naming Conflict Resolution

Strategy 1: Source Suffixes (Recommended)

code-review (from obra) → code-review_obra
code-review (from mrgoonie) → code-review_mrgoonie

Pros: Clear source attribution, no loss of skills Cons: Longer names, requires user choice

Strategy 2: Version Hierarchy

code-review (keep most comprehensive)
code-review-v1 (alternative version)
code-review-minimal (lightweight version)

Pros: Clear versioning, guided choice Cons: Subjective quality assessment

Strategy 3: Merge Strategy

code-review (merged best features from all sources)
├── from obra: requesting workflow
├── from mrgoonie: receiving workflow
└── from diet103: automation tools

Pros: Best-of-breed combination Cons: Requires manual integration work

Strategy 4: Namespace Prefixing

obra/code-review
mrgoonie/code-review
diet103/skill-developer

Pros: Mimics repository structure Cons: Incompatible with flat skill loading in some systems

Quality Assurance

Pre-Consolidation Checks

• ✅ All source repositories cloned successfully
• ✅ Skills contain required SKILL.md files
• ✅ No malformed directory structures
• ✅ Licenses are compatible
• ✅ No binary files or secrets included

Post-Consolidation Checks

• ✅ All skills extracted and flattened
• ✅ No naming conflicts remain unresolved
• ✅ Documentation is complete and accurate
• ✅ Attribution preserved for all sources
• ✅ Directory structure is optimized
• ✅ No broken internal references

Validation Reports

# Consolidation Validation Report

## Statistics
- Skills processed: 161
- Skills successfully consolidated: 154
- Duplicates identified: 7
- Naming conflicts resolved: 0
- Documentation files generated: 5

## Issues Found
- None

## Recommendations
- Consider categorizing skills by domain
- Update main repository README
- Add search functionality
- Create getting-started guide

Integration Points

Input Sources

• GitHub repositories (via bulk-github-skills-downloader)
• Local skill directories
• Exported skill collections
• Individual skill files

Output Formats

• Flat directory structure (Claude Code compatible)
• Categorized hierarchy (browsing-friendly)
• Archived/compressed collections (distribution)
• Documentation websites (Jekyll/Hugo compatible)

Tool Integration

• bulk-github-skills-downloader: Provides raw skills
• skills-duplicate-detector: Identifies redundancy
• git-workflow-helper: Commits organized collection
• github-auth: Pushes to remote repository

Advanced Features

Incremental Updates

Track previously consolidated skills:
- Skip unchanged skills
- Update modified skills only
- Add new skills automatically
- Remove deprecated skills

Smart Categorization

# Analyze skill purpose and auto-categorize
categories = {
    'development': ['debug', 'test', 'review', 'refactor'],
    'infrastructure': ['docker', 'kubernetes', 'deploy'],
    'scientific': ['database', 'analysis', 'research'],
    'documentation': ['markdown', 'diagram', 'wiki']
}

for skill in skills:
    category = auto_categorize(skill)
    move_to_category(skill, category)

Dependency Analysis

Analyze skill dependencies:
- Required tools and CLIs
- Python/npm package requirements
- System dependencies
- API key requirements

Generate dependency matrix for collection.

Health Metrics

Calculate collection health:
- Skill completeness score
- Documentation quality
- Last update recency
- Community activity
- Bug/issue count

Configuration Options

Organization Strategy

organization:
  strategy: "source-suffix"  # source-suffix, category, hybrid, namespace
  flat_structure: true
  preserve_sources: true
  merge_duplicates: false

Naming Conventions

naming:
  suffix_separator: "_"      # skill-name_source
  normalize_case: "kebab"    # kebab-case, snake_case, camelCase
  remove_prefixes: ["skill", "claude"]
  max_length: 50

Documentation

documentation:
  generate_readme: true
  generate_categories: true
  generate_attribution: true
  include_statistics: true
  create_search_index: true

Quality Control

quality:
  require_skill_md: true
  validate_structure: true
  check_licenses: true
  scan_for_secrets: false    # Optional security scan
  enforce_naming: true

Output Structure

Consolidated Repository

your_claude_skills/
├── skills/                          # All consolidated skills
│   ├── skill-name_source/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   └── references/
│   └── ...
├── duplicates/                      # Archived duplicates
│   ├── DUPLICATES_LOG.md
│   └── duplicate-skill/
├── docs/                            # Generated documentation
│   ├── INDEX.md                     # Master index
│   ├── by-category.md               # Categorical view
│   ├── by-source.md                 # Source attribution
│   └── statistics.md                # Collection metrics
├── SKILLS_COLLECTION_README.md      # Main documentation
├── ATTRIBUTION.md                   # License compliance
└── CHANGELOG.md                     # Version history

Best Practices

1. Always Preserve Sources: Keep attribution clear
2. Document Decisions: Record why conflicts were resolved a certain way
3. Validate Thoroughly: Check structure before and after
4. Version Control: Commit consolidation as atomic operation
5. Incremental Approach: Consolidate in batches if collection is large
6. User Communication: Explain organization strategy clearly
7. Regular Maintenance: Re-consolidate periodically as collection grows

Performance Optimization

Large Collections (500+ skills)

• Stream processing instead of loading all into memory
• Parallel validation checks
• Incremental documentation updates
• Chunked git commits

Network Efficiency

• Shallow clones for source repositories
• Sparse checkouts when possible
• Cache frequently accessed repositories
• Batch API requests

Error Handling

Common Issues

1. Naming Conflicts: Apply resolution strategy automatically
2. Missing SKILL.md: Create basic template from directory name
3. Broken Links: Update or remove invalid references
4. Permission Errors: Report and skip problematic skills
5. Disk Space: Check available space before consolidation

Recovery

• Create backup before consolidation
• Transaction-like operation (all or nothing)
• Rollback capability if validation fails
• Detailed error logs for troubleshooting

Use Cases

Scenario 1: Building Master Collection

Goal: Create comprehensive Claude skills library
1. Download top 20 skill repositories
2. Consolidate into single collection
3. Remove duplicates
4. Generate searchable documentation
5. Publish to GitHub

Scenario 2: Team Skills Repository

Goal: Curated skills for development team
1. Select relevant skills from master collection
2. Organize by team workflow
3. Add team-specific customizations
4. Integrate with company tools
5. Maintain in private repository

Scenario 3: Distribution Package

Goal: Package skills for easy installation
1. Consolidate selected skills
2. Flatten to Claude-compatible structure
3. Generate installation script
4. Create compressed archive
5. Publish release

Maintenance Schedule

Weekly

• Check for new skills in tracked repositories
• Update modified skills
• Regenerate documentation if needed

Monthly

• Run duplicate detection
• Review categorization
• Update attribution files
• Check for deprecated skills

Quarterly

• Full re-consolidation
• Structure optimization
• Documentation overhaul
• Community feedback integration

Version: 1.0.0 Last Updated: 2025-11-07 Maintained by: @yourusername