Gestión de dependencias de Skills

Los scripts de Skill suelen requerir librerías de terceros. Cómo declarar, instalar y fijar estas dependencias es la base para garantizar el funcionamiento fiable de un Skill.


Archivo de declaración de dependencias

Crear en el directorio scripts/ del Skillrequirements.txt(Python) opackage.json(Node.js) para declarar todas las dependencias de forma centralizada.

Dependencias de 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 请求

Dependencias de Node.js: package.json

Ejemplo

{
  "name": "my-skill-scripts",
  "version": "1.0.0",
  "description": "Dependencias de Node.js para scripts de Skill",
  "dependencies": {
    "xlsx": "^0.18.5",
    "puppeteer": "^21.0.0"
  }
}

Explicar el método de instalación en SKILL.md

## 依赖安装

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

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

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

Instalar dependencias automáticamente en el script

Para Skills que necesitan ejecutarse con configuración cero, se puede añadir lógica de autocomprobación e instalación automática de dependencias al inicio del script.

Ejemplo

# Ruta del archivo: scripts/auto_deps.py
import subprocess
import sys
import importlib

# Definir lista de dependencias: (nombre de instalación pip, nombre de import, requisito de versión)
DEPENDENCIES = [
    ("pandas",         "pandas",    ">=2.0"),
    ("openpyxl",       "openpyxl",  ">=3.0"),
    ("python-docx",    "docx",      None),     # Sin requisito de versión
]

def install_if_missing(pip_name: str, import_name: str) -> bool:
    """Comprobar e instalar los paquetes de dependencias según sea necesario"""
    try:
        importlib.import_module(import_name)
        return True   # Ya está instalado, devolver directamente
    except ImportError:
        print(f"Instalando: {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"Instalación exitosa: {pip_name}")
            return True
        print(f"Fallo en la instalación: {pip_name}"\n{result.stderr}")
        return False

def ensure_all_deps() -> bool:
    """Asegurarse de que todas las dependencias estén instaladas"""
    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"Las siguientes dependencias fallaron al instalarse: {', '.join(failed)}")
        return False
    return True

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

    # Cuando las dependencias estén listas, ejecutar la lógica normalmente
    import pandas as pd
    print("Todas las dependencias están listas, comenzando la ejecución...")
正在安装:python-docx...
安装成功:python-docx
所有依赖已就绪,开始执行...

Estrategias para manejar conflictos de versiones

Cuando la versión de un paquete del que depende un Skill entra en conflicto con la versión ya existente en el sistema, se pueden seguir los siguientes enfoques:

Estrategia Método Escenario aplicable
Requisito de versión flexible Usar >= en lugar de ==, permitir versiones superiores La mayoría de los escenarios, buena compatibilidad
Entorno virtual Instalar en venv, aislado del sistema Requisitos estrictos de versión
Usar la versión ya existente en el sistema No fijar la versión, usar la versión instalada en el sistema La dependencia es una librería común y las diferencias de versión tienen poco impacto

Crear un entorno virtual (opcional)

Ejemplo

# Crear un entorno virtual en el directorio del Skill
python3 -m venv scripts/.venv

# Activar el entorno virtual
source scripts/.venv/bin/activate

# Instalar dependencias en el entorno virtual
pip install -r scripts/requirements.txt

# Ejecutar el script en el entorno virtual
python scripts/process.py

En el entorno de ejecución de Claude, generalmente no se necesita un entorno virtual, porque cada sesión está relativamente aislada. El entorno virtual se utiliza principalmente en la etapa de desarrollo local, para evitar conflictos con otros proyectos en la máquina de desarrollo.


Normas de documentación de dependencias

En SKILL.md o en un README independiente, se deben enumerar claramente todas las dependencias externas, para que los usuarios puedan conocer los requisitos antes de la instalación.

## 系统要求

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

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

### 系统工具(可选)
- pandoc:格式转换(apt-get install pandoc)
Otras extensiones