claude-skill-management
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.
How do I install this agent skill?
npx skills add https://github.com/delphine-l/claude_global --skill claude-skill-managementIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a comprehensive guide for managing Claude Code skills and commands using a centralized repository pattern. It facilitates organization, symlinking, and maintenance through standard shell commands and Git workflows without introducing malicious patterns.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerwarn
1/1 file flagged
What does this agent skill do?
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
~/.zshrcor~/.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
$HOMEnot 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 namedescription(required): Clear, concise description for activationversion(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 commandsgit-workflows/- Git-related commandstesting/- Testing-related commandsdeployment/- 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-productionnot justdeploy
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
--fullflag - 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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/delphine-l/claude_global/claude-skill-management">View claude-skill-management on skillZs</a>