Software Design
Reducing complexity through thoughtful software design
Reduce software complexity using John Ousterhout's philosophy of deep modules, information hiding, and strategic programming. This skill helps your AI agent design interfaces that are simple on the outside and powerful on the inside.
A Philosophy of Software Design
npx skills add wondelai/skills/software-design-philosophy --global This skill is compatible with Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent, and other agentskills.io-compatible agents.
What is the Software Design skill?
One target drives everything in John Ousterhout's A Philosophy of Software Design: reducing complexity. This free skill points your agent at it too, arguing for deep modules behind simple interfaces, for hiding information rather than passing it around, and for spending design effort now instead of paying interest later.
Key concepts from A Philosophy of Software Design your agent applies
Deep vs Shallow Modules
The best modules have simple interfaces that hide significant implementation complexity — depth matters more than number of modules.
Information Hiding
Each module should encapsulate design decisions that are likely to change, exposing only what callers need to know.
Strategic vs Tactical Programming
Invest time to design clean abstractions upfront (strategic) rather than hacking quick fixes (tactical).
Define Errors Out of Existence
Design interfaces so that error conditions cannot occur, rather than handling them after the fact.
Complexity Signals
Watch for change amplification, cognitive load, and unknown unknowns — the three manifestations of complexity.
When to use Software Design — and when not to
Reach for it when
- Every new feature touches six files, which is the classic signal that your modules are too shallow.
- An interface has more parameters and special cases than the implementation behind it saves you.
- You are deciding how much design effort a new component deserves before writing it.
- You want error cases designed out of existence rather than handled in every caller.
Reach for something else when
- You need naming and function-level style rules — Clean Code is more specific and more prescriptive.
- The question is which layer owns a dependency — use Clean Architecture.
- You are modelling a complex business domain and its language — Domain-Driven Design fits better.
- You want a mechanical, catalogued transformation of existing code — that is Refactoring.
Example prompts for the Software Design skill
Evaluate whether these modules are deep or shallow and suggest improvements using software-design-philosophy skill
Design reviewRedesign this API to hide implementation complexity behind a simpler interface using software-design-philosophy skill
API designIdentify complexity signals in this codebase and propose fixes using software-design-philosophy skill
Code reviewRefactor this error handling to define errors out of existence using software-design-philosophy skill
Error handlingSoftware Design vs the other Code Quality skills
All 5 Code Quality skills are free and install the same way — the only question is which framework fits the job in front of you.
| Skill | Based on | Best for |
|---|---|---|
| Clean Code | Clean Code — Robert C. Martin | Writing readable, maintainable code |
| Pragmatic Programmer | The Pragmatic Programmer — Andrew Hunt & David Thomas | Practical software craftsmanship |
| Refactoring | Refactoring — Martin Fowler | Improving code design through systematic refactoring |
| Software Design | A Philosophy of Software Design — John Ousterhout | Reducing complexity through thoughtful software design |
| Legacy Code | Working Effectively with Legacy Code — Michael C. Feathers | Safely change untested code: seams and characterization tests |
Frequently asked questions
How do I install the Software Design skill?
Run npx skills add wondelai/skills/software-design-philosophy --global. It takes about 30 seconds and needs no account. The Software Design skill then works in Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw and Hermes Agent — anything that reads the open agentskills.io format — and your agent loads it on its own when a task calls for it. It is free and MIT-licensed, and the source is at https://github.com/wondelai/skills.
Which book is the Software Design skill based on?
It packages A Philosophy of Software Design by John Ousterhout — stanford professor, creator of Tcl/Tk, ACM Software System Award winner. The skill distils the book's method into instructions your agent follows while it works, covering deep vs shallow modules, information hiding and strategic vs tactical programming. It sits in the Code Quality part of the library.
What makes a module "deep"?
A deep module hides a lot of functionality behind a small interface — a garbage collector with no API at all is the extreme case. A shallow module is the opposite: an interface almost as complicated as the implementation, so using it costs about as much as writing it yourself. The skill treats interface-to-implementation ratio as the primary design signal, which is why it will sometimes argue against splitting a class.
Does this contradict Clean Code on small functions?
On one point, yes, and the skill does not pretend otherwise. Ousterhout argues that splitting functions purely to make them short can create shallow modules and spread complexity across more places than it removes. If you install both, expect them to disagree about a long-but-cohesive function; the skill will make the complexity argument so you can decide, rather than applying a rule silently.
What is "strategic programming" and why does it cost 10-20% more?
Strategic programming means the goal of each change is a good design, not just working code — so you spend a little extra on every commit rather than a lot on a rewrite later. Ousterhout puts the overhead at 10-20%, and the skill will flag when a shortcut is being taken tactically so the trade is deliberate rather than accidental.
Guides that use this skill
How to Create a New App with AI Skills
Read guide Deep dive · EngineeringFrom Vibe-Coded Prototype to Production-Ready Product
Read guide Deep dive · EngineeringHow to Refactor a Codebase Buried in Technical Debt
Read guide Deep dive · ArchitectureHow to Design the Best Possible Architecture for a New App
Read guideInstall Software Design
Free, open-source, and ready in 30 seconds.
npx skills add wondelai/skills/software-design-philosophy --global MIT Licensed · Works with Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent & other agentskills.io agents · No account needed
Don’t guess your AI engineering level.
Measure it.
AI Developer Scorecard
How production-grade is your AI engineering?
Twenty-five questions across the practices that separate vibe-coding from production-grade engineering. Instant score, per-section breakdown, and a 30/60/90-day playbook.
Score 0–75 · 30/60/90-day playbook Score yourself For CTOs & foundersCTO Scorecard
Is your engineering team ready for AI at scale?
Twenty-five questions on how your org adopts AI — adoption, governance, automation, and ROI. See where you sit on the path from Reactive to Strategic Leader.
Score 0–75 · Reactive → Strategic Leader Score your orgWe build the skills you already use. Now we’ll build yours.
Sprints from $3K · shipped to production, or you don’t pay the final milestone.