From grimoire
Applies the Unix philosophy (single responsibility, clean interfaces) when designing tools, services, CLIs, or modules. Helps refactor coupled components and improve testability.
How this skill is triggered — by the user, by Claude, or both
Slash command
/grimoire:apply-unix-philosophyThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Build components that do one thing well and connect to others through clean, standard interfaces.
Build components that do one thing well and connect to others through clean, standard interfaces.
Adopted by: Unix/Linux operating system (foundational design since 1970s); Go toolchain (each go subcommand is a focused tool); Docker/container ecosystem (one process per container); AWS Lambda (single handler function per event); Kubernetes (single-purpose controllers). The Unix philosophy is the design principle behind every successful composable platform.
Impact: McIlroy's original formulation — "Write programs that do one thing and do it well. Write programs to work together. Write programs to handle text streams" — became the model for how 60+ years of Unix tools remained independently useful while combining into arbitrarily complex pipelines. A study of Unix tool longevity vs. monolithic application platforms shows tools following this philosophy (awk, sed, grep, curl) are still in active use decades later; monolithic alternatives have been replaced multiple times.
Why best: The competing approach — a component that accumulates features over time — optimizes for short-term convenience at the cost of long-term reusability. When a component does two things, you cannot use it in contexts where only one is needed. When a component does ten things, it can only be used by callers who accept all ten. The Unix philosophy is the only design approach with a 60-year track record of producing reusable, replaceable software components.
Sources: McIlroy, Pinson & Tague, "UNIX Time-Sharing System: Forward" (Bell Labs, 1978); Raymond, "The Art of Unix Programming" (Addison-Wesley, 2003); Dan North, "CUPID—for joyful coding" (2022)
Status: Emerging — the Unix philosophy itself is proven; its framing as a CUPID property by Dan North (2022) is gaining traction but not yet majority-adopted under this label.
Before writing a line of code, state what the component does in a single sentence with a single verb and no conjunctions.
If you cannot write this sentence, the scope is not yet clear. Clarify before building.
A component that speaks a standard language (HTTP, stdin/stdout, files, queues) can be combined with anything. A component with a bespoke integration protocol can only be combined with what was designed alongside it.
# Bad — bespoke format, tied to this ecosystem
my-tool --input-json '{"records": [...]}' --output-db postgres://...
# Good — standard streams; composes with any Unix tool
cat records.csv | my-tool | psql -c "COPY table FROM STDIN"
When two concerns appear in one component, find the interface between them and extract it.
Signal: a change to feature A breaks feature B. Signal: testing feature A requires setting up feature B's state.
# Bad — fetching and processing fused; can't test processing without HTTP
def get_and_process_orders(user_id):
response = requests.get(f"/api/users/{user_id}/orders")
orders = response.json()
return [o for o in orders if o["status"] == "pending"]
# Good — separated; each function has one purpose
def fetch_orders(user_id) -> list[dict]:
return requests.get(f"/api/users/{user_id}/orders").json()
def filter_pending(orders: list[dict]) -> list[dict]:
return [o for o in orders if o["status"] == "pending"]
# Caller composes them
pending = filter_pending(fetch_orders(user_id))
The strongest pressure against the Unix philosophy is convenience: "while we're here, let's also handle X." Each addition makes the component slightly less reusable.
Apply the single-purpose test before every feature addition:
If a component truly does one thing, you can test it with no external setup. If setup requires mocking three other systems, the component is doing more than one thing.
// Bad — handler mixes auth, business logic, and persistence; test needs all three
func HandleCreateOrder(w http.ResponseWriter, r *http.Request) {
user := auth.GetCurrentUser(r) // auth concern
order := parseOrder(r.Body) // parsing concern
db.Save(order) // persistence concern
notify.SendConfirmation(user, order) // notification concern
}
// Good — each concern is a function with one clear input/output; each is testable alone
func ParseOrder(body io.Reader) (Order, error) { ... }
func ValidateOrder(o Order) error { ... }
func SaveOrder(store OrderStore, o Order) error { ... }
Confusing "one thing" with "one line." A single purpose can involve multiple steps. validate-payment can check amount, currency, and card presence — all in service of one goal. The test is not "how many operations" but "how many reasons would this change?"
Splitting too fine. A two-line utility function does not need to be a separate service. The Unix philosophy applies at the level where independent reuse and independent replacement are meaningful. Micro-splitting functions produces noise, not clarity.
Bespoke interfaces. A component that does one thing but requires a custom protocol to call it is not Unix-philosophy-compliant — it can only be combined with what knows its protocol. Standard interfaces are the other half of the principle.
npx claudepluginhub jeffreytse/grimoire --plugin grimoireDesigns software in small, focused units with minimal surface areas that can be combined freely without knowing each other's internals. Applicable when units are hard to reuse independently or replacements require touching many files.
Records architectural decisions (ADRs) and reviews PRs/proposals using UNIX philosophy principles and computer science fundamentals for simplicity, composability, and trade-off analysis.
Applies Python design principles like KISS, SRP, composition over inheritance, and Rule of Three for designing services, refactoring monoliths, reducing coupling, and improving testability.