Software Design Patterns for AI Skills and Agents
Canonical version: 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 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 |
| 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
Related
- AI Assistant Architecture
- Harness Engineering
- AI Agent Orchestration
- AI Skill Resilience
- AI Skill Portability
- Context-as-Code
- Context Budget
- Barrel Pattern
- Pure Function
About Sébastien
Ready to get to the next level?
Found this valuable? Share it with someone who needs it.