claude-skill-management

Claude Code 技能管理专家

利用 $CLAUDE_METADATA，通过集中式仓库模式管理 Claude Code 技能和命令的专业知识。

支持文档

为便于维护，此技能拆分为多个文件。请根据需要阅读：

• symlinking-guide.md - 将技能/命令链接到项目、推荐的全局技能、设置方法
• updating-and-syncing.md - 更新现有技能、将项目与全局更改同步
• repository-organization.md - 目录布局、命名约定、文档要求
• version-control.md - Git 工作流、团队协作、Claude 的 Git 限制
• troubleshooting.md - 符号链接失效、激活问题、常见修复方法
• best-practices.md - 专注的技能、维护频率、模板
• quick-reference.md - 速查命令、常见工作流、仓库维护、摘要

何时使用此技能

• 创建新的全局技能或命令
• 为新项目设置技能
• 将项目与更新后的全局技能同步
• 整理集中式技能仓库
• 排查技能发现或激活问题
• 了解技能生命周期

环境设置

必需的环境变量

$CLAUDE_METADATA 必须设置为你的集中式技能目录。

检查是否已设置：

echo $CLAUDE_METADATA
# Should output your claude_data directory path

如果未设置，请添加到 ~/.zshrc（或 ~/.bashrc）：

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

立即应用：

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

验证目录结构

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

从头开始完成设置

如果你是首次设置集中式技能仓库：

1. 创建目录结构：

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

2. 设置环境变量（添加到 ~/.zshrc 或 ~/.bashrc）：

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

3. 验证设置：

   echo $CLAUDE_METADATA
   # Should output your claude_data directory path
   

4. 创建初始文档：

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

5. 初始化 git（推荐）：

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

6. 创建你的第一个技能：

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

7. 链接到第一个项目：

   cd ~/Workdir/my-project
   mkdir -p .claude/skills
   ln -s $CLAUDE_METADATA/skills/my-first-skill .claude/skills/
   

环境变量最佳实践：

• 使用 $HOME，不要使用硬编码路径，以提高可移植性
• 添加后加载 shell 配置：source ~/.zshrc
• 在新终端中验证：echo $CLAUDE_METADATA
• 在 README.md 中为团队成员记录相关说明

---

创建新技能

步骤 1：创建技能目录

mkdir -p $CLAUDE_METADATA/skills/your-skill-name

命名约定：

• 使用 kebab-case（小写字母，以连字符分隔）
• 描述清晰、简洁
• 示例：galaxy-tool-wrapping、python-testing、docker-workflows

步骤 2：创建带 Frontmatter 的 SKILL.md

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 字段：

• name（必需）：必须与目录名称一致
• description（必需）：清晰、简洁的激活说明
• version（可选）：语义化版本号（例如，1.0.0）
• dependencies（可选）：所需工具/软件包

步骤 3：添加支持文件（可选）

# 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

步骤 4：测试技能

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

---

创建新命令

重要： 命令必须始终先在全局仓库（$CLAUDE_METADATA/commands/）中创建，然后再通过符号链接关联到需要它们的各个项目。切勿直接在项目的 .claude/commands/ 目录中创建命令，否则其他项目将无法看到这些命令，并且会绕过集中管理模式。

重要（技能）： 技能也适用相同规则。必须始终先在 $CLAUDE_METADATA/skills/<domain>/<skill-name>/ 中创建技能，然后通过 ln -s 符号链接关联到需要它们的各个项目。切勿直接在项目的 .claude/skills/ 目录中创建技能，否则其他项目将无法看到这些技能，会导致它们无法在多个 git worktree 中使用，并绕过集中式版本控制。位于 $CLAUDE_METADATA/hooks/safety/protect-global-claude-resources.sh 的钩子会对此进行强制检查，涵盖技能、命令和钩子脚本（它会阻止对任何 **/.claude/skills/、**/.claude/commands/ 或 **/.claude/hooks/ 下的路径执行 Write/Edit，前提是该路径解析后不在 $CLAUDE_METADATA 下）。

步骤 1：选择或创建类别目录

# Use existing category
ls $CLAUDE_METADATA/commands/
# Or create new category
mkdir -p $CLAUDE_METADATA/commands/your-category

常见类别：

• vgp-pipeline/ - VGP 工作流命令
• git-workflows/ - Git 相关命令
• testing/ - 测试相关命令
• deployment/ - 部署命令

步骤 2：创建命令文件

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

命名约定：

• 使用 kebab-case
• 以动词开头：check-status、debug-failed、update-skills
• 名称应具体明确：使用 deploy-production，而不是笼统的 deploy

步骤 3：测试命令

# 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 查看 Claude Code 命令的文档（类似传统 CLI 工具中的 --help）：

# 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

命令帮助实现

位置：$CLAUDE_METADATA/commands/global/command-help.md

功能：

• 列出全局和项目命令及其说明
• 显示用法、参数和示例
• 使用 --full 标志显示完整的实现步骤
• 在全局和项目命令目录中搜索

命令 Frontmatter 格式

命令应包含供帮助系统使用的 frontmatter：

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

创建启用帮助的命令

新命令模板：

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

命令文档最佳实践：

1. 将说明控制在 1 行（在列表视图中显示）
2. 清楚地记录所有参数
3. 提供切实可行的示例
4. 在步骤中注明预期输出
5. 说明任何先决条件或依赖项

---

如需更多详细信息，请参阅本文档顶部列出的支持文件：

• 符号链接和项目设置：symlinking-guide.md
• 更新和同步：updating-and-syncing.md
• 仓库组织：repository-organization.md
• 版本控制和 git：version-control.md
• 故障排查：troubleshooting.md
• 最佳实践：best-practices.md
• 快速参考和工作流：quick-reference.md