# How to Install a HumanLayer Skill: A Step-by-Step Guide

> Learn how to install a HumanLayer skill with this step-by-step guide. Add your skill to the marketplace and integrate it into your agent's configuration easily.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: how-to-guide
- Published: 2026-09-07

---

**To install a HumanLayer skill, add it to the [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) catalogue and include its identifier in your agent's `skills` array.**

HumanLayer skills are lightweight, self-contained plugins that extend agent capabilities. This article walks through the exact installation process using the official `humanlayer/skills` repository structure.

## Understanding HumanLayer Skill Installation

Unlike traditional package managers, HumanLayer uses a **declarative marketplace system**. The framework resolves skill paths from a central JSON catalogue and mounts them at runtime. No `npm install` or `pip install` required—just configuration updates.

The installation flow involves three moving parts:

- **Marketplace file** ([`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json)) — maps skill IDs to filesystem paths
- **Agent configuration** — declares which skills to activate for a specific agent
- **Skill metadata** ([`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) and [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json)) — describes the skill's interface

## Step 1: Register the Skill in the Marketplace

The marketplace file acts as the master index. Each entry follows the pattern `"skill-id": "relative/path/to/skill"`.

Open [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) and add your skill:

```json
{
  "skills": {
    "show-me": "plugins/show-me",
    "narrow-react-prop-types": "plugins/narrow-react-prop-types",
    "design-control-loop": "plugins/design-control-loop"
  }
}

```

The path is relative to the repository root. HumanLayer's loader expects this exact structure to resolve skill locations.

## Step 2: Reference the Skill in Agent Configuration

Create or edit your agent's YAML (or JSON) configuration file. Add the skill identifier to the `skills` list:

```yaml
name: my-agent
version: 1.0.0
skills:
  - show-me
  - design-control-loop

```

The order matters—skills are loaded sequentially, and later skills can override or extend earlier ones.

## Step 3: Launch the Agent

Start your agent using the HumanLayer CLI:

```bash
npx humanlayer run --config ./my-agent.yaml

```

The runtime performs these operations:

1. Parses the agent configuration
2. Loads [`marketplace.json`](https://github.com/humanlayer/skills/blob/main/marketplace.json) to resolve skill paths
3. Mounts each skill's code and metadata
4. Merges [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) documentation into the agent context

## Key Files and Their Roles

| File | Purpose | Location |
|------|---------|----------|
| [`marketplace.json`](https://github.com/humanlayer/skills/blob/main/marketplace.json) | Central skill catalogue | [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) |
| [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) | Human-readable skill description | `plugins/[skill-name]/skills/[skill-name]/SKILL.md` |
| [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) | Machine-readable metadata | `plugins/[skill-name]/.claude-plugin/plugin.json` |
| `references/*` | Reusable templates and schemas | `plugins/[skill-name]/skills/[skill-name]/references/` |

## Verifying Installation

After startup, check agent logs for skill load confirmation. A successful mount shows:

```

[humanlayer] Loaded skill: show-me (plugins/show-me)
[humanlayer] Loaded skill: design-control-loop (plugins/design-control-loop)

```

Missing skills trigger explicit errors naming the unresolved identifier and the path attempted.

## Summary

- **Update** [`.claude-plugin/marketplace.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/marketplace.json) to register a skill's location
- **Include** the skill ID in your agent's `skills` array
- **Run** `humanlayer run` to mount and activate the skill
- **Verify** via load logs that the skill resolved correctly

## Frequently Asked Questions

### Where does the skill code actually live?

Skill code resides in the `plugins/` directory, each skill in its own folder. The marketplace file only stores a pointer—no code is copied or moved during installation. This keeps the repository monorepo-friendly and enables quick iteration.

### Can I use a skill without modifying marketplace.json?

No. HumanLayer's security model requires explicit registration. The runtime refuses to load skills not listed in [`marketplace.json`](https://github.com/humanlayer/skills/blob/main/marketplace.json), preventing arbitrary code execution from untrusted paths.

### What happens if two skills have the same ID?

The marketplace uses JSON keys, so duplicate IDs are impossible in a valid JSON file. If you manually introduce a collision, the last entry wins—but this breaks deterministic loading and should be avoided.