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

To install a HumanLayer skill, add it to the .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) — maps skill IDs to filesystem paths
• Agent configuration — declares which skills to activate for a specific agent
• Skill metadata (SKILL.md and 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 and add your skill:

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

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:

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

The runtime performs these operations:

1. Parses the agent configuration
2. Loads marketplace.json to resolve skill paths
3. Mounts each skill's code and metadata
4. Merges SKILL.md documentation into the agent context

Key Files and Their Roles

File	Purpose	Location
marketplace.json	Central skill catalogue	.claude-plugin/marketplace.json
SKILL.md	Human-readable skill description	plugins/[skill-name]/skills/[skill-name]/SKILL.md
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 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, 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.

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