# How to Handle Plugin Dependencies and External Resources in OpenAI Plugins

> Learn to handle plugin dependencies and external resources with OpenAI. Declare runtime packages in package.json or pyproject.toml, bind services in app.json and inject secrets via environment variables for seamless integration.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-16

---

**You handle plugin dependencies and external resources by declaring runtime packages in skill-specific [`package.json`](https://github.com/openai/plugins/blob/main/package.json) or [`pyproject.toml`](https://github.com/openai/plugins/blob/main/pyproject.toml) files, binding external services through [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) manifests, and injecting secrets via environment variables documented in reference markdown.**

The OpenAI plugins repository implements a multi-layered architecture for isolating and managing dependencies across different programming languages and external services. Each plugin combines manifest metadata with skill-specific code packages, requiring precise configuration in files like [`plugins/figma/skills/figma-use/package.json`](https://github.com/openai/plugins/blob/main/plugins/figma/skills/figma-use/package.json) and [`plugins/figma/.app.json`](https://github.com/openai/plugins/blob/main/plugins/figma/.app.json) to ensure reproducible execution. Understanding how to properly handle plugin dependencies and external resources is critical for maintaining secure, portable implementations that run reliably across different environments.

## Understanding the Dependency Architecture

The repository organizes dependency management into three distinct layers that separate plugin identity from runtime requirements.

### Plugin Manifest and App Bindings

At the root level, [`plugins/figma/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/figma/.codex-plugin/plugin.json) declares the plugin's identity and entry points for the Codex system. Adjacent to this, the [`plugins/figma/.app.json`](https://github.com/openai/plugins/blob/main/plugins/figma/.app.json) file contains the critical `apps` mapping that links the plugin to cloud-hosted integrations:

```json
{
  "apps": {
    "zoominfo": {
      "id": "asdk_app_698a340b9230819188ba5a5eea79022d"
    }
  }
}

```

According to the source code, this `id` is **read-only** and tells Codex which remote service to target when a skill triggers an API call. Changing it requires registering a new integration.

### Skill-Level Package Files

Individual skills define their own runtime dependencies through language-specific package files. The skill runner installs only these declared packages, keeping execution isolated from the host environment. For example, [`plugins/figma/skills/figma-use/package.json`](https://github.com/openai/plugins/blob/main/plugins/figma/skills/figma-use/package.json) contains:

```json
{
  "dependencies": {
    "@figma/plugin-typings": "^1.58.0",
    "axios": "^1.7.2"
  },
  "devDependencies": {
    "typescript": "^5.4.5"
  }
}

```

Only the `dependencies` section is installed at execution time; `devDependencies` are ignored to maintain lean containers.

## Declaring Package-Level Dependencies

Different languages follow specific patterns for dependency declaration within the OpenAI plugins framework.

### Managing npm Dependencies

When adding Node.js packages to a skill, modify the local [`package.json`](https://github.com/openai/plugins/blob/main/package.json) within the skill directory:

```bash
cd plugins/figma/skills/figma-use
npm install lodash@4.17.21 --save

```

The resulting [`package.json`](https://github.com/openai/plugins/blob/main/package.json) entry ensures the runner automatically installs `lodash` when the skill executes, without requiring manual `npm install` on the host system.

### Configuring Python Dependencies

For Python skills, the repository prefers [`pyproject.toml`](https://github.com/openai/plugins/blob/main/pyproject.toml) over [`requirements.txt`](https://github.com/openai/plugins/blob/main/requirements.txt) for version pinning and optional extras support. As implemented in [`plugins/temporal/skills/temporal-developer/references/python/pyproject.toml`](https://github.com/openai/plugins/blob/main/plugins/temporal/skills/temporal-developer/references/python/pyproject.toml):

```toml
[project]
name = "temporal-developer"
version = "0.1.0"
dependencies = [
    "temporalio>=1.6.0",
    "pydantic>=2.5.0"
]

```

This format supports exact version constraints and dependency groups that [`requirements.txt`](https://github.com/openai/plugins/blob/main/requirements.txt) cannot express.

## Handling External Service Integrations

Beyond code packages, plugins frequently depend on external APIs and cloud resources that require specific configuration patterns.

### Binding Service IDs

External integrations are referenced through the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file rather than hardcoded in skill logic. The `apps` object maps service names to integration IDs, as shown in [`plugins/zoominfo/.app.json`](https://github.com/openai/plugins/blob/main/plugins/zoominfo/.app.json). When a skill invokes an API, Codex resolves this ID to locate the correct remote service endpoint.

### Documenting Required Environment Variables

API keys and secrets must never be hard-coded. Instead, skills read from environment variables and document requirements in reference files like [`plugins/render/skills/render-deploy/references/error-patterns.md`](https://github.com/openai/plugins/blob/main/plugins/render/skills/render-deploy/references/error-patterns.md). A typical implementation validates presence before use:

```javascript
const apiKey = process.env.RENDER_API_KEY;
if (!apiKey) {
  throw new Error(
    "Missing RENDER_API_KEY – see docs at " +
    "https://github.com/openai/plugins/blob/main/plugins/render/skills/render-deploy/references/error-patterns.md"
  );
}

```

This pattern ensures clear error messages that link directly to setup documentation.

## Managing Conditional and Optional Dependencies

Skills may require heavy optional libraries that should not slow down every execution. The repository implements conditional loading patterns as shown in [`plugins/zoom/skills/video-sdk/react-native/examples/setup-guide.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/video-sdk/react-native/examples/setup-guide.md):

```javascript
if (process.env.USE_NATIVE_SDK) {
  const nativeSdk = require('@zoom/native-sdk');
}

```

This guards against unnecessary installations and improves cold start performance by importing heavy native bindings only when explicitly requested.

## Resolving Version Conflicts and Peer Dependencies

When dependencies conflict, reference documentation provides specific resolution strategies. The [`plugins/vercel/skills/workflow/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/workflow/SKILL.md) file recommends handling peer dependency conflicts with:

```bash
npm install --legacy-peer-deps

```

Or installing compatible versions simultaneously:

```bash
npm install react@18 @workflow/ai@latest

```

Testing dependency failures locally by unsetting environment variables verifies that error messages correctly point to relevant reference documentation.

## Summary

- **Declare runtime packages** in skill-specific [`package.json`](https://github.com/openai/plugins/blob/main/package.json) or [`pyproject.toml`](https://github.com/openai/plugins/blob/main/pyproject.toml) files, keeping `devDependencies` separate.
- **Bind external services** through [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) configuration files using read-only integration IDs rather than hardcoded URLs.
- **Inject secrets** via environment variables and document requirements in `references/*.md` files for clear error messaging.
- **Guard optional imports** behind feature flags to avoid unnecessary container bloat.
- **Pin exact versions** in [`pyproject.toml`](https://github.com/openai/plugins/blob/main/pyproject.toml) or [`package.json`](https://github.com/openai/plugins/blob/main/package.json) to prevent silent breaking changes.

## Frequently Asked Questions

### How do I add a new npm dependency to an existing plugin skill?

Navigate to the specific skill directory (e.g., `plugins/figma/skills/figma-use/`) and run `npm install <package> --save`. The skill runner automatically installs dependencies listed in the local [`package.json`](https://github.com/openai/plugins/blob/main/package.json) when executing the skill, without requiring manual installation on the host machine.

### What is the difference between [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) and [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) in the OpenAI plugins repository?

The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file declares the plugin's identity, version, and entry points for the Codex system, while [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) contains the `apps` mapping that links the plugin to external cloud integrations via service IDs. Codex reads the plugin manifest first to locate skills, then resolves external API calls using the integration IDs stored in the app binding file.

### How should I handle missing API keys or external service credentials?

Never hard-code credentials in source files. Instead, read values from environment variables at runtime and validate their presence before use. When a required variable is missing, throw an error that references the specific documentation file in your skill's `references/` directory, such as [`plugins/render/skills/render-deploy/references/error-patterns.md`](https://github.com/openai/plugins/blob/main/plugins/render/skills/render-deploy/references/error-patterns.md).

### Why does the repository prefer [`pyproject.toml`](https://github.com/openai/plugins/blob/main/pyproject.toml) over [`requirements.txt`](https://github.com/openai/plugins/blob/main/requirements.txt) for Python dependencies?

The [`pyproject.toml`](https://github.com/openai/plugins/blob/main/pyproject.toml) format supports exact version pinning, optional dependency extras, and modern Python packaging standards that [`requirements.txt`](https://github.com/openai/plugins/blob/main/requirements.txt) cannot express. This ensures reproducible builds and clearer dependency resolution across different execution environments.