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:

Create directory structure:

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

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

Verify setup:

echo $CLAUDE_METADATA

Should output your claude_data directory path

Create initial documentation:

Create README and QUICK_REFERENCE

(use templates from claude-skill-management skill)

Initialize git (recommended):

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

Create your first skill:

mkdir -p $CLAUDE_METADATA/skills/my-first-skill

Create SKILL.md with frontmatter

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

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:

• Keep description to 1 line (shows in list view)

• Document all parameters clearly

• Provide realistic examples

• Include expected output in steps

• 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