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

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 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 file provides machine-readable metadata consumed by the Claude-plugin runtime:

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

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

# 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	plugins/show-me/.claude-plugin/plugin.json
narrow-react-prop-types	plugins/narrow-react-prop-types/skills/narrow-react-prop-types/SKILL.md	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 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?

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

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