Claude Plugin Directory Layout Requirements in HumanLayer Skills

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 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.

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 must be JSON; the skill file must be named exactly 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:

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

The plugin.json file (source) contains the plugin metadata:

{
  "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 file (source) documents the skill usage:

# 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
• HTML example

## 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.

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