Claude Skill Management

Claude Code Skill Management Expert

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

Supporting Documentation

This skill is split across multiple files for maintainability. Read these as needed:

• [symlinking-guide.md](symlinking-guide.md) - Linking skills/commands to projects, recommended global skills, setup methods
• [updating-and-syncing.md](updating-and-syncing.md) - Updating existing skills, syncing projects with global changes
• [repository-organization.md](repository-organization.md) - Directory layout, naming conventions, documentation requirements
• [version-control.md](version-control.md) - Git workflows, team collaboration, Claude's git restrictions
• [troubleshooting.md](troubleshooting.md) - Broken symlinks, activation issues, common fixes
• [best-practices.md](best-practices.md) - Focused skills, maintenance cadence, templates
• [quick-reference.md](quick-reference.md) - Cheat-sheet commands, common workflows, repository maintenance, summary

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
# ├── hooks/        # Claude Code hooks (symlinked to ~/.claude/hooks/)
# ├── 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

Important: Commands must ALWAYS be created in the global repository ($CLAUDE_METADATA/commands/) first, then symlinked to each project that needs them. Never create commands directly in a project's .claude/commands/ directory — this makes them invisible from other projects and bypasses the centralized management pattern.

Important (skills): The same rule applies to skills. Skills must ALWAYS be created in $CLAUDE_METADATA/skills/<domain>/<skill-name>/ first, then symlinked to each project that needs them via ln -s. Never create skills directly in a project's .claude/skills/ directory — this makes them invisible from other projects, breaks usage across git worktrees, and bypasses centralized version control. A hook at $CLAUDE_METADATA/hooks/safety/protect-global-claude-resources.sh enforces this for skills, commands, and hook scripts (it blocks Write/Edit to any path under **/.claude/skills/, **/.claude/commands/, or **/.claude/hooks/ whose resolved location isn't under $CLAUDE_METADATA).

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

---

Command Help System

Viewing Command Documentation

Use /command-help to view documentation for Claude Code commands (similar to --help in traditional CLI tools):

# List all available commands
/command-help list

# Show specific command help
/command-help share-project

# Show full details including implementation steps
/command-help share-project --full

Command Help Implementation

Location: $CLAUDE_METADATA/commands/global/command-help.md

Features:

• Lists global and project commands with descriptions
• Shows usage, parameters, and examples
• Can display full implementation steps with --full flag
• Searches in both global and project command directories

Command Frontmatter Format

Commands should include frontmatter for the help system:

---
description: Brief one-line description
usage: /command-name [arguments]
parameters: |
  arg1: Description of argument 1
  arg2: Description of argument 2
examples: |
  /command-name example1
  /command-name example2 --option
---

[Command implementation steps...]

Creating Help-Enabled Commands

Template for new commands:

---
name: my-command
description: Brief description of what this command does
usage: /my-command [required-arg] [optional-arg]
parameters: |
  required-arg: Description of required argument
  optional-arg: (Optional) Description of optional argument
examples: |
  /my-command basic-example
  /my-command advanced-example --flag
---

# Command Implementation

Step 1: [First step description]

Step 2: [Second step description]

[Continue with detailed steps...]

Best practices for command documentation: 1. Keep description to 1 line (shows in list view) 2. Document all parameters clearly 3. Provide realistic examples 4. Include expected output in steps 5. Note any prerequisites or dependencies

---

For additional details, see the supporting files listed at the top of this document:

• Symlinking and project setup: symlinking-guide.md
• Updating and syncing: updating-and-syncing.md
• Repository organization: repository-organization.md
• Version control and git: version-control.md
• Troubleshooting: troubleshooting.md
• Best practices: best-practices.md
• Quick reference and workflows: quick-reference.md

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

9. Adopting External Commands from Other Repos

When evaluating skills/commands from other Claude Code users' GitHub repos:

1. Browse the repo tree with gh api "repos/OWNER/REPO/git/trees/main?recursive=1" --jq '.tree[].path' 2. Fetch file contents with gh api "repos/OWNER/REPO/contents/PATH" --jq '.content' | base64 -d 3. Evaluate relevance — skip project-specific items (e.g., Galaxy vitest helpers for a non-Galaxy user) 4. Adapt to local conventions:

• Add proper YAML frontmatter (name, description, allowed-tools)
• Set context: fork on heavy analysis commands
• Adjust OS-specific tools (e.g., pbcopy for macOS)
• Rename for clarity if the original name is too project-specific

5. Cite sources in the README attribution block 6. Do NOT copy verbatim — tailor prompts to your workflow and conventions

10. Hook Development Safety

Never hold file descriptors in background processes

Synchronous hooks must release stdout/stderr before Claude Code considers them "done":

# Any background work MUST detach from parent stdio
( background_work ) </dev/null >/dev/null 2>&1 &

Synchronous UserPromptSubmit hooks need crash protection

These hooks can silently swallow user input if they exit non-zero:

set -uo pipefail  # Avoid -e (errexit)
trap 'echo "{\"continue\": true}"; exit 0' ERR

Keep installed hooks in sync with source

If hooks are copied (not symlinked) from $CLAUDE_METADATA, fixes to the source won't propagate. After fixing a hook:

# Check if installed hook is a copy or symlink
ls -la ~/.claude/hooks/safety/script.sh
# If not a symlink, manually update the installed copy

11. Fix the Artifact, Not Memory

When a slash command or skill produces wrong/incomplete behavior, edit the command/skill file in $CLAUDE_METADATA rather than saving a feedback memory.

Why: Commands and skills are the durable, shared artifact — every project that symlinks them and every model that runs them benefits from the fix. Memory is per-project, point-in-time, and only nudges the current model. Saving memory when the command itself is editable is treating the symptom.

When memory is still right:

• Project-specific facts (env vars, API keys, internal URLs)
• User preferences that don't generalize across users (terse style, naming)
• Context about ongoing work that has no home in any command

When to edit the command/skill instead:

• "Sync-skills missed project-specific commands" → edit sync-skills.md
• "The review checklist is wrong about X" → edit the review skill
• Any rule that would apply equally well in another project

Workflow when caught saving memory unnecessarily: 1. Edit the command/skill to encode the rule 2. Delete the redundant memory file 3. Remove its pointer from MEMORY.md

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

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

6. Claude creates additional symlinks

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

8. Team members get symlinks via git pull

9. 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

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

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.

Hooks Management

Hooks live in $CLAUDE_METADATA/hooks/ and are symlinked to ~/.claude/hooks/:

ln -s $CLAUDE_METADATA/hooks/safety ~/.claude/hooks/safety
ln -s $CLAUDE_METADATA/hooks/peon-ping ~/.claude/hooks/peon-ping

Portability

• In ~/.claude/settings.json, use ~/.claude/hooks/ paths (not /Users/username/...)
• Runtime files (logs, .state.json, .sound.pid) are gitignored
• Hooks .gitignore covers: *.log, *.state.json, .sound.pid, .last_update_check

New Machine Setup

mkdir -p ~/.claude/hooks
ln -s $CLAUDE_METADATA/hooks/safety ~/.claude/hooks/safety
ln -s $CLAUDE_METADATA/hooks/peon-ping ~/.claude/hooks/peon-ping

Verify Symlinks

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

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

Troubleshooting

Broken Symlinks (Renamed or Moved Skills/Commands)

Symptom: Symlink exists but points to non-existent file (renamed or moved in $CLAUDE_METADATA)

Detection:

# Detect broken skill symlinks
for skill in .claude/skills/*; do
  if [ -L "$skill" ] && [ ! -e "$skill" ]; then
    echo "BROKEN: $skill -> $(readlink "$skill")"
  fi
done

# Detect broken command symlinks
for cmd in .claude/commands/*; do
  if [ -L "$cmd" ] && [ ! -e "$cmd" ]; then
    echo "BROKEN: $cmd -> $(readlink "$cmd")"
  fi
done

Common causes:

• Command renamed (e.g., exit.md -> safe-exit.md)
• Skill reorganized in $CLAUDE_METADATA
• Skill deleted from central repository

Fix:

# Remove broken symlink
rm .claude/commands/old-name.md

# Add new symlink
ln -s $CLAUDE_METADATA/commands/global/new-name.md .claude/commands/new-name.md

# Verify
ls -la .claude/commands/ | grep new-name

Prevention: Use /sync-skills regularly to detect and fix broken symlinks automatically

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 (detect broken symlink)

ls -L .claude/skills/skill-name
# Should show: SKILL.md
# If error: broken symlink - target doesn't exist

# Or use this check:
test -e .claude/skills/skill-name && echo "OK" || echo "BROKEN SYMLINK"

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

Hook Troubleshooting

Background Processes in Synchronous Hooks (fd Leak)

Symptom: All user input disappears instantly with no spinner or response. Disabling all hooks ("disableAllHooks": true in settings.json) fixes it.

Root cause: A synchronous hook spawns a background process with ( ... ) &. The child inherits the parent's stdout pipe. Claude Code waits for EOF on that pipe before considering the hook "done." The background child keeps the fd open indefinitely, so Claude Code hangs.

Fix: Redirect all file descriptors in the background subshell:

# BAD — child holds parent's stdout pipe open
(
    while true; do sleep 900; do_work; done
) &

# GOOD — detach child from parent's stdio
(
    while true; do sleep 900; do_work; done
) </dev/null >/dev/null 2>&1 &

Key insight: This affects ALL synchronous hooks that spawn background processes, not just SessionStart. The same pattern in UserPromptSubmit, PreToolUse, or PreCompact hooks would cause identical symptoms.

Silent Input Swallowing from Hook Crashes

Symptom: Same as above — input disappears with no response.

Root cause: A synchronous UserPromptSubmit hook exits non-zero (crash) or returns invalid JSON. Claude Code blocks the prompt.

Fix: Add a safety trap at the top of synchronous UserPromptSubmit hooks:

set -uo pipefail  # NOT -euo — remove -e
trap 'echo "{\"continue\": true}"; exit 0' ERR

This ensures the hook always passes the prompt through, even on unexpected errors.

Binary Search Method for Isolating Broken Hooks

When hooks break Claude Code and you can't identify which one:

1. Set "disableAllHooks": true to confirm hooks are the cause 2. Replace ALL hooks with a minimal passthrough:

   #!/bin/bash
   cat > /dev/null
   echo '{"continue": true}'
   exit 0

3. If that works, restore hooks by event type (SessionStart, UserPromptSubmit, etc.) one at a time 4. Once the broken event type is found, test hooks within that group individually 5. Each test requires a new session (hooks load at startup)

Tip: Create ~/.claude/hooks/safety/test-passthrough.sh as a permanent diagnostic tool.

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

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"

Claude's Role in Git Operations

CRITICAL: NEVER PERFORM GIT OPERATIONS

Claude must NEVER perform ANY git operations (add, commit, push, stash, tag, rebase, merge, etc.) under ANY circumstances.

This rule applies to:

• All changes in $CLAUDE_METADATA/
• ALL project directories
• Even if the user explicitly asks for it
• Even if the user says "yes, commit them"

What Claude MUST do instead: 1. Make the file changes 2. Show what files were changed (summary or git status) 3. STOP - Do NOT add, commit, or push 4. The user will handle git themselves

What Claude CAN do:

• Check git status (git status --porcelain)
• Show uncommitted changes (git diff)
• Suggest git commands (e.g., "You could run: git commit -m '...'")
• NEVER run git add, commit, push, or any other write operation

If user asks for git operations:

User: "commit these changes"
Claude: "I've made the changes to [files]. You can commit them with:
  git add [files]
  git commit -m 'your message'

I don't perform git operations - you have full control over commits."

Rationale: The user wants complete control over:

• What gets committed and when
• Commit messages and structure
• Git history organization
• All git operations without exception