# HumanLayer Skills Marketplace Plugin Source Resolution and Schema Constraints

> Learn how the humanlayer skills marketplace resolves plugin sources and understand the .claude-plugin/marketplace.json schema constraints. Discover valid plugin structures.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: api-reference
- Published: 2026-09-13

---

**The humanlayer/skills marketplace resolves plugin sources by joining the repository root with the relative `source` path defined in [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json), then validates that the target directory contains a valid [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) file conforming to the Claude Code marketplace schema.**

The humanlayer/skills repository implements a Claude Code marketplace model that enables version-controlled plugin distribution. Understanding the precise source resolution algorithm and strict schema validation rules is essential for developers contributing to this ecosystem. Every plugin entry in the central marketplace definition undergoes rigorous path resolution and structural validation before becoming available to Claude Code users.

## How Plugin Source Resolution Works

The resolution process begins when Claude Code loads the marketplace configuration from [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) at the repository root. The system follows a deterministic four-step algorithm to locate and validate plugin code.

### The Resolution Algorithm

1. **Schema Validation**: Claude Code reads [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) and validates it against the JSON Schema referenced by the `$schema` property (`https://anthropic.com/claude-code/marketplace.schema.json`).

2. **Path Resolution**: For each object in the `plugins` array, the system resolves the `source` string by joining the repository root with the relative path (e.g., `"./plugins/improve-claude-md"` becomes an absolute filesystem path).

3. **Directory Verification**: The resolved path must exist as a directory on disk. The runtime traverses this directory to locate an internal [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) file containing the plugin's metadata (name, description, version, author, repository, license, and optional keywords).

4. **Plugin Loading**: Claude Code loads the discovered [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) and exports the plugin functionality for downstream prompts and workflows. Any failure in path resolution or validation aborts the marketplace load.

### File Path Requirements

The `source` field imposes strict filesystem constraints:

- **Relative Path Only**: The value must be a relative path starting with `./` (e.g., `"./plugins/my-plugin"`). Absolute paths and URLs are rejected.
- **Directory Target**: The resolved path must point to an existing directory, not a file.
- **Nested Plugin Config**: The target directory must contain a [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) file (typically at [`.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/plugin.json) inside the plugin directory) defining the plugin's internal metadata.

## marketplace.json Schema Constraints

The marketplace schema enforces a rigid structure to ensure consistency and discoverability across the humanlayer/skills ecosystem.

### Top-Level Marketplace Properties

The root [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) object requires five mandatory properties:

- **`$schema`**: Must be the exact string `"https://anthropic.com/claude-code/marketplace.schema.json"`.
- **`name`**: Human-readable marketplace identifier; must be unique across marketplaces (e.g., `"skills"`).
- **`owner`**: Object containing `name` (string) and `email` (string, valid email format).
- **`metadata`**: Object requiring `description` (string) and `version` (semantic version string, e.g., `"1.0.0"`).
- **`plugins`**: Array of plugin objects; cannot be empty.

### Plugin Object Requirements

Each element in the `plugins` array must satisfy the following constraints:

**Required Fields:**
- **`name`**: Unique identifier within the marketplace (string).
- **`description`**: Brief human-readable summary (string).
- **`version`**: Semantic version string (e.g., `"1.2.3"`).
- **`author`**: Object with `name` and `email` properties (same validation as marketplace `owner`).
- **`source`**: Relative path string beginning with `./` that resolves to an existing directory containing [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json).

**Optional Fields:**
- **`category`**: Free-form label for grouping (e.g., `"productivity"`, `"dev-tools"`).
- **`keywords`**: Array of searchable string tags for discovery.

### Validation Rules

Any deviation from the schema causes immediate marketplace rejection:

- Missing required fields trigger validation errors.
- Malformed email addresses in `owner` or `author` objects fail regex validation.
- Non-semantic version strings (e.g., `"v1.0"` instead of `"1.0.0"`) are rejected.
- `source` paths that do not resolve to existing directories or lack valid [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) files prevent marketplace loading.

## Practical Implementation Examples

Developers interact with the marketplace through declaration files and configuration updates.

### Referencing a Plugin in Claude Code

When building prompts that leverage marketplace plugins, use the import syntax:

```json
{
  "type": "import",
  "plugin": "improve-claude-md",
  "fromMarketplace": "skills"
}

```

Claude Code processes this import by looking up the `skills` marketplace, locating the plugin entry with `name: "improve-claude-md"`, resolving the `source` field (`"./plugins/improve-claude-md"`), and loading the associated [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) from that directory.

### Adding a New Plugin Entry

To register a new plugin in the marketplace, append this object to the `plugins` array in [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json):

```json
{
  "name": "my-awesome-plugin",
  "description": "Example plugin that demonstrates source resolution",
  "version": "0.1.0",
  "author": {
    "name": "humanlayer",
    "email": "support@humanlayer.dev"
  },
  "source": "./plugins/my-awesome-plugin",
  "category": "demo",
  "keywords": ["example", "demo"]
}

```

Create the corresponding directory structure at `plugins/my-awesome-plugin/` containing a valid [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json). Upon the next marketplace initialization, Claude Code resolves the `"./plugins/my-awesome-plugin"` path and exposes the plugin to the runtime.

## Summary

- The humanlayer/skills marketplace defines all plugins in [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) at the repository root.
- Plugin sources resolve as relative filesystem paths joined to the repository root, requiring directories that contain valid [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) files.
- The schema mandates strict semantic versioning, valid email formats, and unique identifiers for both the marketplace and individual plugins.
- The `source` field must use relative paths starting with `./` and must point to existing directories within the same repository.
- Validation failures at any stage (schema mismatch, missing files, malformed metadata) result in marketplace rejection.

## Frequently Asked Questions

### What happens if the source path points to a missing directory?

Claude Code will reject the entire marketplace load with a validation error. The `source` path must resolve to an existing directory that contains a [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) file; otherwise, the plugin is considered invalid and the marketplace fails to initialize.

### Can I use absolute paths or URLs for the source field?

No. The marketplace schema strictly requires relative paths beginning with `./`. This constraint ensures all plugin code remains within the version-controlled repository, preventing external dependencies and maintaining reproducibility across environments.

### How does the marketplace validate semantic versioning?

The schema enforces semantic versioning (SemVer) compliance on both the marketplace `metadata.version` field and each plugin's `version` field. Strings must follow the `MAJOR.MINOR.PATCH` format (e.g., `"1.0.0"`). Non-compliant strings such as `"v1.0"` or `"1.0-beta"` trigger validation failures.

### Is the category field used for filtering in Claude Code?

While the `category` field is optional and accepts free-form strings, it is primarily intended for organizational metadata and discoverability within the marketplace JSON structure. Current implementations may not actively filter by category in the Claude Code interface, but populating it improves documentation and future-proofs the plugin for UI enhancements.