Skills Dependency Management

Skill scripts typically require third-party libraries. How to declare, install, and lock these dependencies is the foundation for ensuring reliable Skill operation.

Dependency Declaration Files

Create in the Skill's scripts/ directoryrequirements.txt(Python) orpackage.json(Node.js), to centrally declare all dependencies.

Python Dependencies: 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 Dependencies: package.json

Example

{
  "name": "my-skill-scripts",
  "version": "1.0.0",
  "description": Node.js Dependencies for Skill Scripts,
  "dependencies": {
    "xlsx": "^0.18.5",
    "puppeteer": "^21.0.0"
  }
}

Explain the installation method in SKILL.md

## 依赖安装

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

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

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

Automatically install dependencies in the script

For Skills that need to run with zero configuration, you can add dependency self-check and automatic installation logic at the beginning of the script.

Example

# File path: scripts/auto_deps.py
import subprocess
import sys
import importlib

# Define dependency list: (pip install name, import name, version requirement)
DEPENDENCIES = [
    ("pandas",         "pandas",    ">=2.0"),
    ("openpyxl",       "openpyxl",  ">=3.0"),
    ("python-docx",    "docx",      None),     # No version requirement
]

def install_if_missing(pip_name: str, import_name: str) -> bool:
    """Check and install dependency packages as needed"""
    try:
        importlib.import_module(import_name)
        return True   # Already installed, return directly
    except ImportError:
        print(f"Installing: {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"Installation successful: {pip_name}")
            return True
        print(f"Installation failed: {pip_name}\n{result.stderr}")
        return False

def ensure_all_deps() -> bool:
    """Ensure all dependencies are installed"""
    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"The following dependencies failed to install: {', '.join(failed)}")
        return False
    return True

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

    # After dependencies are ready, execute the logic normally
    import pandas as pd
    print("All dependencies are ready, starting execution...")
正在安装：python-docx...
安装成功：python-docx
所有依赖已就绪，开始执行...

Strategies for Handling Version Conflicts

When the package version required by a Skill conflicts with an existing system version, there are several ways to handle it:

Strategy Approach Applicable Scenario
Lenient Version Requirements Use >= instead of == to allow higher versions Most scenarios, good compatibility
Virtual Environment Install in venv, isolated from the system Strict version requirements
Use the existing system version Don't lock the version; use the system-installed version Dependencies are common libraries and version differences have minimal impact

Create a Virtual Environment (Optional)

Example

# Create a virtual environment in the Skill directory
python3 -m venv scripts/.venv

# Activate the virtual environment
source scripts/.venv/bin/activate

# Install dependencies in the virtual environment
pip install -r scripts/requirements.txt

# Run the script in the virtual environment
python scripts/process.py

In Claude's execution environment, a virtual environment is usually not needed because each session is relatively isolated. Virtual environments are mainly used during local development to avoid conflicts with other projects on the development machine.

Dependency Documentation Standards

In SKILL.md or a separate README, all external dependencies should be clearly listed so users can understand the requirements before installation.

## 系统要求

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

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

### 系统工具（可选）
- pandoc：格式转换（apt-get install pandoc）
Other Extensions