Skills 依存関係管理

Skill スクリプトは通常、サードパーティのライブラリを必要とします。これらの依存関係を宣言・インストール・ロックする方法は、Skill を確実に実行するための基盤です。


依存関係宣言ファイル

Skill の scripts/ ディレクトリに作成しますrequirements.txt(Python)またはpackage.json(Node.js)を作成し、すべての依存関係を集中的に宣言します。

Python 依存関係:requirements.txt

# 文件路径:scripts/requirements.txt
# 格式:包名==版本号(锁定版本,确保可重复安装)

pandas==2.1.4         # 数据处理
openpyxl==3.1.2       # Excel 读写
pypdf==3.17.0         # PDF 处理
python-docx==1.1.0    # Word 文档处理
requests==2.31.0      # HTTP 请求

Node.js 依存関係:package.json

実例

{
  "name": "my-skill-scripts",
  "version": "1.0.0",
  "description": "Skill スクリプトの Node.js 依存関係",
  "dependencies": {
    "xlsx": "^0.18.5",
    "puppeteer": "^21.0.0"
  }
}

SKILL.md でインストール方法を説明する

## 依赖安装

首次使用前,运行以下命令安装 Python 依赖:

```bash
pip install -r scripts/requirements.txt --break-system-packages
```

若运行环境已预装依赖,可跳过此步骤。

スクリプト内で依存関係を自動インストールする

ゼロ設定で実行する必要がある Skill の場合、スクリプトの先頭に依存関係の自己チェックと自動インストールのロジックを追加できます。

実例

# ファイルパス:scripts/auto_deps.py
import subprocess
import sys
import importlib

# 依存関係リストを定義:(pipインストール名, import名, バージョン要件)
DEPENDENCIES = [
    ("pandas",         "pandas",    ">=2.0"),
    ("openpyxl",       "openpyxl",  ">=3.0"),
    ("python-docx",    "docx",      None),     # バージョン要件なし
]

def install_if_missing(pip_name: str, import_name: str) -> bool:
    """依存パッケージをチェックし、必要に応じてインストールする"""
    try:
        importlib.import_module(import_name)
        return True   # インストール済みのため、そのまま返す
    except ImportError:
        print(f"インストール中:{pip_name}...")
        result = subprocess.run(
            [sys.executable, "-m", "pip", "install", pip_name,
             "--break-system-packages", "--quiet"],
            capture_output=True, text=True
        )
        if result.returncode == 0:
            print(f"インストール成功:{pip_name}")
            return True
        print(f"インストール失敗:{pip_name}\n{result.stderr}")
        return False

def ensure_all_deps() -> bool:
    """すべての依存関係がインストールされていることを確認する"""
    failed = []
    for pip_name, import_name, _ in DEPENDENCIES:
        if not install_if_missing(pip_name, import_name):
            failed.append(pip_name)
    if failed:
        print(f"以下の依存関係のインストールに失敗しました:{', '.join(failed)}")
        return False
    return True

if __name__ == "__main__":
    if not ensure_all_deps():
        sys.exit(1)

    # 依存関係の準備ができたら、通常のロジックを実行
    import pandas as pd
    print("すべての依存関係の準備が整いました。実行を開始します...")
正在安装:python-docx...
安装成功:python-docx
所有依赖已就绪,开始执行...

バージョン競合の処理戦略

Skill が依存するパッケージのバージョンがシステムの既存バージョンと競合する場合、以下のいくつかの処理方法があります:

戦略 方法 適用シーン
緩やかなバージョン要件 >= を使用し、== ではなく、より高いバージョンを許可する ほとんどのシーンで、互換性が良い
仮想環境 venv にインストールし、システムから隔離する バージョンに厳しい要件がある場合
システムの既存バージョンを使用する バージョンをロックせず、システムにインストールされたバージョンを使用する 依存関係が一般的なライブラリで、バージョン差異の影響が小さい場合

仮想環境の作成(任意)

実例

# Skill ディレクトリに仮想環境を作成
python3 -m venv scripts/.venv

# 仮想環境をアクティベート
source scripts/.venv/bin/activate

# 仮想環境に依存関係をインストール
pip install -r scripts/requirements.txt

# 仮想環境でスクリプトを実行
python scripts/process.py

Claude の実行環境では、各セッションが比較的隔離されているため、通常は仮想環境は必要ありません。仮想環境は主にローカル開発段階で使用され、開発マシン上の他のプロジェクトとの競合を避けるために使われます。


依存関係ドキュメントの規範

SKILL.md または別の README に、すべての外部依存関係を明確にリストアップし、ユーザーがインストール前に要件を理解できるようにする必要があります。

## 系统要求

### 运行环境
- Python 3.8 或更高版本
- pip(Python 包管理工具)

### Python 依赖
| 包名 | 版本 | 用途 |
|------|------|------|
| pandas | >=2.0 | 数据读取与处理 |
| openpyxl | >=3.0 | Excel 文件读写 |
| python-docx | 任意 | Word 文档生成 |

### 系统工具(可选)
- pandoc:格式转换(apt-get install pandoc)
その他の拡張