api-design_skill

Overview

This skill designs intuitive Python library APIs focused on simplicity, consistency, and discoverability. It helps create progressive interfaces that expose simple defaults, configurable classes, and low-level primitives as needed. Use it to shape naming, error handling, deprecation, and API evolution so your library feels natural to use and easy to maintain.

How this skill works

The skill inspects API shapes and recommends patterns: top-level convenience functions for common cases, configurable objects for advanced use, and clear low-level modules for power users. It applies naming conventions (verbs for actions, get_ for retrieval, is_/has_ for booleans, to_/from_ for conversions), checks for anti-patterns, and generates deprecation and error-handling templates. It also produces a review checklist and migration guidance for breaking changes and versioning.

When to use it

• Designing new library APIs to maximize ergonomics and discoverability
• Reviewing an existing API to improve consistency and reduce surprises
• Defining deprecation notices and migration paths during API evolution
• Auditing error handling and exception classes for clarity and context
• Preparing a public release and documenting expected usage patterns

Best practices

• Favor simple top-level helpers, escalate to configurable classes, then expose low-level internals for advanced control
• Choose self-documenting names and consistent verb/noun patterns across the surface area
• Avoid boolean-flag overloads; prefer keyword arguments with descriptive names
• Use immutable-safe defaults (None instead of mutable containers) and make keyword-only where appropriate
• Provide custom exceptions with contextual messages and optional hints to aid debugging
• Emit DeprecationWarning with clear replacement guidance and stacklevel=2 for actionable warnings

Example use cases

• Create a minimal encode()/decode() surface for everyday use, plus an Encoder class for advanced tuning
• Refactor a module that uses positional boolean flags into explicit keyword parameters
• Design exception hierarchy with a shared base exception and per-case subclasses that include hints
• Implement a deprecation wrapper that warns and forwards to the new API while documenting migration steps
• Run the review checklist on a library prior to a major version bump to catch inconsistency and breaking-change risks