# Python Types Contracts

> |-

- **Type:** Skill
- **Install:** `agentstack add skill-ahgraber-skills-python-types-contracts`
- **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-types-contracts

## Install

```sh
agentstack add skill-ahgraber-skills-python-types-contracts
```

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

## About

# Python Types and Contracts

## Overview

Treat type hints as interface design, not decoration.
Focus on explicit contracts, stable public APIs, and boundary-safe modeling.

These are preferred defaults for common cases, not universal rules.
When a default conflicts with project constraints, suggest a better-fit alternative and explain tradeoffs and compensating controls.

## When to Use

- Public API signatures lack type annotations or use overly broad types.
- Pydantic models are scattered throughout internal logic instead of at trust boundaries.
- Contract changes risk breaking downstream consumers without migration paths.
- Interfaces accept `Any`, `object`, or untyped dicts where narrower types apply.
- Schema boundaries between layers (API, DB, domain) are implicit or inconsistent.
- Adding or evolving protocols, abstract base classes, or structural subtyping.

**When NOT to use:**

- Pure implementation-level code with no public interface.
- Throwaway scripts or one-off data munging where type rigor adds no value.
- Performance-critical inner loops where typing overhead matters more than safety.

## Quick Reference

- Type public APIs and keep contracts explicit.
- Prefer narrow interfaces and boundary protocols over broad parameter types.
- Use pydantic at trust boundaries by default, not everywhere.
- Make compatibility and migration impact explicit for any contract change.
- Favor `Protocol` for structural subtyping over deep inheritance hierarchies.
- Return concrete types from public functions; accept protocols or unions as inputs.

## Common Mistakes

- **Typing everything identically.**
  Internal helpers don't need the same rigor as public APIs.
  Over-annotating private code adds noise without safety.
- **Pydantic everywhere.**
  Using pydantic models for internal data flow instead of reserving them for validation at trust boundaries (API ingress, config loading, external data).
- **Broad return types.**
  Returning `Any` or `dict` from public functions forces callers to guess structure.
  Return concrete types or TypedDicts.
- **Breaking contracts silently.**
  Changing function signatures, removing fields, or narrowing accepted types without versioning, deprecation warnings, or migration notes.
- **Ignoring `None`.**
  Omitting `Optional` or union with `None` when a value can legitimately be absent, hiding null-safety bugs until runtime.

## 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/typing-policy.md`
- `references/contract-evolution.md`
- `references/pydantic-boundaries.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-types-contracts
- 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%.