Understanding the Per-Plugin Manifest (`plugin.json`) in the Humanlayer Skills Repository

The per-plugin manifest (plugin.json) is a JSON configuration file located in the .claude-plugin/ directory that supplies metadata for discovering, versioning, and invoking Claude AI skills within the Humanlayer ecosystem.

Each skill in the humanlayer/skills repository functions as an independent package that carries its own manifest. This self-describing approach allows the Instagit marketplace and Claude AI platform to enumerate, load, and execute plugins without inspecting their internal implementation details.

Core Responsibilities of the Per-Plugin Manifest

The plugin.json file serves as the single source of truth for a skill's identity and contract. It handles several critical functions that enable the plugin ecosystem to operate.

Identification and Versioning

The manifest provides human-readable identifiers through three required fields:

• name: The unique identifier for the skill (e.g., "show-me")
• description: A concise explanation of the skill's purpose
• version: Semantic versioning for tracking updates (e.g., "1.0.1")

According to the source code in plugins/show-me/.claude-plugin/plugin.json, the show-me plugin declares:

{
  "name": "show-me",
  "description": "Explain the current topic with concise diagrams, code-shape sketches, and focused HTML artifacts",
  "version": "1.0.1"
}

Authorship and Repository Linkage

The manifest establishes provenance and compliance through structured metadata:

• author: An object containing name and email fields for maintainer contact
• repository: A URL linking back to the source code (e.g., "https://github.com/humanlayer/skills")
• license: The SPDX license identifier (e.g., "MIT")

This transparency allows the platform to perform compliance checks and enables users to navigate directly to the implementation.

Discovery Keywords

The keywords array improves searchability within the marketplace and assists the AI in selecting appropriate skills for specific requests. The show-me plugin uses:

"keywords": ["visualization", "diagrams", "mermaid", "code", "html"]

These tags enable semantic matching when Claude determines which skill to invoke for a given user query.

Runtime Compatibility

The presence of a correctly-formatted plugin.json in the .claude-plugin/ directory acts as an implicit contract. It signals to the Instagit engine that the directory contains a valid Claude-compatible skill, triggering automatic loading without requiring explicit registration in a central index.

Extensibility

The JSON schema supports additional fields for future expansion. Potential extensions include inputSchema, outputSchema, or commands to describe the skill's API contract more richly. This forward compatibility ensures the core engine remains agnostic to implementation changes while the manifest evolves.

File Location Convention

Every plugin follows a strict directory structure. The manifest must reside at:

plugins/{plugin-name}/.claude-plugin/plugin.json

Key manifests in the repository include:

• plugins/show-me/.claude-plugin/plugin.json
• plugins/narrow-react-prop-types/.claude-plugin/plugin.json
• plugins/improve-claude-md/.claude-plugin/plugin.json
• plugins/design-control-loop/.claude-plugin/plugin.json
• plugins/build-iterated-agentic-loop/.claude-plugin/plugin.json

The hidden .claude-plugin/ directory separates platform metadata from the skill's functional code.

Loading and Registration Patterns

Platform implementations read the manifest using standard filesystem operations. Here is the typical loading pattern:

import * as fs from 'fs';
import * as path from 'path';

function loadPluginManifest(pluginDir: string) {
  const manifestPath = path.join(pluginDir, '.claude-plugin', 'plugin.json');
  const raw = fs.readFileSync(manifestPath, 'utf-8');
  return JSON.parse(raw);
}

// Usage
const manifest = loadPluginManifest('plugins/show-me');
console.log(`Loading ${manifest.name} v${manifest.version}`);

When registering a skill in the marketplace, the platform extracts metadata directly from the manifest:

import { registerSkill } from '@instagit/skill-registry';

const manifest = loadPluginManifest('plugins/design-control-loop');
registerSkill({
  id: manifest.name,
  description: manifest.description,
  version: manifest.version,
  keywords: manifest.keywords,
  // Runtime entry point is discovered from the surrounding folder layout
});

This architecture enables independent versioning and updating of plugins without modifying the core Instagit engine.

Summary

• The per-plugin manifest (plugin.json) lives in the .claude-plugin/ directory and defines a skill's metadata.
• It provides identification, versioning, authorship, licensing, and discovery keywords required by the Claude AI platform.
• The manifest acts as a compatibility marker, allowing the runtime to detect and load valid skills automatically.
• File paths follow the convention plugins/{name}/.claude-plugin/plugin.json across the humanlayer/skills repository.
• The schema is extensible, supporting future fields like input/output schemas without breaking changes.

Frequently Asked Questions

What happens if a plugin is missing its plugin.json file?

The Instagit runtime will not recognize the directory as a valid skill. Without the manifest in .claude-plugin/plugin.json, the platform cannot determine the skill's name, version, or entry point, causing the plugin to be excluded from the marketplace and unavailable to Claude AI.

Can I add custom fields to my plugin.json?

Yes, the manifest schema supports extensibility. You can add custom fields (e.g., inputSchema, outputSchema, or implementation-specific metadata) without breaking existing tooling, provided the required fields (name, description, version, author, repository, license) remain present.

How does semantic versioning work for skills?

The version field follows standard semantic versioning (SemVer). When you update a skill's logic, increment the appropriate version component in plugin.json. The platform uses this value to track updates and notify users of new capabilities or breaking changes.

Where exactly should I place the plugin.json file in my plugin directory?

Place the file in a hidden directory named .claude-plugin/ at the root of your plugin folder. The complete path should be {plugin-name}/.claude-plugin/plugin.json. This convention separates platform metadata from your skill's implementation code.

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