skills.rest
dallascrilley
dallascrilleyCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

implementing-modules

Implement self-contained Python modules from specifications using contract-first design.

Updated Dec 4, 2025
Search Tags:#testing#documentation#python#software architecture#modular design#contract-first#module implementation
One-click install
npx skills add https://github.com/dallascrilley/dowser --skill implementing-modules-dallascrilley
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: implementing-modules
Source: https://github.com/dallascrilley/dowser/tree/main/skills/implementing-modules
Command: npx skills add https://github.com/dallascrilley/dowser --skill implementing-modules-dallascrilley

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Building modules without clear contracts leads to leaky abstractions, tight coupling, and code that breaks when refactored. This Skill guides you to implement modules from specifications using the 'bricks and studs' philosophy, producing self-contained, regeneratable components with documented public interfaces. ## Core Features & Use Cases - Contract-First Implementation: Write the README.md contract before coding, defining inputs, outputs, errors, side effects, and performance characteristics. - Structured Module Layout: Standard directory structure with init.py public interface, core.py, models.py, tests/, examples/, and docs/ directories. - Contract & Documentation Tests: Test patterns that validate the public interface matches the specification and that docstring examples actually execute. - Use Case: Given an architecture specification for a document processor, generate a complete module with Pydantic models, typed public functions, contract tests, and a README from which the module could be regenerated. ## Quick Start Implement a self-contained Python module from my specification following the bricks and studs philosophy with a contract README and validation tests.

Frequently Asked Questions about implementing-modules

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I implement a Python module from a specification?▼

Write the contract in README.md first, defining inputs, outputs, errors, and side effects. Then create the module structure with __init__.py exposing only public functions, implement core.py, and write contract tests that validate the implementation matches the specification.

What is the bricks and studs philosophy in software design?▼

A brick is a self-contained module with one clear responsibility, and a stud is its public contract that other modules connect to. Modules stay isolated, expose only typed public interfaces, and can be regenerated from their specification without breaking callers.

How do I write contract tests for a Python module?▼

Create tests/test_contract.py that verifies all documented exports exist in __all__, no private functions are exposed, valid inputs produce the contracted output structure, and invalid inputs raise the specified error types like ValueError.

Can a module be regenerated from its README documentation?▼

Yes, if the README documents all invariants: public function signatures, data model structures, error types, side effects, and performance characteristics. Internal algorithms and private helpers can change freely as long as contract tests still pass.

What are common modular design anti-patterns to avoid?▼

Avoid leaky modules that export private internals, coupled modules that import other modules' private functions, and monster modules with multiple unrelated responsibilities. Keep internals prefixed with underscore and out of __all__.

Related Skills

Explore More Software Engineering Skills→
nodatallnodatall
2

create-architecture

Create or update repo-specific architecture boundary documentation in docs/ARCHITECTURE.md.

Community
Intermediate
cartography-cncfcartography-cncf
4.0k

create-module

Scaffold a complete Cartography intel module with sync pattern and tests.

Official
Advanced
janewilkinjanewilkin

lint

Lints Python code with ruff and checks types with mypy.

Community
Intermediate
mambo-wangmambo-wang
3

tdd

Guides test-driven development using the red-green-refactor loop with behavior-focused tests.

Community
Intermediate