qte77 Designing MAS Plugins
Target: $ARGUMENTS
When to Use
Trigger this skill when:
- Designing agent plugins or evaluation components
- Planning pipeline architecture
- Architecting new metrics or evaluation tiers
- Refactoring engines into plugin patterns
Core Principles
Plugins follow six principles. For worked code examples of each, see
references/core-principles-with-examples.md.
- Stateless Reducer —
evaluate(context) -> resultas a pure function; no side effects, no shared state - Own Context Window — plugin manages its own context; no global state access
- Structured Outputs — all data uses validated models, no raw dicts
- Own Control Flow — plugin handles its own errors and timeouts
- Compact Errors — structured partial results, not exceptions
- Single Responsibility — one metric or tier per plugin
Plugin Design Checklist
Before implementing a plugin, verify:
- Stateless: No class attributes, no global state
- Own Context: All inputs via
evaluate()parameter - Typed I/O: Validated models for inputs and outputs
- Own Errors: Returns error results, doesn't raise
- Own Timeout: Respects configured timeout
- Single Responsibility: One metric or tier
- Explicit Context: Filters output for next stage
- Env Config: All config via env vars / settings
- Observable: Emits structured logs for debugging
- Graceful Degradation: Partial results on failures
Anti-Patterns
- Shared State:
self.cache = {}(breaks stateless) - Raw Dicts:
return {"score": 0.5}(use models) - Raising Exceptions:
raise ValueError()(return error) - Global Access:
config.get_global()(use settings) - Implicit Context: Passing entire result to next tier
- Multiple Responsibilities: One plugin, 3 metrics
Implementation Template
See references/plugin-implementation-template.md for the full EvaluatorPlugin abstract base class and a worked MyPlugin example with typed context/result models, error handling, and next-tier context filtering.
Testing Strategy
See references/plugin-testing-strategy.md for isolation test patterns — happy path and structured-error-handling tests using mocked context.
References
references/mas-design-principles.md— foundational design principles (existing)references/core-principles-with-examples.md— code examples for each of the six core principlesreferences/plugin-implementation-template.md— fullEvaluatorPlugin+MyPlugintemplatereferences/plugin-testing-strategy.md— isolation test patterns