gh-bradleyboehmke-brads-marketplace-marketplace-dev/skills/plugin-structure-standards.md

title, description, tags

title	description	tags
Plugin Structure Standards	File structure, naming conventions, and frontmatter requirements for marketplace plugins	structure naming frontmatter conventions

Plugin Structure Standards

Metadata

Purpose: Define file structure and naming conventions for marketplace plugins Applies to: All Personal marketplace plugins Version: 1.0.0

---

Instructions

Plugin Naming Conventions

Plugin Directory Names:

• Use kebab-case: marketplace-dev, repo-investigator
• Be descriptive but concise
• Avoid redundant "plugin" suffix

Plugin Names in plugin.json:

• Match directory name exactly
• Used in marketplace.json registration
• Used in command namespace (e.g., /plugin-name:command)

Required Files

Every plugin MUST have:

1. .claude-plugin/plugin.json - Plugin metadata
2. At least one: Agent OR Command

plugin.json Structure:

{
  "name": "plugin-name",
  "description": "Clear 5-10 word description",
  "version": "X.Y.Z",
  "author": {
    "name": "Personal Team"
  },
  "tags": ["relevant", "searchable", "tags"]
}

Directory Structure

Standard Layout:

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required
├── agents/                   # Optional
│   └── expert-name.md
├── skills/                   # Optional
│   ├── knowledge-area-1.md
│   └── knowledge-area-2.md
└── commands/                 # Optional
    ├── action-1.md
    └── action-2.md

Personal:

• All plugin development docs go in root README.md
• No nested plugin directories
• Flat structure within each component type

File Naming Conventions

Agents: {role}-{specialty}.md

• Examples: plugin-architect.md, documentation-validator.md
• Lowercase, kebab-case
• Descriptive of expertise

Skills: {domain}-{topic}.md

• Examples: plugin-architecture-principles.md, progressive-disclosure.md
• Lowercase, kebab-case
• Noun-focused

Commands: {action}-{target}.md

• Examples: validate-docs.md, design-plugin.md
• Lowercase, kebab-case
• Verb-focused

Frontmatter Requirements

All component files must have YAML frontmatter:

Agents:

---
description: Brief description of agent expertise
---

Skills:

---
title: Skill Name
description: One sentence description
tags: [category, topic, use-case]
---

Commands:

---
description: What this command does (one sentence)
---

---

Resources

Complete Plugin Template

new-plugin/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   └── domain-expert.md
├── skills/
│   ├── domain-knowledge.md
│   └── methodology.md
└── commands/
    ├── quick-action.md
    └── detailed-action.md

plugin.json Template

{
  "name": "new-plugin",
  "description": "Clear 5-10 word description of plugin purpose",
  "version": "1.0.0",
  "author": {
    "name": "Personal Team"
  },
  "tags": [
    "domain-tag",
    "function-tag",
    "personal"
  ]
}

Agent File Template

---
description: Expert in [domain] for [purpose]
---

# [Agent Name] Agent

You are a **[role description]** for Personal.

Your expertise: [specific domain knowledge and approach]

## Your Approach
1. [Step 1]
2. [Step 2]
...

## Skills Available
- `skill-name-1` - Use when [condition]
- `skill-name-2` - Use when [condition]

Skill File Template

---
title: Skill Name
description: One sentence description
tags: [category, topic]
---

# Skill Name

## Metadata
**Purpose**: What this provides
**Applies to**: When to use this
**Version**: X.Y.Z

---

## Instructions
[Core knowledge, always loaded when activated]

---

## Resources
[Detailed examples, loaded on explicit request]

Command File Template

---
description: What this command does
---

# Command Name

You are a [role] performing [task].

## Command Parameters
[Reference `marketplace-command-patterns` skill for standard parameters]

## Objective
[What this command accomplishes]

## Process
1. [Step 1]
2. Activate skill: `skill-name`
3. [Step 3]

## Output Format
[How to structure the output]