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.
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
I'm Sébastien Dubois, and I'm on a mission to help knowledge workers escape information overload. After 20+ years in IT and seeing too many brilliant minds drowning in digital chaos, I've decided to help people build systems that actually work. Through the Knowii Community, my courses, products & services and my Website/Newsletter, I share practical and battle-tested systems.
I write about Knowledge Work, Personal Knowledge Management, Note-taking, Lifelong Learning, Personal Organization, Productivity, and more. I also craft lovely digital products and tools.
If you want to follow my work, then become a member and join our community.
Ready to get to the next level?
If you're tired of information overwhelm and ready to build a reliable knowledge system:
- 📚 KM for Beginners — 10+ hours of structured video lessons
- 🚀 Obsidian Starter Kit — Ready-made vault with 40+ templates
- 💼 Knowledge Worker Kit — Complete guides + lifetime community
- 🦉 1-on-1 Coaching — Personalized guidance
- 🎯 Join Knowii — Community + ALL courses & tools
Found this valuable? Share it with someone who needs it.