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:

bash

echo $CLAUDE_METADATA
# Should output your claude_data directory path

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

bash

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

Apply immediately:

bash

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

Verify Directory Structure

bash

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:

Create directory structure:

bash

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

Set environment variable (add to

~/.zshrc

~/.bashrc

bash

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

Verify setup:

bash

echo $CLAUDE_METADATA
# Should output your claude_data directory path

Create initial documentation:

bash

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

Initialize git (recommended):

bash

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

Create your first skill:

bash

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

Link to first project:

bash

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

bash

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

bash

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)

bash

# 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

bash

# 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

bash

# 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

bash

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

bash

# 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

bash

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

bash

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

bash

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:

bash

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

bash

# 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:

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

Method 2: Manual Symlink (Specific Skills)

bash

# 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

bash

# 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

bash

# 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

bash

# 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

bash

# 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:

bash

# 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:

List current symlinks
List available skills in
```
$CLAUDE_METADATA
```
Show what's new
Create symlinks for selected items

Manual Sync

bash

# 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

bash

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

Track Changes

bash

# 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:

bash

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

Team members clone:

bash

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:

bash

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

Good Commit Messages

Good:

bash

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:

bash

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

Troubleshooting

Skill Not Activating

Check 1: Verify symlink exists

bash

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

Check 2: Verify target exists

bash

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

Check 3: Check frontmatter

bash

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

bash

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

bash

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:

bash

# 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:

bash

# 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:

Not using symlinks - Projects have copies instead

bash

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

Claude Code hasn't restarted - Skills loaded at session start
- Fix: Restart Claude Code session

Editing wrong file - Multiple copies exist

bash

# 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:

yaml

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

Bad descriptions:

yaml

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":

markdown

## 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

bash

# 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

bash

# Use git for team collaboration
git push origin main

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

7. Symlink, Don't Copy

Good:

bash

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

Bad:

bash

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:

bash

# 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:

bash

# 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

bash

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

bash

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

Update Skill

bash

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

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

Sync Project

bash

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

List Available Skills

bash

ls $CLAUDE_METADATA/skills/

List Available Commands

bash

ls $CLAUDE_METADATA/commands/*/

Verify Setup

bash

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

Setup New Project with Essential Skills and Commands

bash

# 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

Create skill:

bash

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

Test in isolated project:

bash

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

Link to real projects:

bash

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

Share with team:

bash

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

Workflow 2: Updating Skill After Learning

Work with Claude, discover pattern
Tell Claude: "Add this pattern to the vgp-pipeline skill"

Claude updates:

$CLAUDE_METADATA/skills/vgp-pipeline/SKILL.md

Review changes:
```
git diff
```

Commit:

git commit -m "Add WF8 troubleshooting pattern"

Push:
```
git push
```
(if using team repo)
All projects auto-updated via symlinks! 🎉

Workflow 3: Setting Up New Project

Create .claude directory:

bash

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

Symlink essential global skills:

bash

# 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

Symlink ALL global commands:

bash

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

Add project-specific skills (if needed):

bash

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

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

Claude shows list, you choose project-specific skills
Claude creates additional symlinks

Commit symlinks to project:

bash

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]"

Team members get symlinks via git pull
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:

Identify redundancies:

bash

# 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

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)

Always backup before cleanup:

bash

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)/

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

Update skill to reference supporting docs:

markdown

## Supporting Documentation

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

Verify structure:

bash

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:

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

Every new project should start with:

bash

# 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

claude-skill-management

NPX Install

Tags

SKILL.md Content

Claude Code Skill Management Expert

When to Use This Skill

Environment Setup

Required Environment Variable

Verify Directory Structure

Complete Setup from Scratch

Creating New Skills

Step 1: Create Skill Directory

Step 2: Create SKILL.md with Frontmatter

Step 3: Add Supporting Files (Optional)

Step 4: Test the Skill

Creating New Commands

Step 1: Choose or Create Category Directory

Step 2: Create Command File

Step 3: Test the Command

Symlinking Skills and Commands to Projects

Recommended Global Skills (Always Symlink These)

1. token-efficiency (Essential)

2. claude-collaboration (Highly Recommended)

3. galaxy-automation (For Galaxy projects)

4. Recommended Global Commands (Highly Recommended)

Quick Setup for Both Skills and Commands

Method 1: Quick Setup (Recommended for New Projects)

Method 2: Manual Symlink (Specific Skills)

Method 3: Symlink All Skills

Verify Symlinks

Updating Existing Skills

When to Update Skills

Method 1: Direct Editing

Method 2: Use /update-skills Command

Method 3: End-of-Session Updates

Propagation of Updates

Synchronizing Projects with Global Skills

Scenario: Added New Skills to $CLAUDE_METADATA

Manual Sync

Organizing the Centralized Repository

Directory Organization Best Practices

Naming Consistency

Documentation Requirements

Version Control with Git

Initialize Git Repository

Track Changes

Team Collaboration

Good Commit Messages

Troubleshooting

Skill Not Activating

Command Not Found

$CLAUDE_METADATA Not Set

Symlink Points to Wrong Location

Changes Not Appearing in Projects

Best Practices

1. Keep Skills Focused

2. Use Clear, Specific Descriptions

3. Regular Maintenance

4. Document Rationale

5. Version Control Everything

6. Share with Team

7. Symlink, Don't Copy

8. Template-Based Script Generation

Quick Reference

Create New Skill

Link to Project

Update Skill

Sync Project

List Available Skills

List Available Commands

Verify Setup

Setup New Project with Essential Skills and Commands

Common Workflows

Workflow 1: Creating and Using a New Skill

Workflow 2: Updating Skill After Learning

Workflow 3: Setting Up New Project

Repository Maintenance

Periodic Cleanup to Remove Redundancies

Summary