System Architecture

This guide provides a deep dive into the technical architecture of the Seer Marketing Agents infrastructure. It is intended for engineers and agent builders who want to understand how the system works or extend its capabilities.

The Design Philosophy

The architecture is built on three core principles:

1. Modularity: Functionality is encapsulated in plugins that can be independently developed and versioned.
2. Progressive Disclosure: Information is loaded only when needed (via Skills and Commands) to maintain a lean context window.
3. Cross-Platform Compatibility: Built to work seamlessly on both OpenCode (primary) and Claude Code (secondary) using standardized formats.

The Layered Trifecta

The system operates through three primary layers that govern how the agent perceives and interacts with the user's request.

graph TD
    A[User Prompt] --> B[HOOKS - UserPromptSubmit]
    B --> C[SKILLS - Auto-activated]
    C --> D[COMMANDS - User-triggered]
    D --> E[HOOKS - PostToolUse / Stop]

    subgraph "core-dependencies (Operating Layer)"
    B
    E
    end

    subgraph "Division Plugins (Domain Layer)"
    C
    D
    end

1. Hooks (The Event Layer)

Hooks are automatic reactions to lifecycle events. They are centralized in the core-dependencies plugin to ensure a consistent operating environment.

• UserPromptSubmit: Fires before the agent responds. Its primary job is to scan for relevant skills and inject activation suggestions into the context.
• PostToolUse: Fires after file operations (Edit, Write). It tracks changes and maintains a "memory" of what has been modified.
• Stop: Fires when the agent thinks it is finished. This serves as a final QA checkpoint to ensure the "definition of done" is met.

2. Skills (The Behavior Layer)

Skills define how the agent thinks and behaves. They are "always-on" but modular; the agent decides when to load them based on the task context.

• Shared Skills: Standards like writing-standards and quality-standards live in core-dependencies.
• Domain Skills: Specialized methods like seo-methods live within their respective division plugins.
• Resources: Skills use a "progressive disclosure" pattern where the main SKILL.md is kept under 500 lines, with detailed methodologies stored in the resources/ subdirectory.

3. Commands (The Workflow Layer)

Commands are explicit, user-triggered workflows. While skills guide behavior, commands execute specific deliverables.

• Deliverable Commands: /content-audit, /search-landscape.
• Reasoning Commands: /chain-of-thought, /95-confidence.
• Utility Commands: /utils:help, /utils:commands.

---

Directory Structure

The repository distinguishes between Product Deliverables (the agent infrastructure) and Development Tooling.

core-dependencies

Located at plugins/core-dependencies/. This is the required operating layer.

plugins/core-dependencies/
├── hooks/                   # Activation and QA hooks
├── scripts/                 # Logic for hooks (bash/TS)
├── skills/                  # Shared standards (writing, quality)
└── commands/                # Core workflows (reasoning, diagnostic)

Division Plugins

Located at plugins/divisions/{division}/. These are "thin" plugins containing domain-specific logic.

plugins/divisions/seo/
├── .claude-plugin/          # Manifests
├── commands/                # /content-audit, etc.
├── skills/                  # Domain-specific methods only
│   └── seo-methods/
│       ├── SKILL.md
│       └── resources/       # data-analysis.md, strategy.md
└── scripts/                 # Division-specific Python algorithms

---

Feature Decision Framework

When adding new features, builders should use this framework to choose the right implementation path:

Need	Implementation	Rationale
Persistent project context	CLAUDE.md / AGENTS.md	Always loaded; best for static project rules.
User-triggered workflow	Command	Explicit invocation; best for specific deliverables.
Automatic behavior	Skill	Agent-triggered; best for standards and mental models.
Event reaction	Hook	Automatic; best for QA checks or change tracking.
External integration	MCP	API adapter; best for connecting to BigQuery, Wrike, etc.
Parallel heavy work	Subagent	Isolated context; best for complex, multi-step tasks.

Skill Activation Engine

The core-dependencies plugin provides an engine that merges activation rules from all installed plugins.

1. Each skill includes a skill-rules-fragment.json.
2. The engine merges these fragments into a master registry.
3. On every prompt, the engine checks for matches against keywords, intent patterns, and file paths.
4. If a match is found, it "nudges" the agent to load the relevant skill.

This prevents "context explosion" by only loading the specific guidelines needed for the current task.

---

Relationship to Seer AI Horizons

This infrastructure (agents-infra) serves as the backbone for Seer's AI initiatives across all Horizons:

Horizon	Focus	How agents-infra Supports
Horizon 1	Production agents & tools	Provides shared skills, MCP integrations, quality standards
Horizon 2	R&D prototypes	Enables rapid prototyping with reusable modules
Horizon 3	Future innovation	Establishes patterns and architecture for scale

Key distinction:

• agents-infra = Infrastructure and shared capabilities (this repo)
• Horizon teams = Build specific products using this infrastructure
• When R&D winners graduate to production, they leverage agents-infra patterns

This separation allows Horizon teams to move fast on product innovation while infrastructure provides the stable foundation of skills, MCP connections, and quality gates.

---

Technical Specifications

For the full technical specification, see the Plugin Architecture Spec on GitHub.