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

> Discover the role of plugin JSON files in the Humanlayer Skills repository. Learn how this manifest enables skill discovery, versioning, and invocation for Claude AI.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: internals
- Published: 2026-09-12

---

**The per-plugin manifest ([`plugin.json`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/plugins/show-me/.claude-plugin/plugin.json), the show-me plugin declares:

```json
{
  "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:

```json
"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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/plugins/show-me/.claude-plugin/plugin.json)
- [`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)
- [`plugins/improve-claude-md/.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/plugins/improve-claude-md/.claude-plugin/plugin.json)
- [`plugins/design-control-loop/.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/plugins/design-control-loop/.claude-plugin/plugin.json)
- [`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)

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:

```typescript
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:

```typescript
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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/plugin.json) file?

The Instagit runtime will not recognize the directory as a valid skill. Without the manifest in [`.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/.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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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.