# Software Design Patterns for AI Skills and Agents Software architecture principles transfer to AI skill and agent design with minimal translation. Skills behave like [[Pure Function|pure functions]]. Agents behave like microservices. The system forms a dependency graph governed by the same principles that make software maintainable. ## Principle mapping | Principle | Software meaning | AI skill/agent equivalent | |-----------|-----------------|--------------------------| | [[Atomicity]] / SRP | One class, one job | One skill, one purpose | | Open/Closed | Extend without modifying | Progressive disclosure; reference files extend without touching SKILL.md | | Liskov Substitution | Swap implementations safely | Any "search" skill works where another search skill works | | Interface Segregation | No forced dependencies | DEPENDENCIES.md Always/OnTrigger/Never tiers; context loaders as opt-in modules | | Dependency Inversion | Depend on abstractions | "Search the vault" not "call qmd with these flags" | | [[Composition over Inheritance]] | Build from parts | Chain/layer skills; agent teams compose specialist agents | | [[Loose Coupling]] | Minimal interdependency | Skills declare deps explicitly; agents have clear boundaries | | [[High Cohesion]] | Related logic stays together | All vault-search logic in one skill, not scattered | | [[Don't Repeat Yourself (DRY) principle\|DRY]] | No duplication | [[Barrel Pattern]] meta-skills eliminate repeated context loading | | [[Idempotency]] | Safe to run twice | Skills produce same structure given same input | | [[Design by Contract]] | Explicit interfaces | Skills declare input expectations and output shape | | [[Fail Fast]] | Detect errors early | Skills check preconditions before doing work | | [[Convention over Configuration]] | Sensible defaults | Consistent skill/agent folder structure reduces boilerplate | ## Structural analogies | Software concept | AI system equivalent | |-----------------|---------------------| | npm package / module | Skill folder with SKILL.md | | Barrel file (`index.ts`) | Meta-skill that loads a cluster of dependencies | | TypeScript interface | Skill input/output contract | | Microservice | Agent with SOUL.md + DEPENDENCIES.md | | Service mesh + discovery | Agent registry + [[Receptionist AI Design Pattern]] | | Cross-functional squad | [[AI Agent Panels]] / agent team | | Dependency injection | Context loaders loaded at runtime via [[Prompt Lazy Loading AI Design Pattern (PLL)]] | | Facade | [[Barrel Pattern]] meta-skill hiding cluster complexity | | Strategy pattern | Swappable search implementations behind same interface | | Mediator | Receptionist agent routing requests | | Chain of Responsibility | Agent pipeline with handoff protocol | ## The two graphs **Skill dependency graph**: a [[Directed Acyclic Graph (DAG)]] where skills depend on 0-n other skills. Skills sharing dependencies form clusters. Clusters use barrel meta-skills to load shared context. **Agent collaboration graph**: a directed graph where agents delegate to, review for, and hand off to each other. Unlike skills (which compose via dependency), agents compose via collaboration. Clusters of collaborating agents form teams. ## Key insight Skills are functions. Agents are services. The same forces that drove software from monoliths to microservices are driving AI from monolithic prompts to composed skill-agent systems. The patterns that made that transition manageable in software apply directly here. ## References - [[SOLID Principles]] - [[AI Skill Composability]] - [[AI Skill Best Practices]] - [[Agent System Engineering]] ## Related - [[AI Assistant Architecture]] - [[Harness Engineering]] - [[AI Agent Orchestration]] - [[AI Skill Resilience]] - [[AI Skill Portability]] - [[Context-as-Code]] - [[Context Budget]] - [[Barrel Pattern]] - [[Pure Function]]