Plugins

Extend Droid with shareable packages of skills, commands, droids, hooks, and MCP servers.

Plugins package Droid customizations so they can be shared, installed, updated, and governed as one unit. A plugin can bundle skills, slash commands, custom droids, hooks, and MCP servers for a specific workflow, team, or organization.

Use standalone .factory/ configuration for quick local iteration. Use a plugin when a customization should be reused across repositories, installed by teammates, or distributed through a marketplace.

What plugins include

A plugin is a directory with a required manifest at .factory-plugin/plugin.json and optional component folders at the plugin root.

Component	Purpose	Invocation
Skills	Reusable capabilities with instructions, examples, and supporting files	Invoked by Droid when relevant or by /skill-name
Commands	User-invoked slash commands for repeatable workflows	Invoked directly by /command-name
Droids	Specialized subagents with their own prompts, models, and tool policies	Used by the parent Droid through delegation
Hooks	Lifecycle commands that enforce deterministic automation or guardrails	Run automatically when matching events fire
MCP servers	External tools exposed to Droid through Model Context Protocol	Available as tools when the plugin is active

For example, a security engineering plugin might include a security review skill, a /threat-model command, a security-focused custom droid, hooks that block risky files, and MCP configuration for a vulnerability database.

When to use plugins

Approach	Best for
Standalone .factory/ files	Personal workflows, project-specific context, experiments, one-off commands
Plugins	Shared team workflows, reusable conventions, curated tool bundles, versioned distribution
Org-managed plugin rollout	Organization-approved marketplaces and mandatory plugin installation

Start with standalone configuration when the workflow is still changing. Convert it to a plugin once the workflow is stable enough to share.

Managing plugins

Use /plugins to browse, install, update, and remove plugins from the interactive CLI.

/plugins

The plugin manager has three tabs:

• Browse — view installable plugins from registered marketplaces.
• Installed — inspect, update, or uninstall active plugins.
• Marketplaces — add, update, or remove plugin sources.

For scripting, use the droid plugin CLI commands from your shell:

droid plugin install <plugin@marketplace> [--scope user|project]
droid plugin uninstall <plugin@marketplace> [--scope user|project]
droid plugin update [plugin@marketplace] [--scope user|project]
droid plugin list [--scope user|project]

Plugin IDs use the format pluginName@marketplaceName, such as security-engineer@factory-plugins.

Marketplaces are Git-backed plugin catalogs. Use Plugin Marketplaces to add official, external, local, team, or organization-managed plugin sources.

Plugin structure

Every plugin follows the same root-level layout:

my-plugin/
├── .factory-plugin/
│   └── plugin.json          # Plugin manifest (required)
├── commands/                 # Slash commands (optional)
├── skills/                   # Skills (optional)
│   └── my-skill/
│       └── SKILL.md
├── droids/                   # Custom droids (optional)
├── hooks/                    # Hook configuration and scripts (optional)
│   └── hooks.json
├── mcp.json                  # MCP server configs (optional)
└── README.md                 # Human-facing documentation

Do not put commands/, skills/, droids/, hooks/, or mcp.json inside .factory-plugin/. Only plugin.json belongs in .factory-plugin/; all plugin components live at the plugin root.

Plugin manifest

The manifest defines the plugin’s identity and display metadata.

{
  "name": "my-plugin",
  "description": "A helpful description of what this plugin does",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Field	Purpose
name	Unique plugin identifier.
description	Shown when browsing and installing the plugin.
version	Human-readable release version in the manifest.
author	Optional attribution metadata.

Droid tracks installed plugin updates by marketplace Git commit. When you update a plugin, Droid fetches the latest version from the marketplace.

Version pinning is not currently supported. Plugin updates fetch the latest marketplace version.

Plugin scopes

Choose a scope when installing a plugin:

Scope	Location	Visibility
User	~/.factory/	Available across your projects
Project	<project>/.factory/	Shared with teammates through git
Org	Managed settings	Installed through organization configuration

You can manually install user or project scoped plugins. Org-scoped plugins are controlled by organization managed settings and are installed automatically.

A plugin can only exist at one scope at a time. To change scope, uninstall it and install it again at the new scope.

Plugin hooks

Plugins can include hooks that execute at specific Droid lifecycle events. Put hook definitions in hooks/hooks.json and scripts in the same hooks/ directory.

my-plugin/
├── .factory-plugin/
│   └── plugin.json
├── hooks/
│   ├── hooks.json
│   └── format.sh
└── ...

{
  "PostToolUse": [
    {
      "matcher": "Create|Edit|ApplyPatch",
      "hooks": [
        {
          "type": "command",
          "command": "${DROID_PLUGIN_ROOT}/hooks/format.sh"
        }
      ]
    }
  ]
}

Use ${DROID_PLUGIN_ROOT} to reference files inside the installed plugin directory. See the Hooks reference for hook event schemas and security considerations.

Next steps

Plugin Marketplaces

Add official, external, local, team, and organization-managed plugin sources.

Building plugins

Create a plugin with skills, commands, droids, hooks, and MCP configuration.

Skills

Define reusable capabilities that Droid can invoke on demand.

Custom Droids

Create specialized subagents that plugins can package and distribute.