# Python Design Modularity

> |-

- **Type:** Skill
- **Install:** `agentstack add skill-ahgraber-skills-python-design-modularity`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ahgraber](https://agentstack.voostack.com/s/ahgraber)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** CC0-1.0
- **Upstream author:** [ahgraber](https://github.com/ahgraber)
- **Source:** https://github.com/ahgraber/skills/tree/main/skills/python-design-modularity

## Install

```sh
agentstack add skill-ahgraber-skills-python-design-modularity
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Python Design and Modularity

## Overview

Readability-first design with explicit module contracts.
Keep control flow, data movement, and ownership boundaries visible so code stays maintainable and safe to change.

Treat these recommendations as preferred defaults.
When a default conflicts with project constraints, suggest a better-fit alternative and call out tradeoffs and compensating controls (tests, observability, migration, rollback).

## When to Use

- Restructuring modules, packages, or ownership boundaries
- Breaking apart god classes or deeply nested hierarchies
- Choosing between composition and inheritance
- Applying Functional Core / Imperative Shell separation
- Planning a refactor that touches multiple modules
- Reviewing code for readability or architectural clarity

**When NOT to use:**

- Pure performance optimization — see `python-concurrency-performance`
- Error handling and resilience patterns — see `python-errors-reliability`
- Type contracts and protocol design — see `python-types-contracts`
- One-off script or throwaway code with no maintenance horizon

## Quick Reference

- Keep control flow and data movement explicit.
- Keep module ownership and invariants explicit.
- Prefer composition by default.
- Apply Functional Core / Imperative Shell where it improves testability and separation of concerns.
- Separate behavior changes from structural refactors — never mix in the same commit.

## Common Mistakes

- **Refactoring behavior and structure simultaneously** — conflates two kinds of risk, makes rollback harder, and obscures review.
  Do one, then the other.
- **Reaching for inheritance first** — deep hierarchies couple unrelated concerns and make reasoning non-local.
  Default to composition; inherit only when the "is-a" relationship is genuinely stable.
- **Hidden module coupling** — importing implementation details across boundaries creates invisible contracts.
  Expose explicit public APIs and keep internals private.
- **Premature abstraction** — extracting a shared interface before the second or third concrete use leads to wrong abstractions that are expensive to undo.
  Wait for duplication to reveal the real seam.
- **Ignoring the Functional Core / Imperative Shell split** — mixing I/O with business logic makes unit testing painful and increases the blast radius of changes.
  Push side effects to the edges.

## Scope Note

- Treat these recommendations as preferred defaults for common cases, not universal rules.
- If a default conflicts with project constraints or worsens the outcome, suggest a better-fit alternative and explain why it is better for this case.
- When deviating, call out tradeoffs and compensating controls (tests, observability, migration, rollback).

## Invocation Notice

- Inform the user when this skill is being invoked by name: `python-design-modularity`.

## References

- `references/design-rules.md`
- `references/readability-and-complexity.md`
- `references/module-boundaries.md`
- `references/functional-core-shell.md`
- `references/refactor-guidelines.md`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ahgraber](https://github.com/ahgraber)
- **Source:** [ahgraber/skills](https://github.com/ahgraber/skills)
- **License:** CC0-1.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ahgraber-skills-python-design-modularity
- Seller: https://agentstack.voostack.com/s/ahgraber
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.