|
| 1 | +--- |
| 2 | +description: "Configure ECA plugins: load external skills, agents, commands, rules, hooks, MCP servers and config overrides from git repos or local paths." |
| 3 | +--- |
| 4 | + |
| 5 | +# Plugins / Marketplace |
| 6 | + |
| 7 | +Plugins let you share and reuse ECA configuration across projects and teams. A plugin source is a git repository or local directory containing a **marketplace** of plugins, each providing any combination of skills, agents, commands, rules, hooks, MCP servers, and config overrides. |
| 8 | + |
| 9 | +## How it works |
| 10 | + |
| 11 | +```mermaid |
| 12 | +flowchart TD |
| 13 | + A[ECA has a 'plugins' in config.json] --> B{Git URL or local path?} |
| 14 | + B -->|git| C[Clone to ~/.eca/cache/plugins] |
| 15 | + B -->|local| D[Use directory directly] |
| 16 | + C --> E[Read .eca-plugin/marketplace.json] |
| 17 | + D --> E |
| 18 | + E --> F[Read plugins from 'autoInstall'] |
| 19 | + F --> G[Merge into final ECA config] |
| 20 | +``` |
| 21 | + |
| 22 | +1. You register one or more **sources** (git URL or local path) and list plugin names in **`autoInstall`**. |
| 23 | +2. ECA resolves each source — cloning git repos to a local cache or using the local path directly. |
| 24 | +3. Each source provides a **marketplace** (`.eca-plugin/marketplace.json`) listing its available plugins. |
| 25 | +4. ECA matches `autoInstall` names against the marketplace, then **discovers components** from each matched plugin directory. |
| 26 | +5. All components are **merged** into the config waterfall — user config always takes precedence on conflicts. |
| 27 | + |
| 28 | +## Pointing to a plugin source / marketplace |
| 29 | + |
| 30 | +Add a `plugins` key to your config with one or more named sources and an `autoInstall` array: |
| 31 | + |
| 32 | +=== "Git source" |
| 33 | + |
| 34 | + ```javascript title="~/.config/eca/config.json" |
| 35 | + { |
| 36 | + "plugins": { |
| 37 | + "my-org": { |
| 38 | + "source": "https://github.com/my-org/eca-plugins.git" |
| 39 | + }, |
| 40 | + "autoInstall": ["code-review", "security-scanner"] |
| 41 | + } |
| 42 | + } |
| 43 | + ``` |
| 44 | + |
| 45 | +=== "Local path (for development)" |
| 46 | + |
| 47 | + ```javascript title=".eca/config.json" |
| 48 | + { |
| 49 | + "plugins": { |
| 50 | + "local-dev": { |
| 51 | + "source": "/home/user/my-eca-plugins" |
| 52 | + }, |
| 53 | + "autoInstall": ["my-plugin"] |
| 54 | + } |
| 55 | + } |
| 56 | + ``` |
| 57 | + |
| 58 | +=== "Multiple sources" |
| 59 | + |
| 60 | + ECA searches all registered sources when resolving `autoInstall` entries: |
| 61 | + |
| 62 | + ```javascript title="~/.config/eca/config.json" |
| 63 | + { |
| 64 | + "plugins": { |
| 65 | + "company": { |
| 66 | + "source": "https://github.com/company/eca-plugins.git" |
| 67 | + }, |
| 68 | + "community": { |
| 69 | + "source": "https://github.com/community/shared-plugins.git" |
| 70 | + }, |
| 71 | + "autoInstall": ["company-standards", "linter-setup", "shared-skills"] |
| 72 | + } |
| 73 | + } |
| 74 | + ``` |
| 75 | + |
| 76 | +## Creating a plugin source (Plugins marketplace) |
| 77 | + |
| 78 | +A plugin source is a directory (typically a git repo) with a `.eca-plugin/marketplace.json` file that lists available plugins. |
| 79 | + |
| 80 | +### Marketplace file |
| 81 | + |
| 82 | +```json title=".eca-plugin/marketplace.json" |
| 83 | +{ |
| 84 | + "plugins": [ |
| 85 | + { |
| 86 | + "name": "code-review", |
| 87 | + "description": "Agents and skills for thorough code review", |
| 88 | + "source": "plugins/code-review" |
| 89 | + }, |
| 90 | + { |
| 91 | + "name": "security-scanner", |
| 92 | + "description": "Security-focused rules and hooks", |
| 93 | + "source": "plugins/security-scanner" |
| 94 | + } |
| 95 | + ] |
| 96 | +} |
| 97 | +``` |
| 98 | + |
| 99 | +Each plugin entry has: |
| 100 | + |
| 101 | +| Field | Description | |
| 102 | +|-------|-------------| |
| 103 | +| `name` | Unique plugin name (used in `autoInstall`) | |
| 104 | +| `description` | Human-readable description | |
| 105 | +| `source` | Relative path from the repo root to the plugin directory | |
| 106 | + |
| 107 | +### Plugin directory structure |
| 108 | + |
| 109 | +Each plugin directory can contain any combination of: |
| 110 | + |
| 111 | +``` |
| 112 | +plugins/code-review/ |
| 113 | +├── skills/ |
| 114 | +│ └── review-checklist/ |
| 115 | +│ └── SKILL.md |
| 116 | +├── agents/ |
| 117 | +│ └── reviewer.md |
| 118 | +├── commands/ |
| 119 | +│ └── review.md |
| 120 | +├── rules/ |
| 121 | +│ └── code-standards.md |
| 122 | +├── hooks/ |
| 123 | +│ └── hooks.json |
| 124 | +├── .mcp.json |
| 125 | +└── eca.json |
| 126 | +``` |
| 127 | + |
| 128 | +| Path | What it provides | Details | |
| 129 | +|------|-----------------|---------| |
| 130 | +| `skills/` | Skill definitions | Each subfolder follows the [agentskills.io](https://agentskills.io/) spec with a `SKILL.md` | |
| 131 | +| `agents/*.md` | Agent definitions | Markdown files with YAML frontmatter, same format as local agents | |
| 132 | +| `commands/*.md` | Custom commands | Markdown command files, same format as local commands | |
| 133 | +| `rules/**` | Rule files | Any files under `rules/` are loaded as rules | |
| 134 | +| `hooks/hooks.json` | Hooks | ECA hook format or Claude Code hook format (auto-translated) | |
| 135 | +| `.mcp.json` | MCP server definitions | Standard `{"mcpServers": {...}}` format | |
| 136 | +| `eca.json` | Config overrides | Arbitrary ECA config keys deep-merged into config | |
| 137 | + |
| 138 | +All paths are optional — include only what your plugin needs. |
| 139 | + |
| 140 | +=== "Skill-only plugin" |
| 141 | + |
| 142 | + ``` |
| 143 | + plugins/gif-maker/ |
| 144 | + └── skills/ |
| 145 | + └── gif-generator/ |
| 146 | + ├── SKILL.md |
| 147 | + └── scripts/ |
| 148 | + └── generate.py |
| 149 | + ``` |
| 150 | + |
| 151 | +=== "Hooks + MCP plugin" |
| 152 | + |
| 153 | + ``` |
| 154 | + plugins/security-scanner/ |
| 155 | + ├── hooks/ |
| 156 | + │ └── hooks.json |
| 157 | + └── .mcp.json |
| 158 | + ``` |
| 159 | + |
| 160 | +=== "Config overrides only" |
| 161 | + |
| 162 | + ``` |
| 163 | + plugins/team-defaults/ |
| 164 | + └── eca.json |
| 165 | + ``` |
| 166 | + |
| 167 | +=== "Full plugin" |
| 168 | + |
| 169 | + ``` |
| 170 | + plugins/company-standards/ |
| 171 | + ├── skills/ |
| 172 | + │ └── internal-api/ |
| 173 | + │ └── SKILL.md |
| 174 | + ├── agents/ |
| 175 | + │ └── reviewer.md |
| 176 | + ├── commands/ |
| 177 | + │ └── deploy.md |
| 178 | + ├── rules/ |
| 179 | + │ └── coding-standards.md |
| 180 | + ├── hooks/ |
| 181 | + │ └── hooks.json |
| 182 | + ├── .mcp.json |
| 183 | + └── eca.json |
| 184 | + ``` |
| 185 | + |
| 186 | +### Hook format |
| 187 | + |
| 188 | +Plugins support both ECA native hook format and Claude Code hook format. Claude Code hooks are automatically translated: |
| 189 | + |
| 190 | +=== "ECA format" |
| 191 | + |
| 192 | + ```json title="hooks/hooks.json" |
| 193 | + { |
| 194 | + "my-hook": { |
| 195 | + "type": "preToolCall", |
| 196 | + "matcher": "eca__shell_command", |
| 197 | + "actions": [ |
| 198 | + { |
| 199 | + "type": "shell", |
| 200 | + "shell": "echo 'checking tool call...'" |
| 201 | + } |
| 202 | + ] |
| 203 | + } |
| 204 | + } |
| 205 | + ``` |
| 206 | + |
| 207 | +=== "Claude Code format (auto-translated)" |
| 208 | + |
| 209 | + ```json title="hooks/hooks.json" |
| 210 | + { |
| 211 | + "hooks": { |
| 212 | + "PreToolUse": [ |
| 213 | + { |
| 214 | + "matcher": "eca__shell_command", |
| 215 | + "hooks": [ |
| 216 | + { |
| 217 | + "type": "command", |
| 218 | + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/check.sh" |
| 219 | + } |
| 220 | + ] |
| 221 | + } |
| 222 | + ] |
| 223 | + } |
| 224 | + } |
| 225 | + ``` |
| 226 | + |
| 227 | +The `${CLAUDE_PLUGIN_ROOT}` variable is replaced with the plugin's absolute path at load time. |
| 228 | + |
| 229 | +| Claude Code Event | ECA Event | |
| 230 | +|-------------------|-----------| |
| 231 | +| `PostToolUse` | `postToolCall` | |
| 232 | +| `PreToolUse` | `preToolCall` | |
| 233 | +| `UserPromptSubmit` | `preRequest` | |
0 commit comments