HumanLayer Skills Marketplace Plugin Source Resolution and Schema Constraints

The humanlayer/skills marketplace resolves plugin sources by joining the repository root with the relative source path defined in .claude-plugin/marketplace.json, then validates that the target directory contains a valid 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 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 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 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 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 file (typically at .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 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.

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

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

{
  "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. 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 at the repository root.
• Plugin sources resolve as relative filesystem paths joined to the repository root, requiring directories that contain valid 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 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.

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