Claude Code Skill Management Expert

Expert knowledge for managing Claude Code skills and commands using the centralized repository pattern with $CLAUDE_METADATA.

When to Use This Skill

• Creating new global skills or commands
• Setting up skills for a new project
• Synchronizing projects with updated global skills
• Organizing the centralized skill repository
• Troubleshooting skill discovery or activation issues
• Understanding the skill lifecycle

Environment Setup

Required Environment Variable

$CLAUDE_METADATA must be set to your centralized skills directory.

Check if set:

echo $CLAUDE_METADATA
# Should output your claude_data directory path

If not set, add to ~/.zshrc (or ~/.bashrc):

export CLAUDE_METADATA="$HOME/path/to/claude_data"  # Adjust to your actual path

Apply immediately:

source ~/.zshrc  # or source ~/.bashrc

Verify Directory Structure

ls -la $CLAUDE_METADATA/
# Should show:
# ├── skills/       # Global skills
# ├── commands/     # Global commands
# ├── README.md
# └── QUICK_REFERENCE.md

Complete Setup from Scratch

If setting up a centralized skill repository for the first time:

1. Create directory structure:

   mkdir -p $CLAUDE_METADATA/{skills,commands}
   cd $CLAUDE_METADATA
   

2. Set environment variable (add to ~/.zshrc or ~/.bashrc):

   echo 'export CLAUDE_METADATA="$HOME/path/to/claude_data"  # Adjust to your actual path' >> ~/.zshrc
   source ~/.zshrc
   

3. Verify setup:

   echo $CLAUDE_METADATA
   # Should output your claude_data directory path
   

4. Create initial documentation:

   # Create README and QUICK_REFERENCE
   # (use templates from claude-skill-management skill)
   

5. Initialize git (recommended):

   cd $CLAUDE_METADATA
   git init
   git add .
   git commit -m "Initial centralized skill repository"
   

6. Create your first skill:

   mkdir -p $CLAUDE_METADATA/skills/my-first-skill
   # Create SKILL.md with frontmatter
   

7. Link to first project:

   cd ~/Workdir/my-project
   mkdir -p .claude/skills
   ln -s $CLAUDE_METADATA/skills/my-first-skill .claude/skills/
   

Environment variable best practices:

• Use $HOME not hardcoded paths for portability
• Source shell config after adding: source ~/.zshrc
• Verify in new terminals: echo $CLAUDE_METADATA
• Document for team members in README.md

---

Creating New Skills

Step 1: Create Skill Directory

mkdir -p $CLAUDE_METADATA/skills/your-skill-name

Naming conventions:

• Use kebab-case (lowercase with hyphens)
• Be descriptive but concise
• Examples: galaxy-tool-wrapping, python-testing, docker-workflows

Step 2: Create SKILL.md with Frontmatter

cat > $CLAUDE_METADATA/skills/your-skill-name/SKILL.md << 'EOF'
---
name: your-skill-name
description: Brief description that helps Claude decide when to activate this skill (1-2 sentences)
---

# Your Skill Name

Detailed instructions for Claude when this skill is activated.

## When to Use This Skill

- Specific use case 1
- Specific use case 2
- Specific use case 3

## Core Concepts

### Concept 1

Explanation and examples...

### Concept 2

Explanation and examples...

## Best Practices

- Practice 1
- Practice 2

## Common Issues and Solutions

### Issue 1

**Problem:** Description
**Solution:** How to fix it

## Examples

### Example 1: Task Name

Description and code examples...
EOF

Frontmatter fields:

• name (required): Must match directory name
• description (required): Clear, concise description for activation
• version (optional): Semantic versioning (e.g., 1.0.0)
• dependencies (optional): Required tools/packages

Step 3: Add Supporting Files (Optional)

# Add detailed reference documentation
cat > $CLAUDE_METADATA/skills/your-skill-name/reference.md << 'EOF'
# Reference Documentation

Detailed technical information, API references, etc.
EOF

# Add examples directory
mkdir -p $CLAUDE_METADATA/skills/your-skill-name/examples

# Add templates directory
mkdir -p $CLAUDE_METADATA/skills/your-skill-name/templates

Step 4: Test the Skill

# Create a test project
mkdir -p /tmp/test-skill-project/.claude/skills

# Symlink the new skill
ln -s $CLAUDE_METADATA/skills/your-skill-name /tmp/test-skill-project/.claude/skills/your-skill-name

# Start Claude Code in test project
cd /tmp/test-skill-project
# Tell Claude: "Use the your-skill-name skill to [test task]"

---

Creating New Commands

Step 1: Choose or Create Category Directory

# Use existing category
ls $CLAUDE_METADATA/commands/
# Or create new category
mkdir -p $CLAUDE_METADATA/commands/your-category

Common categories:

• vgp-pipeline/ - VGP workflow commands
• git-workflows/ - Git-related commands
• testing/ - Testing-related commands
• deployment/ - Deployment commands

Step 2: Create Command File

cat > $CLAUDE_METADATA/commands/your-category/command-name.md << 'EOF'
---
name: command-name
description: Brief description shown in /help
---

Your command prompt here. This will be expanded when the user types /command-name.

You can include:
- Multi-line instructions
- Variable references: {{variable_name}}
- Markdown formatting
- Code blocks

Example:
Check the status of all workflows for species {{species_name}}.
Show me which workflows are complete, running, or failed.
EOF

Naming conventions:

• Use kebab-case
• Start with verb: check-status, debug-failed, update-skills
• Be specific: deploy-production not just deploy

Step 3: Test the Command

# Symlink to test project
ln -s $CLAUDE_METADATA/commands/your-category/command-name.md /tmp/test-project/.claude/commands/

# Start Claude Code and test
# Type: /command-name

---

Symlinking Skills and Commands to Projects

Recommended Global Skills (Always Symlink These)

Every new project should include these globally useful skills:

1. token-efficiency (Essential)

Why: Automatically optimizes Claude's token usage, saving 80-90% on typical operations

ln -s $CLAUDE_METADATA/skills/token-efficiency .claude/skills/token-efficiency

Benefits:

• Uses --quiet mode for commands automatically
• Reads log files efficiently (tail/grep instead of full read)
• Strategic file selection for learning mode
• Extends your Claude Pro usage 5-10x

2. claude-collaboration (Highly Recommended)

Why: Teaches best practices for managing skills and team collaboration

ln -s $CLAUDE_METADATA/skills/claude-collaboration .claude/skills/claude-collaboration

Benefits:

• Explains when and how to update skills
• Documents skill lifecycle and version control
• Helps onboard team members
• Ensures consistency across projects

3. galaxy-automation (For Galaxy projects)

Why: Universal BioBlend and Planemo knowledge for any Galaxy automation project

ln -s $CLAUDE_METADATA/skills/galaxy-automation .claude/skills/galaxy-automation

Benefits:

• Foundation for Galaxy workflow automation
• Required dependency for vgp-pipeline
• Useful for galaxy-tool-wrapping (Planemo testing)
• Reduces duplication across Galaxy-related skills

4. Recommended Global Commands (Highly Recommended)

Useful for managing skills across all projects:

mkdir -p .claude/commands
# Symlink ALL global commands (always include)
ln -s $CLAUDE_METADATA/commands/global/*.md .claude/commands/

Available commands:

• /update-skills - Review session and suggest skill updates
• /list-skills - Show all available skills in $CLAUDE_METADATA
• /setup-project - Set up a new project with intelligent defaults
• /sync-skills - Check for new skills/commands added to $CLAUDE_METADATA
• /cleanup-project - End-of-project cleanup (working docs, verbose READMEs)

Quick Setup for Both Skills and Commands

# Navigate to your new project
cd ~/Workdir/your-new-project/

# Create .claude directories
mkdir -p .claude/skills .claude/commands

# Symlink essential global skills
ln -s $CLAUDE_METADATA/skills/token-efficiency .claude/skills/token-efficiency
ln -s $CLAUDE_METADATA/skills/claude-collaboration .claude/skills/claude-collaboration
ln -s $CLAUDE_METADATA/skills/python-environment-management .claude/skills/python-environment-management

# Symlink ALL global commands (always include)
ln -s $CLAUDE_METADATA/commands/global/*.md .claude/commands/

# Add project-specific skills as needed
# For Galaxy projects:
# ln -s $CLAUDE_METADATA/skills/galaxy-automation .claude/skills/galaxy-automation



# Verify
ls -la .claude/skills/
ls -la .claude/commands/

Or ask Claude:

Set up this new project with Claude Code. Symlink the essential global skills
(token-efficiency, claude-collaboration, and python-environment-management) and global commands
from $CLAUDE_METADATA/skills/ and ALL global commands from $CLAUDE_METADATA/commands/global/, then show me
other available skills I might want to add.

Or simply use:

/setup-project

(if the setup-project command is already symlinked)

---

Method 1: Quick Setup (Recommended for New Projects)

Tell Claude:

Set up Claude Code for this project. Show me available skills in $CLAUDE_METADATA and let me choose which ones to symlink.

Claude will:

1. Automatically symlink token-efficiency, claude-collaboration, python-environment-management (if not already present)
2. List all available skills and commands
3. Ask which additional ones you want
4. Create the symlinks
5. Verify everything works

Method 2: Manual Symlink (Specific Skills)

# Navigate to your project
cd ~/Workdir/your-project/

# Create directories if needed
mkdir -p .claude/skills .claude/commands

# Symlink specific skill
ln -s $CLAUDE_METADATA/skills/skill-name .claude/skills/skill-name

# Symlink all commands from a category
ln -s $CLAUDE_METADATA/commands/category/*.md .claude/commands/

# Symlink specific command
ln -s $CLAUDE_METADATA/commands/category/command-name.md .claude/commands/command-name.md

Method 3: Symlink All Skills

# Link every skill (use cautiously)
for skill in $CLAUDE_METADATA/skills/*; do
    ln -s "$skill" .claude/skills/$(basename "$skill")
done

# Link all commands from all categories
for category in $CLAUDE_METADATA/commands/*; do
    ln -s "$category"/*.md .claude/commands/
done

Note: Progressive disclosure means having many skills doesn't hurt performance, but keep projects focused on relevant skills for clarity.

Verify Symlinks

# Check what's linked
ls -la .claude/skills/
ls -la .claude/commands/

# Verify targets exist
ls -L .claude/skills/    # Follows symlinks

---

Updating Existing Skills

When to Update Skills

Update when you discover:

• ✅ Repeated patterns or solutions
• ✅ New best practices
• ✅ Common errors and their fixes
• ✅ Token optimizations
• ✅ Workflow improvements

Don't update for:

• ❌ One-time issues
• ❌ Experimental approaches (wait until proven)
• ❌ User-specific preferences
• ❌ Obvious information

Method 1: Direct Editing

# Edit the skill file
nano $CLAUDE_METADATA/skills/skill-name/SKILL.md

# Or use Claude
# Tell Claude: "Update the skill-name skill to add [new information]"

Method 2: Use /update-skills Command

# If you have the update-skills command linked
/update-skills

# Claude will:
# 1. Review your session
# 2. Suggest skill updates
# 3. Ask for approval
# 4. Apply changes

Method 3: End-of-Session Updates

Tell Claude:

Review today's session and suggest updates to relevant skills in $CLAUDE_METADATA.

Propagation of Updates

Automatic propagation:

# Update skill in central location
vim $CLAUDE_METADATA/skills/vgp-pipeline/SKILL.md

# ALL projects with symlinks immediately see the update! 🎉
# No need to update each project individually

---

Synchronizing Projects with Global Skills

Scenario: Added New Skills to $CLAUDE_METADATA

Tell Claude (in existing project):

Check what skills and commands are available in $CLAUDE_METADATA and compare with what's currently symlinked in this project. Show me what's new or missing, and let me choose which ones to add.

Claude will:

1. List current symlinks
2. List available skills in $CLAUDE_METADATA
3. Show what's new
4. Create symlinks for selected items

Manual Sync

# List available skills
ls $CLAUDE_METADATA/skills/

# List what you have
ls .claude/skills/

# Add missing ones
ln -s $CLAUDE_METADATA/skills/new-skill .claude/skills/new-skill

---

Organizing the Centralized Repository

Directory Organization Best Practices

By domain/technology:

$CLAUDE_METADATA/skills/
├── vgp-pipeline/              # VGP workflows
├── galaxy-tool-wrapping/      # Galaxy development
├── python-testing/            # Python test patterns
├── docker-workflows/          # Docker/containers
└── bioinformatics-common/     # General bioinformatics

By function:

$CLAUDE_METADATA/commands/
├── vgp-pipeline/              # VGP-specific commands
│   ├── check-status.md
│   └── debug-failed.md
├── git-workflows/             # Git commands
│   └── review-commits.md
└── deployment/                # Deployment commands
    └── deploy-production.md

Naming Consistency

Skills:

• Format: domain-subdomain or technology-purpose
• Examples:
  • galaxy-tool-wrapping (technology-purpose)
  • vgp-pipeline (project-type)
  • python-testing (language-purpose)

Commands:

• Format: verb-noun or verb-target
• Examples:
  • check-status (verb-noun)
  • debug-failed (verb-state)
  • update-skills (verb-noun)

Documentation Requirements

Every skill directory should have:

• ✅ SKILL.md (required) - Main skill file
• ✅ Clear frontmatter with name and description
• ✅ "When to Use This Skill" section
• ⚠️ reference.md (optional) - Detailed documentation
• ⚠️ examples/ (optional) - Example code/configs

Every command should have:

• ✅ Frontmatter with name and description
• ✅ Clear prompt/instructions
• ✅ Examples if the command takes parameters

---

Version Control with Git

Initialize Git Repository

cd $CLAUDE_METADATA
git init
git add .
git commit -m "Initial commit: centralized skills and commands"

Track Changes

# After updating skills
cd $CLAUDE_METADATA
git status          # See what changed
git diff            # Review changes

# Commit updates
git add skills/skill-name/SKILL.md
git commit -m "Add troubleshooting section for XYZ issue"

# Optional: Push to remote for team sharing
git push origin main

Team Collaboration

Setup shared repository:

# Create GitHub/GitLab repo
git remote add origin git@github.com:your-team/claude-metadata.git
git push -u origin main

Team members clone:

git clone git@github.com:your-team/claude-metadata.git ~/path/to/claude_data
export CLAUDE_METADATA="$HOME/path/to/claude_data"  # Adjust to your actual path

Pull updates:

cd $CLAUDE_METADATA
git pull  # All projects with symlinks auto-update!

Good Commit Messages

Good:

git commit -m "Add token optimization for VGP log files (96% savings)"
git commit -m "Document WF8 failure pattern when Hi-C R2 missing"
git commit -m "Create galaxy-tool-wrapping skill for tool development"

Bad:

git commit -m "update"
git commit -m "changes"
git commit -m "fix stuff"

---

Troubleshooting

Skill Not Activating

Check 1: Verify symlink exists

ls -la .claude/skills/
# Should show: skill-name -> $CLAUDE_METADATA/skills/skill-name

Check 2: Verify target exists

ls -L .claude/skills/skill-name
# Should show: SKILL.md

Check 3: Check frontmatter

head -10 .claude/skills/skill-name/SKILL.md
# Should have:
# ---
# name: skill-name
# description: ...
# ---

Check 4: Description clarity

• Is the description clear about when to use the skill?
• Does it match your request?
• Try explicitly mentioning: "Use the skill-name skill to..."

Command Not Found

Check 1: Verify symlink

ls -la .claude/commands/command-name.md

Check 2: Restart Claude Code Commands are loaded at session start, so restart if you just added it.

Check 3: Check frontmatter

head -5 .claude/commands/command-name.md
# Should have:
# ---
# name: command-name
# description: ...
# ---

$CLAUDE_METADATA Not Set

Symptom: Symlink commands fail with "No such file or directory"

Fix:

# Check current value
echo $CLAUDE_METADATA

# If empty, add to shell config
echo 'export CLAUDE_METADATA="$HOME/path/to/claude_data"  # Adjust to your actual path' >> ~/.zshrc
source ~/.zshrc

# Verify
echo $CLAUDE_METADATA

Symlink Points to Wrong Location

Symptom: ls -la .claude/skills/skill-name shows wrong path

Fix:

# Remove broken symlink
rm .claude/skills/skill-name

# Recreate with correct path
ln -s $CLAUDE_METADATA/skills/skill-name .claude/skills/skill-name

# Verify
ls -L .claude/skills/skill-name

Changes Not Appearing in Projects

Symptom: Updated skill in $CLAUDE_METADATA but projects don't see changes

Possible causes:

1. Not using symlinks - Projects have copies instead

   # Check if it's a symlink
   ls -la .claude/skills/skill-name
   # Should show -> pointing to $CLAUDE_METADATA
   

2. Claude Code hasn't restarted - Skills loaded at session start

   • Fix: Restart Claude Code session

3. Editing wrong file - Multiple copies exist

   # Find all copies
   find ~/Workdir -name "SKILL.md" -path "*/skill-name/*"
   # Should only show one in $CLAUDE_METADATA
   

---

Best Practices

1. Keep Skills Focused

Good: One skill per domain

• galaxy-tool-wrapping/SKILL.md - Only Galaxy tools
• vgp-pipeline/SKILL.md - Only VGP workflows

Bad: Kitchen sink skill

• everything/SKILL.md - Galaxy + VGP + Docker + Python + ...

2. Use Clear, Specific Descriptions

Good descriptions:

description: Expert in Galaxy tool wrapper development, XML schemas, and Planemo testing
description: VGP genome assembly pipeline orchestration, debugging, and workflow management

Bad descriptions:

description: Helps with stuff
description: Development skill

3. Regular Maintenance

Weekly:

• Review session learnings
• Update skills with new patterns
• Commit changes with clear messages

Monthly:

• Audit all skills for conflicts
• Remove outdated information
• Reorganize if needed

4. Document Rationale

Include "why" not just "what":

## Use --quiet Mode for Status Checks

**Why:** Status checks with verbose output produce 15K tokens, but only 2K
with --quiet mode. Over a typical workflow (10 checks), this saves 130K tokens
(87% reduction).

**When to override:** User explicitly requests detailed output, or debugging
requires full logs.

5. Version Control Everything

# Always use git
cd $CLAUDE_METADATA
git add .
git commit -m "Descriptive message"

# Never work without version control
# You'll want to undo changes eventually!

6. Share with Team

# Use git for team collaboration
git push origin main

# Team members stay updated
cd $CLAUDE_METADATA && git pull

7. Symlink, Don't Copy

Good:

ln -s $CLAUDE_METADATA/skills/my-skill .claude/skills/my-skill

Bad:

cp -r $CLAUDE_METADATA/skills/my-skill .claude/skills/my-skill

Why: Symlinks mean updates propagate automatically. Copies create maintenance nightmares.

8. Template-Based Script Generation

When creating reusable installers or scripts that need customization across repositories:

Use placeholders in templates:

# Template with placeholders
TEMPLATE='
MAIN_FILE="__MAIN_FILE__"
BACKUP_DIR="__BACKUP_BASE_DIR__"
DAYS="__DAYS_TO_KEEP__"
'

# Substitute with actual values
echo "$TEMPLATE" | \
  sed "s|__MAIN_FILE__|$ACTUAL_FILE|g" | \
  sed "s|__BACKUP_BASE_DIR__|$ACTUAL_DIR|g" | \
  sed "s|__DAYS_TO_KEEP__|$ACTUAL_DAYS|g" \
  > final_script.sh

Benefits:

• Reusable across projects
• Single source of truth for logic
• Easy to maintain and update
• Parameter validation in one place
• Reduces duplication

Example use case: Creating a global installer for backup systems that can be customized for any data file and directory structure. The template contains all the logic, and sed substitution customizes it for each project.

Alternative: Template files:

# Store template in file
cat > template.sh << 'EOF'
MAIN_FILE="__MAIN_FILE__"
BACKUP_DIR="__BACKUP_BASE_DIR__"
EOF

# Generate from template
sed "s|__MAIN_FILE__|data.csv|g" template.sh > backup.sh

---

Quick Reference

Create New Skill

mkdir -p $CLAUDE_METADATA/skills/skill-name
cat > $CLAUDE_METADATA/skills/skill-name/SKILL.md << 'EOF'
---
name: skill-name
description: Brief description
---
# Content here
EOF

Link to Project

ln -s $CLAUDE_METADATA/skills/skill-name .claude/skills/skill-name

Update Skill

# Edit directly
vim $CLAUDE_METADATA/skills/skill-name/SKILL.md

# Or tell Claude
"Update the skill-name skill to add [information]"

Sync Project

# Tell Claude
"Check what skills are available in $CLAUDE_METADATA and show me what's new"

List Available Skills

ls $CLAUDE_METADATA/skills/

List Available Commands

ls $CLAUDE_METADATA/commands/*/

Verify Setup

echo $CLAUDE_METADATA
ls -la .claude/skills/
ls -la .claude/commands/

Setup New Project with Essential Skills and Commands

# Quick setup for new project
cd ~/Workdir/new-project
mkdir -p .claude/skills .claude/commands

# Always symlink these essential skills
ln -s $CLAUDE_METADATA/skills/token-efficiency .claude/skills/token-efficiency
ln -s $CLAUDE_METADATA/skills/claude-collaboration .claude/skills/claude-collaboration

# Always symlink these useful commands
ln -s $CLAUDE_METADATA/commands/global/*.md .claude/commands/

# Verify
ls -la .claude/skills/
ls -la .claude/commands/

---

Common Workflows

Workflow 1: Creating and Using a New Skill

1. Create skill:

   mkdir -p $CLAUDE_METADATA/skills/docker-workflows
   # Create SKILL.md with frontmatter
   

2. Test in isolated project:

   mkdir -p /tmp/test/.claude/skills
   ln -s $CLAUDE_METADATA/skills/docker-workflows /tmp/test/.claude/skills/
   # Start Claude Code, test the skill
   

3. Link to real projects:

   cd ~/Workdir/real-project
   ln -s $CLAUDE_METADATA/skills/docker-workflows .claude/skills/
   

4. Share with team:

   cd $CLAUDE_METADATA
   git add skills/docker-workflows/
   git commit -m "Add docker-workflows skill"
   git push
   

Workflow 2: Updating Skill After Learning

1. Work with Claude, discover pattern
2. Tell Claude: "Add this pattern to the vgp-pipeline skill"
3. Claude updates: $CLAUDE_METADATA/skills/vgp-pipeline/SKILL.md
4. Review changes: git diff
5. Commit: git commit -m "Add WF8 troubleshooting pattern"
6. Push: git push (if using team repo)
7. All projects auto-updated via symlinks! 🎉

Workflow 3: Setting Up New Project

1. Create .claude directory:

   cd ~/Workdir/new-project
   mkdir -p .claude/skills .claude/commands
   

2. Symlink essential global skills:

   # Always include these
   ln -s $CLAUDE_METADATA/skills/token-efficiency .claude/skills/token-efficiency
   ln -s $CLAUDE_METADATA/skills/claude-collaboration .claude/skills/claude-collaboration
   ln -s $CLAUDE_METADATA/skills/python-environment-management .claude/skills/python-environment-management
   

3. Symlink ALL global commands:

   # Always include for all projects
   ln -s $CLAUDE_METADATA/commands/global/*.md .claude/commands/
   

4. Add project-specific skills (if needed):

   # For Galaxy projects:
   ln -s $CLAUDE_METADATA/skills/galaxy-automation .claude/skills/galaxy-automation
   

5. Tell Claude (or use /setup-project if already linked):

   I've set up the essential skills and commands. Show me other available skills in
   $CLAUDE_METADATA that might be relevant for [describe your project type].
   

   Or simply:

   /list-skills
   

6. Claude shows list, you choose project-specific skills

7. Claude creates additional symlinks

8. Commit symlinks to project:

   git add .claude/
   git commit -m "Add Claude Code configuration
   
   Essential global skills and commands:
   - token-efficiency (token optimization)
   - claude-collaboration (team best practices)
   - galaxy-automation (BioBlend & Planemo)
   - Global commands: /update-skills, /list-skills, /setup-project
   
   [Additional project-specific skills if added]"
   

9. Team members get symlinks via git pull

10. Team members point to their $CLAUDE_METADATA

    • They need to set $CLAUDE_METADATA in their shell config
    • Symlinks work automatically once environment variable is set

Pro tip: Use /update-skills at the end of productive sessions to capture new learnings!

---

Repository Maintenance

Periodic Cleanup to Remove Redundancies

As your skill repository grows, redundancies can accumulate from:

• Legacy files after reorganizations
• Duplicate documentation in different locations
• Outdated quick-start guides
• Superseded command files

Cleanup workflow:

1. Identify redundancies:

   # List all markdown files
   find $CLAUDE_METADATA -name "*.md" -type f | sort
   
   # Compare similar files
   diff file1.md file2.md
   
   # Search for overlapping content
   grep -r "specific topic" $CLAUDE_METADATA
   

2. Categorize files:

   • Skills (must be unique, in skills/*/SKILL.md)
   • Supporting docs (should be in skill subdirectories)
   • Commands (one version only, in commands/category/)
   • Root docs (only README.md, QUICK_REFERENCE.md)

3. Always backup before cleanup:

   cd $CLAUDE_METADATA
   mkdir -p .backup-$(date +%Y%m%d-%H%M%S)
   cp -r files-to-modify .backup-$(date +%Y%m%d-%H%M%S)/
   

4. Consolidation patterns:

   • Standalone docs → Move to skills/skill-name/reference.md
   • Legacy commands → Remove if superseded by new versions
   • Duplicate guides → Consolidate into single skill
   • Quick reference prompts → Replace with standardized QUICK_REFERENCE.md

5. Update skill to reference supporting docs:

   ## Supporting Documentation
   
   This skill includes detailed reference documentation:
   - **reference.md** - Comprehensive guide
   - **troubleshooting.md** - Common issues and solutions
   

6. Verify structure:

   tree -L 3 $CLAUDE_METADATA
   # Should show clean, logical organization
   

Benefits of regular cleanup:

• Reduces confusion about which file to use
• Improves discoverability via progressive disclosure
• Easier maintenance (single source of truth)
• Faster skill loading (no duplicate content)

---

Summary

Key Principles:

1. Central repository - All skills in $CLAUDE_METADATA
2. Symlinks, not copies - Updates propagate automatically
3. Version control - Track changes with git
4. Essential global skills first - Always symlink token-efficiency, claude-collaboration, and python-environment-management
5. Selective activation - Link only relevant skills per project
6. Team collaboration - Share via git, everyone benefits

Every new project should start with:

# Essential global skills (always)
ln -s $CLAUDE_METADATA/skills/token-efficiency .claude/skills/token-efficiency
ln -s $CLAUDE_METADATA/skills/claude-collaboration .claude/skills/claude-collaboration
ln -s $CLAUDE_METADATA/skills/python-environment-management .claude/skills/python-environment-management

# ALL global commands (always include for management)
ln -s $CLAUDE_METADATA/commands/global/*.md .claude/commands/

# Project-specific skills (add as needed)
# For Galaxy projects:
# ln -s $CLAUDE_METADATA/skills/galaxy-automation .claude/skills/galaxy-automation

Available global commands:

• /update-skills - Capture learnings from current session
• /list-skills - Show all available skills
• /setup-project - Set up a new project intelligently
• /sync-skills - Check for new skills/commands to symlink
• /cleanup-project - End-of-project cleanup (removes working docs, condenses READMEs)

Remember: The centralized pattern makes skills:

• ✅ Maintainable (update once, apply everywhere)
• ✅ Shareable (team uses same knowledge)
• ✅ Versionable (track evolution with git)
• ✅ Scalable (works for 1 or 100 projects)
• ✅ Efficient (progressive disclosure = no token waste)

With token-efficiency skill active:

• 80-90% token savings on typical operations
• 5-10x more interactions from your Claude Pro subscription
• Strategic file reading for learning and debugging