# Python Design

Python design patterns for CLI scripts and utilities, type-first development, deep...

- Repository: https://github.com/mindfold-ai/Trellis (15078 stars)
- Category: Design
- License: AGPL-3.0
- Last updated: 2026-09-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mindfold-ai/Trellis --skill python-design -g -a claude-code -y`
Codex: `npx skills add mindfold-ai/Trellis --skill python-design -g -a codex -y`
Cursor: `npx skills add mindfold-ai/Trellis --skill python-design -g -a cursor -y`
Gemini CLI: `npx skills add mindfold-ai/Trellis --skill python-design -g -a gemini-cli -y`

## Description

Python design patterns for CLI scripts and utilities, type-first development, deep modules, complexity management, and red flags. Use when reading, writing, reviewing, or refactoring Python files, especially in .trellis/scripts/ or any CLI/scripting context. Also activate when planning module structure, deciding where to put new code, or doing code review.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Python Design for CLI Scripts

Design patterns and principles for writing maintainable Python CLI tools and utilities.
Based on *A Philosophy of Software Design* (Ousterhout), adapted for scripting contexts.

## When to Activate

- Writing or modifying Python files
- Planning module decomposition
- Code review of Python changes
- Refactoring scripts that feel "messy"
- Adding a new subcommand or utility function

## Core Thesis

**The central challenge is managing complexity, not adding features.**

Complexity is anything that makes code hard to understand or modify. It has three symptoms:

1. **Change Amplification**, A small change requires edits in many places
2. **Cognitive Load**, You must hold too much context to make a safe change
3. **Unknown Unknowns**, You don't know what you don't know (the most dangerous)

Complexity is incremental. It accumulates through hundreds of small decisions, not one catastrophic mistake. Therefore: **sweat the small stuff**.

---

## Principle 1: Deep Modules

A module's value is the ratio of functionality hidden vs. interface exposed.

```
Deep module (good):          Shallow module (bad):
┌──────────┐                 ┌──────────────────────────┐
│ simple   │                 │ complex interface        │
│ interface│                 │ many params, many methods │
├──────────┤                 ├──────────────────────────┤
│          │                 │                          │
│  rich    │                 │  thin implementation     │
│  impl    │                 │                          │
│          │                 └──────────────────────────┘
│          │
└──────────┘
```

**Practical test**: If a caller must understand how the module works internally to use it correctly, the module is too shallow.

### Example: Task Data Access

The rest: https://github.com/mindfold-ai/Trellis/blob/HEAD/.agents/skills/python-design/SKILL.md