# HumanLayer Skill Plugin Directory Structure: How to Organize Plugins in the Skills Repository

> Understand the HumanLayer skill plugin directory structure under humanlayer/skills. Learn about skill definition markdown, Claude-plugin JSON, and reference assets.

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

---

**A HumanLayer skill plugin follows a three-part directory structure under `plugins/<skill-name>/` containing a skill definition markdown file, a Claude-plugin JSON manifest, and optional supporting assets in a `references/` folder.**

This standardized layout powers the `humanlayer/skills` open-source registry, making it easy to distribute, discover, and reuse LLM-assisted coding skills across projects.

## Core Directory Layout for HumanLayer Skill Plugins

Every plugin in the repository lives beneath the root-level **`plugins/`** directory. Each skill occupies its own named subdirectory with a predictable internal hierarchy:

```

plugins/
└─ <skill-name>/
   ├─ .claude-plugin/
   │   └─ plugin.json               ← Claude-plugin system manifest
   ├─ skills/
   │   └─ <skill-name>/
   │       └─ SKILL.md              ← human-readable skill definition
   └─ references/                   ← optional supporting assets
       ├─ workflow-template.yml
       ├─ response-template.md
       └─ prompt-template.md

```

This structure separates **metadata**, **documentation**, and **auxiliary resources** while keeping them co-located for version control and distribution.

## The Three Required Components of a Skill Plugin Directory

### 1. Skill Definition: `plugins/<skill-name>/skills/<skill-name>/SKILL.md`

The **[`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md)** file is the heart of every HumanLayer skill plugin. It contains:

- A description of the skill's purpose and use cases
- Prompts and usage instructions for the LLM
- Examples of expected inputs and outputs
- References to any supporting templates

**Location:** `plugins/<skill-name>/skills/<skill-name>/SKILL.md`

The nested `skills/<skill-name>/` path ensures compatibility with Claude's plugin discovery mechanism while allowing future multi-skill plugins.

### 2. Plugin Manifest: `plugins/<skill-name>/.claude-plugin/plugin.json`

The **[`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json)** file provides machine-readable metadata consumed by the Claude-plugin runtime:

```json
{
  "name": "skill-name",
  "description": "What this skill does",
  "version": "0.1.0",
  "author": {
    "name": "humanlayer",
    "email": "support@humanlayer.dev"
  },
  "repository": "https://github.com/humanlayer/skills",
  "license": "MIT",
  "keywords": ["relevant", "tags"]
}

```

**Location:** `plugins/<skill-name>/.claude-plugin/plugin.json`

The hidden `.claude-plugin/` directory keeps runtime metadata distinct from user-facing documentation.

### 3. Supporting Assets: `plugins/<skill-name>/references/` (Optional)

Skills that need **templates, examples, or scripts** ship them in a `references/` folder. Common file types include:

- **Workflow templates** (`.yml`, `.yaml`)
- **Response templates** (`.md`)
- **Prompt fragments** (`.md`)
- **TypeScript utilities** (`.ts`)

These assets are referenced from [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) using relative paths, enabling modular, reusable skill composition.

## Creating a New HumanLayer Skill Plugin: Step-by-Step

Use this bash script to scaffold a complete plugin directory structure:

```bash

# Create the nested skill directory

mkdir -p plugins/my-awesome-skill/skills/my-awesome-skill

# Initialize the skill definition

touch plugins/my-awesome-skill/skills/my-awesome-skill/SKILL.md

#Create the Claude-plugin manifest directory
mkdir plugins/my-awesome-skill/.claude-plugin

# Write the plugin.json metadata

cat > plugins/my-awesome-skill/.claude-plugin/plugin.json <<'EOF'
{
  "name": "my-awesome-skill",
  "description": "Brief description of what the skill does",
  "version": "0.1.0",
  "author": {
    "name": "humanlayer",
    "email": "support@humanlayer.dev"
  },
  "repository": "https://github.com/humanlayer/skills",
  "license": "MIT",
  "keywords": ["example", "skill"]
}
EOF

# Add optional references folder

mkdir plugins/my-awesome-skill/references
touch plugins/my-awesome-skill/references/workflow-template.yml

```

## Referencing Assets Within SKILL.md

Link to supporting files using repository-relative paths:

```markdown

# Skill: My Awesome Skill

## References

- **Workflow template**: [workflow-template.yml](/plugins/my-awesome-skill/references/workflow-template.yml)
- **Prompt template**: [prompt-template.md](/plugins/my-awesome-skill/references/prompt-template.md)
- **Response format**: [response-template.md](/plugins/my-awesome-skill/references/response-template.md)

```

These references enable the Claude agent to locate and load auxiliary resources at runtime.

## Real-World Examples from the humanlayer/skills Repository

| Skill | SKILL.md Path | plugin.json Path |
|-------|-------------|------------------|
| `show-me` | [`plugins/show-me/skills/show-me/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/show-me/skills/show-me/SKILL.md) | [`plugins/show-me/.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/plugins/show-me/.claude-plugin/plugin.json) |
| `narrow-react-prop-types` | [`plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md`](https://github.com/humanlayer/skills/blob/main/plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md) | [`plugins/narrow-react-prop-types/.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/plugins/narrow-react-prop-types/.claude-plugin/plugin.json) |

Both skills follow the identical directory structure, demonstrating the consistency enforced across the repository.

## Why This Directory Structure Matters

The HumanLayer skill plugin directory structure delivers three key benefits:

- **Discoverability** – The Claude-plugin system scans [`.claude-plugin/plugin.json`](https://github.com/humanlayer/skills/blob/main/.claude-plugin/plugin.json) to index available skills
- **Maintainability** – Predictable paths make tooling, CI checks, and documentation generation straightforward
- **Extensibility** – The `references/` pattern allows skills to evolve from simple prompts to complex multi-file workflows without structural changes

## Summary

- **Root location**: All plugins live under `plugins/<skill-name>/` at the repository root
- **SKILL.md**: Human-readable skill definition at `plugins/<skill-name>/skills/<skill-name>/SKILL.md`
- **plugin.json**: Machine-readable manifest at `plugins/<skill-name>/.claude-plugin/plugin.json`
- **references/**: Optional folder for templates, scripts, and auxiliary assets
- **Consistency**: Every skill in `humanlayer/skills` follows this identical hierarchy

## Frequently Asked Questions

### Can a single plugin directory contain multiple skills?

No. The current HumanLayer skill plugin directory structure assumes a 1:1 mapping between plugin directories and skills. The nested `skills/<skill-name>/` path inside each plugin preserves forward compatibility for future multi-skill plugins, but as implemented in `humanlayer/skills`, each `<skill-name>/` directory contains exactly one skill definition.

### What fields are required in [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json)?

The Claude-plugin runtime requires `name`, `description`, and `version` at minimum. The `humanlayer/skills` repository conventionally includes `author`, `repository`, `license`, and `keywords` fields as well. The manifest at `plugins/<skill-name>/.claude-plugin/plugin.json` must be valid JSON and use lowercase kebab-case for the `name` field to match the directory name.

### Is the `references/` folder mandatory?

No. The `references/` folder is optional. Simple skills that rely entirely on inline prompts within [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) need no external assets. Add the folder only when your skill requires workflow templates, response formats, prompt fragments, or executable scripts beyond the core markdown definition.