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 を使用する
• 追加後にシェル設定を読み込む：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：フロントマター付きの 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

フロントマターのフィールド：

• 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_METADATA 配下でない **/.claude/skills/、**/.claude/commands/、**/.claude/hooks/ 配下のパスに対する Write／Edit をブロックします）。

ステップ 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 だけではなく deploy-production

ステップ 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 フラグを指定すると、実装手順全体を表示できます
• グローバルおよびプロジェクトの両方のコマンドディレクトリを検索します

コマンドのフロントマター形式

コマンドには、ヘルプシステムで使うフロントマターを含めてください。

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