plugin-architecture

name	plugin-architecture
description	Master plugin folder structure, manifest design, and architectural patterns. Learn to organize plugins for scalability and maintainability.
sasmp_version	1.3.0
bonded_agent	01-plugin-architect
bond_type	PRIMARY_BOND

Plugin Architecture

Quick Start

A well-structured plugin follows this minimal layout:

my-plugin/
├── .claude-plugin/
│   └── plugin.json              # Required manifest
├── agents/
│   └── agent.md                 # Agent definition
├── skills/
│   └── skill-name/SKILL.md      # Skill definition
├── commands/
│   └── command.md               # Command definition
├── hooks/
│   └── hooks.json               # Automation hooks
└── README.md

Plugin Manifest (plugin.json)

The manifest defines what your plugin does and what it contains.

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What my plugin does",
  "author": "Your Name",
  "license": "MIT",
  "repository": "https://github.com/user/repo",
  "agents": [
    {
      "name": "agent-id",
      "description": "What it does",
      "file": "agents/agent.md"
    }
  ],
  "commands": [
    {
      "name": "command",
      "file": "commands/command.md",
      "description": "What it does"
    }
  ],
  "skills": [
    {
      "name": "skill-id",
      "file": "skills/skill-id/SKILL.md"
    }
  ],
  "hooks": {
    "file": "hooks/hooks.json"
  }
}

Manifest Rules

• name: lowercase-hyphens, 10-50 chars
• version: semantic (MAJOR.MINOR.PATCH)
• description: 50-256 characters
• agents: array of agent definitions
• commands: array of command definitions
• skills: array of skill definitions
• hooks: optional, points to hooks.json

Agent Structure

Each agent is a markdown file with YAML frontmatter:

---
description: What this agent does (max 1024 chars)
capabilities:
  - "Capability 1"
  - "Capability 2"
  - "Capability 3"
---

# Agent Name

[Detailed content about what agent does]

## When to Use

Use this agent when:
- Need 1
- Need 2
- Need 3

Naming Convention

01-primary-agent.md
02-secondary-agent.md
03-tertiary-agent.md

Skill Structure

Skills provide reusable knowledge and examples.

skills/
├── skill-one/
│   ├── SKILL.md              # Always named SKILL.md
│   └── resources/            # Optional: additional files
│       ├── example.py
│       └── reference.md
└── skill-two/
    └── SKILL.md

SKILL.md Format

---
name: skill-unique-id
description: "What skill teaches (max 1024 chars)"
---

# Skill Name

## Quick Start

[Working code - copy-paste ready]

## Core Concepts

### Concept 1
[Explanation with code]

### Concept 2
[More examples]

## Advanced Topics

[Expert-level content]

## Real-World Projects

[Practical applications]

Command Structure

Commands are entry points for users:

commands/
├── create.md
├── design.md
├── test.md
└── deploy.md

Command Format

# /command-name - Brief Description

## What This Does

[Clear explanation]

## Usage

/command-name [options]

## Options

| Option | Description |
|--------|-------------|
| `--flag` | What it does |

## Example

[Sample output]

## Next Steps

[What to do next]

Hook Configuration

Hooks automate plugin behavior:

{
  "hooks": [
    {
      "id": "hook-id",
      "name": "Hook Name",
      "event": "event-type",
      "condition": "condition",
      "action": "action-name",
      "enabled": true
    }
  ]
}

Architectural Patterns

Single Responsibility

Agent 1: Domain A only
Agent 2: Domain B only
Agent 3: Domain C only

Layered Architecture

Commands (User interface)
    ↓
Agents (Logic & guidance)
    ↓
Skills (Knowledge & examples)
    ↓
Hooks (Automation)

Agent Collaboration

Agent A → asks → Agent B
  ↓
Links to shared skills
  ↓
Agent C for final review

File Organization Best Practices

✅ Logical grouping
├─ All agents together
├─ All skills organized
├─ All commands grouped
└─ Config centralized

✅ Clear naming
├─ agents/01-primary.md
├─ agents/02-secondary.md
├─ skills/skill-one/SKILL.md
└─ commands/action.md

✅ Scalable structure
├─ Easy to add agents
├─ Simple to extend skills
├─ Clear command naming
└─ Organized hooks

Scaling Your Plugin

From Simple to Complex

Stage 1: 1 agent, 2 skills, 1 command

Minimal viable plugin

Stage 2: 3 agents, 5 skills, 3 commands

Feature-rich plugin

Stage 3: 5-7 agents, 10+ skills, 5+ commands

Enterprise plugin

Common Mistakes

❌ Unclear structure → Use recommended layout ❌ Mixed concerns → One agent = one domain ❌ Missing manifest → Always include plugin.json ❌ Bad naming → Use lowercase-hyphens ❌ No documentation → Document everything

---

Use this skill when:

• Designing plugin structure
• Creating plugin.json
• Organizing agents and skills
• Planning plugin growth

---

Status: ✅ Production Ready | SASMP: v1.3.0 | Bonded Agent: 01-plugin-architect