About

Imported from markduan/a-philosophy-of-software-design-skills (SKILL.md). Install upstream with npx skills add markduan/a-philosophy-of-software-design-skills. Copyright stays with the author (MIT).

Software Design Principles

Name: a-philosophy-of-software-design-skills
Author: markduan

A comprehensive guide to software design based on "A Philosophy of Software Design" by John Ousterhout.

Description

This skill provides practical guidance for writing simple, maintainable code that minimizes complexity. It covers eight essential areas of software design:

Complexity Management - Understanding and fighting complexity through strategic programming
Deep Modules - Creating powerful abstractions with simple interfaces
Error Handling - Defining errors out of existence
Naming & Obviousness - Making code self-documenting
Documentation - Writing meaningful comments
General-Purpose Design - Building reusable, flexible modules
Design Process - Practical methodology and best practices
Consistency - Leveraging conventions to reduce cognitive load

When to Use

Use this skill when:

Designing new features or modules
Reviewing code for quality and maintainability
Refactoring existing code
Establishing team coding standards
Teaching software design principles
Making architectural decisions

Core Philosophy

The fundamental problem in software design is managing complexity. This skill teaches you to:

Think strategically, not tactically
Create deep modules with simple interfaces
Hide implementation details effectively
Eliminate special cases and exceptions
Write obvious, self-documenting code
Make continual small investments in design quality

Quick Start

Read the README for an overview
Start with 01-complexity-management.md to understand the core philosophy
Reference specific skills as needed during development
Use red flags and principles as a code review checklist

README.md - Complete overview and integration guide
QUICK-REFERENCE.md - One-page cheat sheet
INSTALLATION.md - Installation and usage guide
01-complexity-management.md - Core philosophy and strategic programming
02-deep-modules.md - Interface design and information hiding
03-error-handling.md - Eliminating exceptions and special cases
04-naming-obviousness.md - Naming conventions and code clarity
05-comments-documentation.md - Effective documentation practices
06-general-purpose-design.md - Building flexible, reusable code
07-design-process.md - Design methodology and workflow
08-consistency-conventions.md - Standards and conventions

Each skill includes:

Core principles and philosophy
Practical guidelines and examples
Good vs bad code comparisons
Red flags to watch for
Benefits and when to apply

Key Takeaways

Red Flags (signs of complexity):

Shallow modules, information leakage, pass-through methods
Vague names, hard-to-describe interfaces
Comments that repeat code
Special cases proliferating
Nonobvious code requiring extensive explanation

Design Principles:

Complexity is incremental - sweat the small stuff
Working code isn't enough - design quality matters
Modules should be deep (simple interface, powerful implementation)
Define errors out of existence
Design it twice (consider alternatives)
Comments describe what's non-obvious
Design for ease of reading, not writing

Attribution

Based on "A Philosophy of Software Design" by John Ousterhout, published by Yaknyam Press.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/markduan-a-philosophy-of-software-design-skills-a-philos-f761b4/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

markduan-a-philosophy-of-software-design-skills-a-philos-f761b4.ocm.jsonjson

{
  "ocm": "1",
  "id": "markduan-a-philosophy-of-software-design-skills-a-philos-f761b4",
  "kind": "skill",
  "name": "a-philosophy-of-software-design-skills",
  "description": "Comprehensive guide to software design based on \"A Philosophy of Software Design\" by John Ousterhout. Covers complexity management, deep modules, error handling, naming, documentation, general-purpose design, design process, and consistency conventions.",
  "publisher": "markduan",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "software-design",
      "complexity",
      "architecture",
      "best-practices",
      "code-quality",
      "github"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Comprehensive guide to software design based on \"A Philosophy of Software Design\" by John Ousterhout. Covers complexity management, deep modules, error handling, naming, documentation, general-purpose design, design process, and consistency conventions."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "github",
      "repository": "https://github.com/markduan/a-philosophy-of-software-design-skills",
      "path": "SKILL.md",
      "ref": "39ddc4b655faeb82c5feccc65780a95c7e9d5d74",
      "url": "https://github.com/markduan/a-philosophy-of-software-design-skills/blob/39ddc4b655faeb82c5feccc65780a95c7e9d5d74/SKILL.md",
      "key": "markduan/a-philosophy-of-software-design-skills/SKILL.md"
    },
    "license": "MIT"
  },
  "instructions": "# Software Design Principles\n\nA comprehensive guide to software design based on \"A Philosophy of Software Design\" by John Ousterhout.\n\n## Description\n\nThis skill provides practical guidance for writing simple, maintainable code that minimizes complexity. It covers eight essential areas of software design:\n\n1. **Complexity Management** - Understanding and fighting complexity through strategic programming\n2. **Deep Modules** - Creating powerful abstractions with simple interfaces\n3. **Error Handling** - Defining errors out of existence\n4. **Naming & Obviousness** - Making code self-documenting\n5",
  "cost": {
    "context_tokens": 845
  }
}

Fetch it by URL: GET /api/v1/registry/markduan-a-philosophy-of-software-design-skills-a-philos-f761b4/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.