Skip to content

System Architecture

This guide provides a deep dive into the technical architecture of the Seer Agent Engine 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 Claude Code, OpenCode, and other AI coding assistants 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.

flowchart TB
    subgraph INPUT["📥 INPUT"]
        A[/"User: Run a content audit"/]
    end

    subgraph HOOKS1["🪝 HOOKS (Before)"]
        B["UserPromptSubmit<br/>Scans for relevant skills"]
    end

    subgraph SKILLS["🧠 SKILLS (Auto-loaded)"]
        C1["writing-standards"]
        C2["seo-methods"]
        C3["quality-standards"]
    end

    subgraph COMMANDS["⚡ COMMANDS (Executed)"]
        D["/content-audit<br/>5-phase workflow"]
    end

    subgraph HOOKS2["🪝 HOOKS (After)"]
        E1["PostToolUse<br/>Track file changes"]
        E2["Stop<br/>QA checkpoint"]
    end

    subgraph OUTPUT["📤 OUTPUT"]
        F[/"Deliverable:<br/>Content Audit Report"/]
    end

    A --> B
    B --> C1 & C2 & C3
    C1 & C2 & C3 --> D
    D --> E1
    E1 --> E2
    E2 --> F

    style INPUT fill:#5050BC,color:#fff
    style OUTPUT fill:#5050BC,color:#fff
    style HOOKS1 fill:#343456,color:#fff
    style HOOKS2 fill:#343456,color:#fff
    style SKILLS fill:#5050BC,color:#fff
    style COMMANDS fill:#5050BC,color:#fff

Visual Summary

Layer Icon Trigger Purpose
Hooks (Before) 🪝 Automatic Inject context before response
Skills 🧠 Context-driven Shape behavior and standards
Commands ⚡ User-invoked Execute specific workflows
Hooks (After) 🪝 Automatic QA and tracking

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.

Skills are organized in a layered architecture:

Skill Type Purpose Auto-Load Example
Meta Skills Index of all skills in a division Yes seo-skill-index
Foundation Skills General domain knowledge Yes seo-methods, analytics-methods
Workflow Skills Command-specific methodology No (command loads) content-audit, search-landscape
Shared Skills Cross-division standards Yes writing-standards, quality-standards

Key Architecture Principle: Commands cannot have resource folders. Only skills support progressive disclosure (loading resources/ on demand). If a command needs substantial reference material (>50 lines), create a dedicated workflow skill.

  • Shared Skills: Standards like writing-standards and quality-standards live in core-dependencies.
  • Foundation Skills: Domain knowledge like seo-methods provides general techniques shared across commands.
  • Workflow Skills: Command-specific methodologies like content-audit contain the detailed process for that deliverable.
  • Meta Skills: Division indexes like seo-skill-index help discover available capabilities.
  • 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/                  # Layered skill architecture
│   ├── seo-skill-index/     # Meta skill (discovery)
│   │   └── SKILL.md
│   ├── seo-methods/         # Foundation skill (shared)
│   │   ├── SKILL.md
│   │   └── resources/       # data-analysis.md, strategy.md
│   ├── content-audit/       # Workflow skill (command-specific)
│   │   ├── SKILL.md
│   │   └── resources/       # methodology.md (2500+ lines)
│   ├── search-landscape/    # Workflow skill
│   ├── content-gap/         # Workflow skill
│   └── quick-wins/          # Workflow skill
└── scripts/                 # Division-specific Python algorithms

Note: Each major command has its own dedicated workflow skill containing the full methodology. General techniques shared across commands remain in the foundation skill (seo-methods).

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.

flowchart LR
    subgraph PLUGINS["📦 Installed Plugins"]
        P1["seo-methods<br/>skill-rules-fragment.json"]
        P2["writing-standards<br/>skill-rules-fragment.json"]
        P3["quality-standards<br/>skill-rules-fragment.json"]
    end

    subgraph ENGINE["⚙️ Activation Engine"]
        M["Merged Registry"]
        C{"Match Check"}
    end

    subgraph PROMPT["💬 User Prompt"]
        U["'Create a content audit'"]
    end

    subgraph RESULT["✅ Activated Skills"]
        R["writing-standards ✓<br/>seo-methods ✓"]
    end

    P1 & P2 & P3 --> M
    M --> C
    U --> C
    C -->|"Keywords match"| R

    style PLUGINS fill:#343456,color:#fff
    style ENGINE fill:#5050BC,color:#fff
    style RESULT fill:#54DEDB,color:#343456

How it works:

  1. Each skill includes a skill-rules-fragment.json with activation triggers
  2. The engine merges all fragments into a master registry
  3. On every prompt, the engine checks for matches against:
    • Keywords: ["audit", "content", "deliverable"]
    • Intent patterns: "(create|write).*(audit|report)"
    • File paths: "**/deliverables/**"
  4. Matched skills are suggested to the agent

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.

Explanation

Reference

How-To

Features

Tutorials