skills-consolidator

What this skill does

# 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
```markdown
# 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
```python
# 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:
- Skil