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

> Discover how skills are structured in the HumanLayer Skills marketplace. Learn about the plugin-centric hierarchy, SKILL.md files, and marketplace registry.

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

---

**The HumanLayer Skills marketplace organizes skills using a plugin-centric hierarchy, with each skill defined by a [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) file nested under `plugins/<plugin-name>/skills/<skill-name>/` and catalogued in the root [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.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`](https://github.com/humanlayer/skills/blob/main/.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`](https://github.com/humanlayer/skills/blob/main/.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`](https://github.com/humanlayer/skills/blob/main/SKILL.md) format ensures skills are human-readable while remaining parsable by automated tooling.

### Reference Assets

Adjacent to each [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/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.

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

```

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

```bash
/show-me

```

## Programmatic Access

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

```javascript
// 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`](https://github.com/humanlayer/skills/blob/main/.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`](https://github.com/humanlayer/skills/blob/main/.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`](https://github.com/humanlayer/skills/blob/main/.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`](https://github.com/humanlayer/skills/blob/main/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.