Creating Packages

Creating Packages

For atopile syntax, interfaces, and design patterns, see the ato-language skill. For build workflow and debugging, see build-and-test.

Search Before You Create

Writing a new part/driver is the last resort. Stop as soon as you find something usable.

1. The atopile registry — use the find_packages / inspect_package MCP tools, or browse packages.atopile.io. Install with ato dependencies add (e.g. atopile/usb-connectors).

1. Packages you can vendor — other repos and your own past projects often have a driver for the same IC. Copy it into a local packages/ directory and reference it via type: file in ato.yaml. Review and adapt — vendored packages may carry application-specific assumptions.

1. Local shared packages — check the project's own packages/ (or equivalent) for something already vendored.

1. Create new — only if nothing above works. Use ato create part to generate the footprint/symbol + a .ato stub from a JLCPCB search, then write the driver around it.

Package Conventions

These conventions keep packages predictable and reviewable. Adapt the exact namespace to your project.

• Naming: - (e.g. ti-bq25756, microchip-emc2101).
• Identifier: / in ato.yaml's package.identifier (the namespace is your project/org slug).
• hide_designators: true on build targets — designators are assigned at the consuming board level, not in the package.
• Two-file pattern:
• The driver (.ato) contains the reusable, configurable module that consumers import.
• A separate test.ato instantiates it in one specific configuration, connects all interfaces, and adds assertions that verify that configuration. Consumers import from the driver, never from the test.
• Layout: /ato.yaml, .ato (driver — importable), test.ato (build validation + design verification), parts/ (footprint/symbol/step files).
• Verification status: every public module's docstring should declare its lifecycle state, updated as the module progresses:
• UNVERIFIED — design complete, builds clean, not yet fabricated or tested
• BUILT — PCB fabricated, not yet powered or tested
• TESTED — powered and functionally verified on hardware
• PRODUCTION — used in a shipped/deployed product

Two build targets per package

builds:
  package:
    entry: .ato:
    hide_designators: true
  test:
    entry: test.ato:Test
    hide_designators: true

• The package build compiles the driver module standalone (used for the package-level layout).
• The test build compiles the test harness that instantiates and wires the driver (used for a test-level layout with instance-prefixed addresses).

Consuming a local package

dependencies:
  - type: file
    identifier: /
    path: ../packages/

Then import the driver:

from "//.ato" import DriverModule

Shared Package vs. Inline

Shared package (in packages/): two or more boards use it, or it's a commodity block (MCU, regulator, current sense, connector).

Inline in the board: only one board uses it, and it's tightly coupled to that application.

When in doubt, start inline. Extract to a shared package when a second board needs it.

Source & license

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

• Author: mawildoer
• Source: mawildoer/atopile-agent-skill
• License: MIT

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