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"
}
}
"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("所有依赖已就绪，开始执行...")
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
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）