Skip to content

Plugin Authoring Guide

This guide walks you through creating a new division plugin for the Seer Marketing Agents system.

Overview

A division plugin (e.g., SEO, Analytics, Paid Media) is a domain-specific extension that provides specialized workflows and methodologies. All division plugins are "thin", meaning they inherit shared standards and activation logic from core-dependencies.

1. Directory Structure

Create the following structure for your new division:

mkdir -p plugins/divisions/{division}/.claude-plugin
mkdir -p plugins/divisions/{division}/commands
mkdir -p plugins/divisions/{division}/skills/{division}-methods/resources

2. Manifest Setup

Every plugin must have a plugin.json manifest. The most critical requirement is declaring the dependency on core-dependencies.

Create plugins/divisions/{division}/.claude-plugin/plugin.json:

{
  "name": "your-division-name",
  "version": "1.0.0",
  "description": "Domain-specific workflows for {division}",
  "dependencies": {
    "plugins": [
      {
        "name": "core-dependencies",
        "version": ">=1.0.0",
        "required": true
      }
    ]
  }
}

3. Creating Commands

Commands are the primary way users interact with your plugin. Each command should represent a single, clear deliverable.

  • Path: plugins/divisions/{division}/commands/{command}.md
  • Discovery: Use the /utils:help and /utils:commands pattern (copy from the SEO plugin).

Command Frontmatter Template

---
name: command-name
description: "Brief one-line description for discovery"
skills: [division-methods]
mcp: [optional-dependencies]
version: 1.0.0
---

# Command Title

[Workflow instructions for the agent]

4. Creating Skills

Skills define the mental models and domain standards for your division.

  • Path: plugins/divisions/{division}/skills/{division}-methods/SKILL.md
  • Pattern: Keep the main skill file under 500 lines. Use the resources/ directory for deep-dive methodologies.

Skill Activation

To enable automatic activation, add a skill-rules-fragment.json to your skill directory:

{
  "{division}-methods": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "high",
    "promptTriggers": {
      "keywords": ["keyword1", "keyword2"],
      "intentPatterns": ["(action).*(topic)"]
    },
    "fileTriggers": {
      "pathPatterns": ["**/division-specific-path/**"]
    }
  }
}

5. Golden Rules for Builders

  1. Don't Duplicate Standards: If it's about tone, quality, or general writing, it belongs in core-dependencies.
  2. One Command = One Deliverable: Avoid "god commands" that do everything. Split them into logical outputs.
  3. Graceful Degradation: If your command requires an MCP server, check for its availability first and provide clear instructions if it's missing.
  4. Use Subagents for Heavy Lifting: If a task requires processing massive amounts of data or parallel work, delegate it to a subagent.

6. Testing Your Plugin

  1. Register the Plugin: Add it to .claude-plugin/marketplace.json.
  2. Verify Activation: Use /core:doctor activation-test "triggering phrase" to ensure your skills load.
  3. Run End-to-End: Execute your commands and verify the output matches the expected deliverable quality.

Reference Implementation

See plugins/divisions/seo/ for the production-standard implementation of this architecture.