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

A 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 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 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:

{
  "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 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.

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:

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 files within hidden .claude-plugin directories inside each plugin folder:

Plugin	Manifest Path
show-me	plugins/show-me/.claude-plugin/plugin.json
narrow-react-prop-types	plugins/narrow-react-prop-types/.claude-plugin/plugin.json
improve-claude-md	plugins/improve-claude-md/.claude-plugin/plugin.json
design-control-loop	plugins/design-control-loop/.claude-plugin/plugin.json
build-iterated-agentic-loop	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 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 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 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 file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}