How Skills Are Structured in the HumanLayer Skills Marketplace: A Complete Guide

The HumanLayer Skills marketplace organizes skills using a plugin-centric hierarchy, with each skill defined by a SKILL.md file nested under plugins/<plugin-name>/skills/<skill-name>/ and catalogued in the root .claude-plugin/marketplace.json registry.

The humanlayer/skills repository implements an extensible marketplace architecture that separates plugin metadata from skill definitions. This structure enables automated discovery through a central JSON registry while keeping individual skill implementations modular and self-contained.

The Root Marketplace Registry

The foundation of the HumanLayer Skills marketplace is .claude-plugin/marketplace.json located at the repository root. This file serves as the canonical manifest, listing every available plugin with metadata including name, description, version, author, and the relative source path to each plugin's code.

According to the source code, this JSON file drives both the marketplace UI and the CLI installer, enabling automated tooling to enumerate available skills without scanning the entire directory structure.

Plugin Directory Structure

Each plugin resides in its own directory under plugins/<plugin-name>/. This folder contains standardized subdirectories and configuration files that define the plugin's identity and capabilities.

The Plugin Manifest

Inside each plugin directory, .claude-plugin/plugin.json provides lightweight descriptors such as the plugin's name, description, version, author, repository URL, license, and keywords. This file distinguishes the plugin container from the individual skills it provides.

Skill Definitions

The core executable content lives in skills/<skill-name>/SKILL.md. This markdown file begins with YAML front-matter declaring the skill's name and description, followed by usage guidelines, examples, and visual aids that guide execution. The SKILL.md format ensures skills are human-readable while remaining parsable by automated tooling.

Reference Assets

Adjacent to each SKILL.md file, a references/ directory stores auxiliary files including YAML templates, TypeScript snippets, and Mermaid diagrams. These assets are imported at runtime when a user invokes the specific skill, allowing complex skills to bundle necessary templates without cluttering the main definition file.

Installation and Invocation Flow

The marketplace exposes a standardized CLI interface for skill consumption. Users install skills using the npx command, which reads the marketplace registry, copies the selected plugin into the user's repository, and registers the associated slash command.

npx skills add humanlayer/skills --skill show-me

Once installed, skills are invoked directly via their registered slash commands:

/show-me

Programmatic Access

Tooling scripts can interact with the marketplace structure directly by parsing the JSON registry and resolving skill paths dynamically:

// Load marketplace metadata
const marketplace = require('./.claude-plugin/marketplace.json');

// Find the entry for the “show‑me” plugin
const showMe = marketplace.plugins.find(p => p.name === 'show-me');

// Resolve the path to its skill definition
const skillPath = `${showMe.source}/skills/show-me/SKILL.md`;

// Read the skill metadata (front‑matter) and content
const fs = require('fs');
const skillContent = fs.readFileSync(skillPath, 'utf‑8');

This approach allows third-party tools to enumerate available capabilities and load skill definitions without hardcoding paths.

Summary

• Central Registry: .claude-plugin/marketplace.json at the repository root contains the master list of all plugins with canonical metadata and source paths.
• Plugin Containers: Each plugin lives in plugins/<plugin-name>/ with a .claude-plugin/plugin.json descriptor defining authorship and versioning.
• Skill Definitions: Individual skills are defined in skills/<skill-name>/SKILL.md using front-matter for metadata and markdown for usage instructions.
• Asset Bundling: Supporting files live in references/ directories adjacent to skill definitions, enabling complex templates and diagrams.
• CLI Integration: The marketplace supports npx skills add for installation and slash commands (/skill-name) for invocation.

Frequently Asked Questions

Where is the master list of skills defined in the HumanLayer Skills marketplace?

The master registry is located at .claude-plugin/marketplace.json in the repository root. This file enumerates every available plugin with fields for name, description, version, author, and the relative source path, serving as the single source of truth for marketplace tooling and UIs.

How does the marketplace distinguish between a plugin and an individual skill?

A plugin is a container defined by plugins/<plugin-name>/.claude-plugin/plugin.json that holds metadata like license and keywords. Individual skills reside within that plugin at plugins/<plugin-name>/skills/<skill-name>/SKILL.md, separating the plugin's identity from its executable capabilities.

What types of files can be bundled with a skill besides the main definition?

Skills can include auxiliary assets in a references/ directory located next to SKILL.md. This folder typically contains YAML templates, TypeScript code snippets, Mermaid diagrams, and other supporting files imported at runtime during skill execution.

How do I install and use a skill from the HumanLayer marketplace?

Install any skill using the CLI command npx skills add humanlayer/skills --skill <skill-name>, which copies the plugin into your project and registers the slash command. After installation, invoke the skill directly using /<skill-name> from your terminal or chat interface.

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