claude-skill-management

name	claude-skill-management
description	Expert guide for managing Claude Code global skills and commands. Use when creating new skills, symlinking to projects, updating existing skills, or organizing the centralized skill repository.

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 - Linking skills/commands to projects, recommended global skills, setup methods
• updating-and-syncing.md - Updating existing skills, syncing projects with global changes
• repository-organization.md - Directory layout, naming conventions, documentation requirements
• version-control.md - Git workflows, team collaboration, Claude's git restrictions
• troubleshooting.md - Broken symlinks, activation issues, common fixes
• best-practices.md - Focused skills, maintenance cadence, templates
• 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