# What Information Is in a plugin.json File? A Complete Guide to Claude Plugin Manifests

> Discover what information resides in a plugin.json file. This guide explores Claude plugin manifests, detailing name, version, entry point, runtime, permissions, dependencies, and configurations.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: deep-dive
- Published: 2026-09-07

---

**A [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) file serves as the manifest for Claude plugins, containing essential metadata such as name, version, entry point, runtime environment, permissions, dependencies, and configuration defaults.**

The [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) file acts as the configuration cornerstone for Claude plugins in the open-source **humanlayer/skills** repository. This JSON manifest tells the Claude execution environment how to load, validate, and run plugin code safely. Understanding the structure of a [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) file is essential for developers extending the platform with custom capabilities.

## Example plugin.json Structure

The following manifest from the **show-me** plugin illustrates the standard schema used across the **humanlayer/skills** repository:

```json
{
  "name": "show-me",
  "description": "Display the current repository layout and file contents.",
  "version": "1.0.0",
  "author": "HumanLayer",
  "entry_point": "./src/index.js",
  "runtime": "node",
  "permissions": ["read"],
  "dependencies": {
    "fs-extra": "^10.0.0"
  },
  "config": {
    "showHidden": false
  },
  "metadata": {
    "tags": ["utility", "inspection"]
  }
}

```

## Core Metadata Fields

Every [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) file begins with identity information that uniquely identifies the plugin and its origin.

### Plugin Identity and Versioning

The **name** field provides a human-readable identifier for the plugin (e.g., `"show-me"`), while the **version** field follows semantic versioning (e.g., `"1.0.0"`). The **author** field specifies the creator or organization responsible for the plugin, enabling proper attribution and contact tracing within the **humanlayer/skills** ecosystem.

### Functional Description

The **description** field offers a concise summary of the plugin's purpose, displayed to users when browsing available plugins. The **entry_point** field specifies the relative path to the module exporting the plugin's main functionality (commonly `"./src/index.js"`), and the **runtime** field declares the execution environment (e.g., `"node"` or `"python"`).

## Security and Resource Configuration

Claude plugins operate within sandboxed environments, making explicit permission declarations mandatory.

### Permission Declarations

The **permissions** field contains an array of strings describing system capabilities the plugin requires, such as `["read"]` for file system access or `"network"` for HTTP requests. These declarations allow the **humanlayer/skills** loader to enforce security boundaries and prevent unauthorized operations before executing plugin code.

### Dependency Management

The **dependencies** field maps package names to version constraints (e.g., `"fs-extra": "^10.0.0"`), enabling automated installation of required libraries when the plugin initializes. This ensures the runtime environment contains all necessary code before the entry point executes.

## Runtime Configuration Defaults

Plugins often require tunable behavior without code changes.

### Configuration Values and Tags

The **config** field defines default configuration values (e.g., `"showHidden": false`) that can be overridden at runtime via environment variables or API calls. The **metadata** field stores arbitrary key-value pairs for additional context, such as `"tags": ["utility", "inspection"]`, which help categorize plugins within the **humanlayer/skills** registry.

## Parsing plugin.json Files Programmatically

When building tools that interact with the **humanlayer/skills** repository, you must read and validate these manifests before loading plugin code.

```javascript
import fs from 'fs';
import path from 'path';

function loadPluginManifest(pluginDir) {
  const manifestPath = path.join(pluginDir, '.claude-plugin', 'plugin.json');
  const raw = fs.readFileSync(manifestPath, 'utf‑8');
  const manifest = JSON.parse(raw);
  // Validate required fields
  if (!manifest.name || !manifest.entry_point) {
    throw new Error('Invalid plugin manifest');
  }
  return manifest;
}

// Example usage
const manifest = loadPluginManifest('./plugins/show-me');
console.log(`Loaded plugin: ${manifest.name} v${manifest.version}`);

```

Merge default configuration with runtime overrides using the spread operator:

```javascript
function getPluginConfig(manifest, overrides = {}) {
  return { ...manifest.config, ...overrides };
}

const config = getPluginConfig(manifest, { showHidden: true });
console.log('Effective config:', config);

```

## File Locations in the humanlayer/skills Repository

The repository stores individual [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) files within hidden `.claude-plugin` directories inside each plugin folder:

| Plugin | Manifest Path |
|--------|---------------|
| **show-me** | [`plugins/show-me/.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/plugins/show-me/.claude-plugin/plugin.json) |
| **narrow-react-prop-types** | [`plugins/narrow-react-prop-types/.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/plugins/narrow-react-prop-types/.claude-plugin/plugin.json) |
| **improve-claude-md** | [`plugins/improve-claude-md/.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/plugins/improve-claude-md/.claude-plugin/plugin.json) |
| **design-control-loop** | [`plugins/design-control-loop/.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/.claude-plugin/plugin.json) |
| **build-iterated-agentic-loop** | [`plugins/build-iterated-agentic-loop/.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/plugins/build-iterated-agentic-loop/.claude-plugin/plugin.json) |

These paths demonstrate the consistent schema location across all plugins in the repository.

## Summary

- A [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) file acts as the manifest describing a Claude plugin's metadata, runtime requirements, and security permissions within the **humanlayer/skills** repository.
- Essential fields include **name**, **version**, **author**, **entry_point**, and **runtime**, which identify the plugin and specify how to execute it.
- The **permissions** array and **dependencies** object define security boundaries and required packages for safe plugin operation.
- Default **config** values and **metadata** tags provide extensibility and categorization without modifying source code.
- Manifests are located in [`.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/plugin.json) within each plugin directory and can be parsed using standard Node.js file system operations.

## Frequently Asked Questions

### What is the primary purpose of a plugin.json file?

A [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) file serves as the declarative manifest that tells the Claude plugin loader how to initialize, configure, and secure a plugin. It separates static metadata from implementation code, enabling the **humanlayer/skills** platform to enumerate and validate plugins before execution.

### Which fields are required in a plugin.json manifest?

While the schema allows optional extensions, every valid manifest must include **name**, **version**, **entry_point**, and **runtime** to function correctly. The validation logic in **humanlayer/skills** checks for these fields specifically, throwing an error if either **name** or **entry_point** is missing.

### How does the permissions field affect plugin execution?

The **permissions** array acts as an explicit capability list that the runtime checks before granting system access. If a plugin declares `["read"]`, the loader ensures the execution sandbox can access the file system, whereas undeclared permissions remain blocked to prevent privilege escalation.

### Can configuration values in plugin.json be overridden at runtime?

Yes, the **config** object provides default values that the plugin loader merges with runtime-supplied overrides. As shown in the `getPluginConfig` example, you can spread user-provided options over the manifest defaults to produce an effective configuration object without modifying the original [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) file.