Agent Skills: Skills Consolidator

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