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.
npx skills add wondelai/skills/software-design-philosophy --global 
A Philosophy of Software Design John Ousterhout View on Amazon
02 What it is
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.
03 Key concepts
Five principles your agent applies.
Drawn from A Philosophy of Software Design — not advice it repeats back to you, but decisions it makes while it works.
04 Fit
When to use it, and
when not to.
four symptoms it fixes, and four it doesn't.
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.
05 Prompts
Say it like this.
Name the skill at the end of a prompt and the agent applies the framework rather than a vibe. Or say nothing — it loads on its own when a task matches.
Evaluate whether these modules are deep or shallow and suggest improvements using software-design-philosophy skill
Redesign this API to hide implementation complexity behind a simpler interface using software-design-philosophy skill
Identify complexity signals in this codebase and propose fixes using software-design-philosophy skill
Refactor this error handling to define errors out of existence using software-design-philosophy skill
06 About the author
07 Same stack
The stack it sits in.
Six Code Quality skills. Most people run two: this one, and whichever fits the next problem.
All Code Quality skills08 Questions
Before you install.
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.
09 Guides that use it
Put it to work.
Long-form playbooks where this skill does part of the job.
One skill, one command.
Install Software Design, or the whole stack.
npx skills add wondelai/skills/software-design-philosophy --global MIT licensed · Claude, Claude Code, Codex, Cursor, OpenClaw, Hermes · No account