Designing Python Apis
Designs intuitive Python library APIs following principles of simplicity, consistency, and discoverability. Handles public re-exports, API evolution, deprecation, breaking changes, and error handling. Use when designing or reviewing a library API, exposing a symbol from a package __init__, or managing API versioning and deprecations.
Install
/plugin marketplace add wdm0006/python-skillsThe repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.
npx skills add wdm0006/python-skills --skill designing-python-apisgit clone --depth 1 https://github.com/wdm0006/python-skills.git /tmp/python-skills
mkdir -p ~/.claude/skills
cp -r /tmp/python-skills/skills/python/api-design ~/.claude/skills/designing-python-apisPersonal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.
From the SKILL.md
# Python API Design
## Core Principles
1. **Simplicity**: Simple things simple, complex things possible
2. **Consistency**: Similar operations work similarly
3. **Least Surprise**: Behave as users expect
4. **Discoverability**: Find via autocomplete and help
## Progressive Disclosure Pattern
```python
# Level 1: Simple functions
from mylib import encode, decode
result = encode(37.7749, -122.4194)
# Level 2: Configurable classes
from mylib import Encoder
encoder = Encoder(precision=15)
# Level 3: Low-level access
from mylib.internals import BitEncoder
```
## Naming Conventions
```python
# Actions: verbs
encode(), decode(), validate()
# Retrieval: get_*
get_user(), get_config()
# Boolean: is_*, has_*, can_*
is_valid(), has_permission()
# Conversion: to_*, from_*
to_dict(), from_json()
```
## Error Handling
```python
class MyLibError(Exception):
"""Base exception with helpful messages."""
def __init__(self, message: str, *, hint: str = None):
super().__init__(message)
self.hint = hint
# Usage
raise ValidationError(
f"Latitude must be -90 to 90, got {lat}",
hint="Did you swap latitude and longitude?"
)
```
### Fail Loud, Not Silent
The most expensive bugs are the ones where **failure is indistinguishable from
success**. A caller who gets no error assumes everything worked. These patterns
all turned a real failure into a silent wrong answer in shipped code — guard
against every one.Details
- Skill name
designing-python-apis- Repository
- wdm0006/python-skills
- Path
skills/python/api-design/SKILL.md- License
- MIT
- Repo updated
- 18 November 2026
FAQ
What does the Designing Python Apis skill do?
Designs intuitive Python library APIs following principles of simplicity, consistency, and discoverability. Handles public re-exports, API evolution, deprecation, breaking changes, and error handling. Use when designing or reviewing a library API, exposing a symbol from a package __init__, or managing API versioning and deprecations.
How do I install the Designing Python Apis skill?
Claude Code plugin: /plugin marketplace add wdm0006/python-skills. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.
Is Designing Python Apis popular?
It lives in wdm0006/python-skills, which has 115 GitHub stars and 18 forks.
Related skills
Auditing Python Security
115wdm0006/python-skills
Audits Python libraries for security vulnerabilities using Bandit, pip-audit, Semgrep, and detect-secrets. Identifies SQL injection, command injection, hardcoded credentials, secrets exposed through tracebacks, weak cryptography, and insecure deserialization. Use when reviewing library security, setting up security scanning in CI, or implementing secure coding patterns.
Building Accessible Interfaces
115wdm0006/python-skills
Makes web and app UIs usable by keyboard, screen-reader, low-vision and motion-sensitive users — semantic HTML before ARIA, labelled controls, visible focus, WCAG AA contrast measured rather than eyeballed, touch targets, reduced motion, and automated axe checks plus a manual keyboard pass in CI or before every UI PR. Use when building or restyling a screen, adding a form, modal, menu or custom control, choosing colors, or reviewing a UI change.
Building Browser Extensions
115wdm0006/python-skills
Builds and tests Manifest V3 browser extensions — service-worker message channels that survive teardown, chrome.storage read-modify-write safety, settings validation in the popup, and a Jest chrome mock that can actually fail. Use when writing or reviewing a background service worker, a popup that reads/writes chrome.storage, an extension's Jest suite, or debugging an extension whose UI silently stops responding.
Diagnose
80KerberosClaw/kc_ai_skills
Use when the user reports misbehaving software to investigate — a bug, crash, wrong output, flaky behavior, or '為什麼壞掉/不會動/查一下' — and the root cause is not yet established. Enforces building a red-capable reproduction command BEFORE any hypothesis is allowed, then 3-5 ranked falsifiable hypotheses before testing any single one. NOT for conceptual questions, code reading requests, or feature work. When a failing command already exists, Step 1 is pre-satisfied — still apply, jumping straight to the hypothesis discipline.
Deferring Heavy Dependencies
115wdm0006/python-skills
Keep expensive resources — ML models, spellcheck dictionaries, embedded databases, large third-party imports — off code paths that never use them. Covers constructor work paid by every caller, one-size factories that load the heaviest member for the cheapest request, load-and-unload-per-call masquerading as a cache, measuring per-call cost in a fresh process, telling a one-time import from a repeated model load, and the test fallout (patches that only now take effect, autouse fixtures that hide the dependency). Use when a trivially cheap operation takes hundreds of milliseconds, when adding a
Documenting Python Libraries
115wdm0006/python-skills
Creates comprehensive Python library documentation including Google-style docstrings, Sphinx setup, API references, tutorials, and ReadTheDocs configuration. Use when writing docstrings, setting up Sphinx documentation, or creating user guides for Python libraries.
Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.