Software Design Philosophy skill
software-design-philosophy-skill
Skill based on Ousterhout's software design book: deep modules, information hiding and red flags for code and design review
- 355 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- A single file of text principles: the skill runs nothing and makes no network calls
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/software-design-philosophy-skillDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- A single file of text principles: the skill runs nothing and makes no network calls
This is third-party code. Review the repository files before installing.
What it does
The software-design-philosophy skill retells John Ousterhout's book "A Philosophy of Software Design" as a reference and loads when an agent has to judge design quality. The book's central thesis: the core challenge of design is managing complexity. The file is split into fifteen sections: symptoms and causes of complexity, strategic versus tactical programming, deep and shallow modules, information hiding and leakage, general-purpose and special-purpose modules, layers of abstraction, pulling complexity downward. Next come defining errors out of existence, the design-it-twice habit, a philosophy of comments, naming, consistency and obvious code. For review there is a red-flag summary: information leakage, pass-through methods, pass-through variables, non-obvious code. The skill triggers on phrases such as "code is too complex", "how to split modules" and "reduce coupling".
Who it is for. Developers and reviewers who want an agent to notice complexity in architecture, interfaces and naming through one system of concepts.
Good fit when
- An agent reviews a pull request and you want design feedback, not just style comments
- A module keeps growing and you must decide how to split it into parts with simple interfaces
- An API or class interface is designed from scratch and two options are needed to choose from
- Code is hard to read and you want to learn whether names, pass-through layers or leaked details are to blame
- Error handling has sprawled and you need to check whether some of it can be removed by design itself
Not a fit when
- You need a linter check or formatting: the skill supplies principles, not style rules for a particular language
- You need the whole book with its examples: the file is condensed to a digest
- The fix is urgent and local: design reasoning would slow it down for nothing
Example request
Review this module against Ousterhout's principles: where the interface is shallow, where implementation details leak and what can be simplifiedLimitations
The skill is a single SKILL.md file and retells the book in its own words; it has no original code examples or chapters. It supplies principles and red flags but no tooling: there are no scripts, checks or automated code analysis. The skill does not check code itself: the agent draws conclusions from the text. A Usage Guide section at the end of the file gives rules for six cases: review, interface design, module splitting, errors, refactoring, and names and comments. The material is written in English. The last commit in the repository is dated July 2026.
How to disable. Delete the software-design-philosophy skill folder from your agent's skills folder, for example ~/.claude/skills/, and restart the session.
FAQ
How do I install the skill in Claude Code?
The README gives claude install-skill luoling8192/software-design-philosophy-skill for Claude Code. The general npx skills add luoling8192/software-design-philosophy-skill also works.
Do I still need the book if I have the skill?
The digest of principles with red flags is what the agent uses in review, while Ousterhout's examples and reasoning stay in the book, and reading it in full is still worthwhile.
Which red flags does it include?
Information leakage, pass-through methods, pass-through variables, non-obvious code and several more. They are collected in a Red Flags section with a short reference.
When does it trigger?
During code review, architecture discussions, API design, module splitting, refactoring, naming and error handling strategy. The description also lists trigger phrases such as "code is too complex" and "reduce coupling".
Does it work in Codex?
Yes. The README gives codex skills add luoling8192/software-design-philosophy-skill for Codex, and the repository holds a separate codex-skill.md file.
Discussion
No questions or reviews yet.
Related
SkillsWith rederive, the agent asks questions that help a learner reconstruct the reasoning behind a codebase’s design decisions.
A code review skill across many languages and frameworks: architecture, performance, security, anti-patterns and common bugs
Eleven skills that take an idea through requirements, spec and plan to a verified pull request with an independent review
lencx skills
lencx-skills
Two skills for Claude Code and Codex: keel works through architecture questions, coding-protocol keeps code edits inside the task
An evidence-first development skill: the agent wraps code in a spec and a gauntlet of checks so line-by-line review becomes optional
A skill that explains and audits code, telling you what it does and why instead of just accepting it
README in short
A short page: the skill's purpose, the list of situations it covers (review, architecture, API, modules, refactoring, naming, error handling), three install commands for Claude Code, Codex and Skills.sh, and the MIT license.
README badge
Original SKILL.md
--- name: software-design-philosophy description: > Software design philosophy guide based on John Ousterhout's "A Philosophy of Software Design." Use this skill during: code reviews, architecture discussions, API design, module decomposition decisions, refactoring guidance, complexity analysis, naming and commenting improvements, error handling strategy design. Trigger when the user mentions "code is too complex", "how to split modules", "interface design", "reduce coupling", "deep/shallow modules", "information leakage", "error handling", "code readability", "design philosophy", "pull complexity down", "define errors out of existence", or similar topics. Also trigger for any code review where design quality feedback is requested. --- # A Philosophy of Software Design — Distilled Guide > Source: John Ousterhout, *A Philosophy of Software Design* > Central thesis: **The core challenge of software design is managing complexity.** --- ## I. Complexity: Know the Enemy ### Definition Complexity is anything related to the structure of a software system that makes it **hard to understand and modify**. Complexity is not the same as system size — a small system can be complex, and a large well-designed system can be manageable. ### Three Symptoms of Complexity 1. **Change Amplification**: A seemingly simple change requires code modifications in many different places. 2. **Cognitive Load**: Developers must absorb a large amount of information to complete a task safely. Note: fewer lines of code ≠ simpler — sometimes more code is actually simpler because it reduces cognitive load. 3. **Unknown Unknowns**: It's unclear which code must be modified or what information is needed to complete a task. This is the most dangerous symptom. ### Two Root Causes 1. **Dependencies**: A piece of code cannot be understood or modified in isolation; it relates to other code that must also be considered. 2. **Obscurity**: Important information is not obvious — vague names, missing docs, implicit conventions, hidden constraints. ### Key Insight - **Complexity is incremental**: It's not caused by a single catastrophic error; it accumulates through thousands of small decisions. - Therefore you must adopt a **zero-tolerance** mindset — every bit of "minor" complexity matters. --- ## II. Strategic vs. Tactical Programming ### Tactical Programming (Anti-pattern) - Goal: get features working as quickly as possible. - Mindset: "Just make it work", "We'll refactor later." - Result: complexity accumulates fast, tech debt spirals out of control.