Runtime Dependencies

Add Python and Node.js packages to your Skills using requirements.txt and package.json.

Skills can declare runtime dependencies that are automatically installed when the Skill is loaded into the sandbox environment. This allows your scripts to use external packages without requiring manual installation.

Supported Dependency Files

File	Language	Package Manager
`requirements.txt`	Python	pip
`package.json`	Node.js	npm

Python Dependencies

Using requirements.txt

Create a requirements.txt file in your Skill's root directory:

my-skill/
├── SKILL.md
├── requirements.txt    # Python dependencies
└── scripts/
    └── process.py

Format

List each package on a separate line:

pdfplumber>=0.10.0
pandas>=2.0.0
numpy>=1.24.0
requests>=2.28.0

Version Specifiers

Use standard pip version specifiers:

Specifier	Meaning
`package`	Any version
`package==1.2.3`	Exact version
`package>=1.2.0`	Minimum version
`package>=1.2.0,<2.0.0`	Version range
`package~=1.2.0`	Compatible release

Example

# requirements.txt
pdfplumber>=0.10.0
Pillow>=10.0.0
pandas>=2.0.0
openpyxl>=3.1.0

Using Dependencies in Scripts

Import packages normally in your Python scripts:

#!/usr/bin/env python3
"""Process PDF files using pdfplumber."""

import sys
import pdfplumber
import pandas as pd

def extract_tables(pdf_path):
    """Extract tables from PDF and return as DataFrame."""
    tables = []
    with pdfplumber.open(pdf_path) as pdf:
        for page in pdf.pages:
            page_tables = page.extract_tables()
            for table in page_tables:
                df = pd.DataFrame(table[1:], columns=table[0])
                tables.append(df)
    return tables

if __name__ == "__main__":
    pdf_path = sys.argv[1]
    tables = extract_tables(pdf_path)
    for i, table in enumerate(tables):
        print(f"Table {i + 1}:")
        print(table.to_string())

Node.js Dependencies

Using package.json

Create a package.json file in your Skill's root directory:

my-skill/
├── SKILL.md
├── package.json        # Node.js dependencies
└── scripts/
    └── process.js

Format

Use standard npm package.json format:

{
  "name": "my-skill",
  "version": "1.0.0",
  "dependencies": {
    "pdf-parse": "^1.1.1",
    "sharp": "^0.32.0",
    "axios": "^1.6.0"
  }
}

Example

{
  "name": "document-processor",
  "version": "1.0.0",
  "description": "Process various document formats",
  "dependencies": {
    "pdf-parse": "^1.1.1",
    "mammoth": "^1.6.0",
    "xlsx": "^0.18.5"
  }
}

Using Dependencies in Scripts

Require packages in your JavaScript/TypeScript scripts:

#!/usr/bin/env node
/**
 * Extract text from PDF files.
 */

const fs = require("fs");
const pdf = require("pdf-parse");

async function extractText(pdfPath) {
  const dataBuffer = fs.readFileSync(pdfPath);
  const data = await pdf(dataBuffer);
  return data.text;
}

const pdfPath = process.argv[2];
if (!pdfPath) {
  console.error("Usage: node extract.js <pdf_path>");
  process.exit(1);
}

extractText(pdfPath)
  .then((text) => console.log(text))
  .catch((err) => {
    console.error("Error:", err.message);
    process.exit(1);
  });

Installation Process

When Dependencies Are Installed

Dependencies are installed:

When the Skill is first loaded into a sandbox session
When the Skill's content changes (detected by content hash)

Installation Commands

The sandbox runs:

Python:

pip install --no-input --disable-pip-version-check -r requirements.txt

Node.js:

npm install --omit=dev --no-audit --no-fund

Caching

Installed dependencies are cached per Skill content hash. If your Skill files haven't changed, dependencies won't be reinstalled, saving time on subsequent loads.

Best Practices

Pin Versions

Pin specific versions for reproducibility:

# Good - predictable behavior
pdfplumber==0.10.3
pandas==2.1.4

# Risky - may break unexpectedly
pdfplumber
pandas

Minimize Dependencies

Only include packages you actually use:

# Good - minimal dependencies
pdfplumber>=0.10.0

# Avoid - unnecessary packages
pdfplumber>=0.10.0
numpy>=1.24.0        # Not used
scipy>=1.11.0        # Not used
matplotlib>=3.8.0    # Not used

Use Compatible Versions

Ensure packages are compatible with each other:

# Test locally first
pandas>=2.0.0
numpy>=1.24.0  # pandas 2.x requires numpy 1.24+

Document Dependencies

Reference dependencies in your SKILL.md:

## Dependencies

This skill requires the following Python packages (installed automatically):

- `pdfplumber` - PDF text and table extraction
- `pandas` - Data manipulation

See `requirements.txt` for specific versions.

Combining Python and Node.js

A single Skill can have both requirements.txt and package.json:

my-skill/
├── SKILL.md
├── requirements.txt    # Python deps
├── package.json        # Node.js deps
└── scripts/
    ├── process.py      # Uses Python packages
    └── convert.js      # Uses Node.js packages

Both will be installed when the Skill loads.

Limitations

Unavailable Packages

Some packages may not work in the sandbox environment:

Packages requiring system-level dependencies (e.g., opencv-python needs OpenCV)
Packages with native compilation requirements
Packages requiring GPU access

Installation Timeout

Dependency installation has a 5-minute timeout. If installation exceeds this:

Reduce the number of dependencies
Use pre-compiled wheels where available
Consider bundling pre-installed functionality

No Dev Dependencies

Dev dependencies are not installed:

Python: Only packages in requirements.txt (not dev-requirements.txt)
Node.js: devDependencies in package.json are skipped

Troubleshooting

Package Not Found

ERROR: Could not find a version that satisfies the requirement xyz

Solutions:

Verify the package name is correct
Check if the package is available on PyPI/npm
Specify a valid version range

Version Conflict

ERROR: Cannot install package-a and package-b because they have conflicting dependencies

Solutions:

Adjust version constraints to find compatible versions
Test locally with pip install -r requirements.txt
Consider using alternative packages

Installation Timeout

If dependencies take too long to install:

Remove unused packages
Use lighter alternatives (e.g., pillow-simd instead of pillow)
Pre-process data to avoid heavy packages

Import Errors at Runtime

ModuleNotFoundError: No module named 'xyz'

Solutions:

Ensure package is listed in requirements.txt/package.json
Check spelling and package name
Verify the Skill was uploaded after adding the dependency

Runtime Dependencies

On this page