# Claude Plugin Directory Layout Requirements in HumanLayer Skills

> Understand Claude plugin directory layout for HumanLayer Skills. Learn about required files like plugin.json and SKILL.md for successful integration.

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

---

**A Claude plugin in the HumanLayer skills repository requires a strict directory structure with metadata in `plugins/<name>/.claude-plugin/plugin.json` and skill documentation in `plugins/<name>/skills/<name>/SKILL.md`.**

The HumanLayer skills repository uses a standardized directory layout to enable automatic discovery and loading of Claude plugins. Understanding these directory layout requirements ensures your plugin integrates correctly with the Instagit runtime environment.

## Required Directory Structure

### Plugin Metadata Location

Every plugin must include a [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) file located at `plugins/<plugin-name>/.claude-plugin/plugin.json`. This hidden `.claude-plugin` directory contains the plugin's metadata including name, version, author, repository, license, and keywords. The file must be valid JSON and reside exactly within this hidden folder so the Instagit runtime can locate it automatically.

### Skill Definition Location

The skill implementation documentation must reside at `plugins/<plugin-name>/skills/<plugin-name>/SKILL.md`. Critically, the directory name inside `skills/` must match the plugin name exactly. This Markdown file describes usage patterns, prompts, references, and examples for the skill.

### Optional Assets Folder

Supporting files such as YAML templates, example prompts, or auxiliary Markdown files should be placed in `plugins/<plugin-name>/skills/<plugin-name>/references/`. While not required, this is the conventional location for extra resources referenced from [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md).

## Critical Constraints and Naming Rules

- **Exact naming**: The folder under `skills/` must mirror the plugin name (e.g., `plugins/show-me/skills/show-me/`).
- **Hidden metadata folder**: The metadata file must be inside `.claude-plugin`, not `.claude_plugin` or any other variant.
- **File extensions**: [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) must be JSON; the skill file must be named exactly [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md).
- **Git-tracked**: Both files must be committed to the repository to be reachable via GitHub URL structures used by the platform.

## Complete Example: The show-me Plugin

Here is the directory tree for the `show-me` plugin as implemented in the `humanlayer/skills` repository:

```text
plugins/
└─ show-me/
   ├─ .claude-plugin/
   │   └─ plugin.json
   └─ skills/
       └─ show-me/
           ├─ SKILL.md
           └─ references/
               ├─ diagram.mmd
               └─ usage.yml

```

The [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) file ([source](https://github.com/humanlayer/skills/blob/main/plugins/show-me/.claude-plugin/plugin.json)) contains the plugin metadata:

```json
{
  "name": "show-me",
  "description": "Explain the current topic with concise diagrams, code‑shape sketches, and focused HTML artifacts",
  "version": "1.0.1",
  "author": {
    "name": "humanlayer",
    "email": "support@humanlayer.dev"
  },
  "repository": "https://github.com/humanlayer/skills",
  "license": "MIT",
  "keywords": ["visualization", "diagrams", "mermaid", "code", "html"]
}

```

The [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) file ([source](https://github.com/humanlayer/skills/blob/main/plugins/show-me/skills/show-me/SKILL.md)) documents the skill usage:

```markdown

# Show‑Me Skill

This skill renders diagrams, code sketches, and HTML snippets for the current topic.

## Usage

```json
{
  "action": "show-me",
  "prompt": "Explain React hooks with a diagram"
}

```

## References

- [Diagram template](references/diagram.mmd)
- [HTML example](references/example.html)

```

## Summary

- Place plugin metadata in `plugins/<name>/.claude-plugin/plugin.json` using valid JSON format.
- Store skill documentation in `plugins/<name>/skills/<name>/SKILL.md` where the folder name matches the plugin name exactly.
- Use the `references/` subfolder for optional supporting assets like templates and examples.
- Ensure both required files are committed to git so the Instagit runtime can access them via GitHub URLs.

## Frequently Asked Questions

### What happens if the skills subfolder name doesn't match the plugin name?

The Instagit runtime relies on exact path matching to locate [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md). If the directory under `skills/` differs from the plugin name in [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json), the platform will fail to discover and load the skill documentation automatically.

### Can I use a different name instead of .claude-plugin for the metadata folder?

No, the `.claude-plugin` directory name is mandatory. The platform specifically scans for this hidden folder to locate [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json), and using alternative naming conventions will prevent the plugin from being recognized by the discovery system.

### Is the references folder required for every plugin?

No, the `references/` folder is optional. It serves as the conventional location for auxiliary files like YAML templates or example prompts referenced in [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md), but plugins function correctly with only the required [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) and [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) files.

### Why must these files be tracked in Git?

The Instagit platform constructs GitHub URLs to access [`plugin.json`](https://github.com/humanlayer/skills/blob/main/plugin.json) and [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) directly from the repository. Untracked files are inaccessible via these URLs, which breaks the runtime's ability to load plugin metadata and skill definitions.