# Build And Test

> Use when building, validating, or debugging atopile projects. Triggers on build errors, "ato build", solver failures, "no parts found", package management, creating parts from JLCPCB, or debugging connectivity issues.

- **Type:** Skill
- **Install:** `agentstack add skill-mawildoer-atopile-agent-skill-build-and-test`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mawildoer](https://agentstack.voostack.com/s/mawildoer)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mawildoer](https://github.com/mawildoer)
- **Source:** https://github.com/mawildoer/atopile-agent-skill/tree/master/skills/build-and-test

## Install

```sh
agentstack add skill-mawildoer-atopile-agent-skill-build-and-test
```

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

## About

# Build & Test Workflow

## Typical Order

1. **`ato validate `** -- quick syntax check. Catches parse errors before a full build. No solver, no parts, no PCB. Use after editing .ato files to confirm they parse cleanly.
2. **`ato build`** -- the main command. Runs from the project directory (wherever `ato.yaml` lives). Stages in order: resolve dependencies, build context, instantiate, verify design, pick parts from JLCPCB, update PCB, generate reports. A successful build means the design is electrically valid and all parts are available.
3. **`ato build --open`** -- same as above, then launches KiCad layout editor so you can inspect/route the PCB.
4. **`ato build -b `** -- build a specific target from `ato.yaml` (e.g. `ato build -b test`). Useful when a project has multiple build targets.
5. **`ato build --verbose`** -- runs sequentially without the live display. Better for reading error messages.
6. **`ato inspect`** -- debug connectivity. Shows what is connected to a module at a given boundary. Use `--inspect  --context ` to see connections from a specific viewpoint.
7. **`ato create part -s ""`** -- search JLCPCB and generate a component package (.ato + KiCad footprint/symbol) in `parts/`. Interactive: presents matches and lets you pick.

Run any command with `--help` for full flag details.

## Build Outputs

After a successful build, outputs land in `build/builds//`:

| File | Contents |
|------|----------|
| `.bom.csv` | Bill of materials -- designators, footprints, manufacturer, LCSC part numbers |
| `.bom.json` | Same BOM in JSON format |
| `.variables.ato.json` | All solved parameter values -- spec vs actual, whether constraints are met |
| `.power_tree.ato.json` | Power tree structure (JSON) |
| `power_tree.md` | Power tree as Mermaid diagram |
| `.data_interface_tree.ato.json` | Data interface topology |
| `pinout/` | Per-component pinout JSON files |
| `backups/` | PCB backup snapshots |

The `build/cache/` directory stores downloaded datasheets (PDFs) for picked parts.

## Debugging Build Errors

### "No parts found matching constraints"

The most common error. The JLCPCB part solver cannot find a real part matching your parameter assertions. Fix in this order:

1. **Add tolerances** -- `resistance = 10kohm` matches nothing (0% tolerance). Use `resistance = 10kohm +/- 5%` or `assert resistance within 10kohm +/- 10%`.
2. **Widen package constraint** -- `package = "0201"` severely limits options. Try `"0402"` or remove the package constraint entirely.
3. **Check for conflicting assertions** -- two assertions on the same parameter can create an impossible range. Use `get_hover` from the LSP on the parameter to see the effective constraint.
4. **Check max_voltage / max_current** -- if you assert `max_voltage within 100V +/- 10%` on a 0402 cap, nothing exists. Relax or remove secondary constraints.
5. **Inspect the variables report** -- after a partial build, check `build/builds//.variables.ato.json` to see what the solver computed for each parameter.

### "Assertion failed"

A design rule check (assert statement) evaluated to false after part picking. The error message names the specific assertion and the values it compared.

1. Read the assertion in the .ato source -- it tells you what relationship was expected.
2. Use `get_hover` on the parameters involved to see their solved values.
3. Either loosen the assertion (widen the tolerance) or tighten the input (pick a more precise part, constrain upstream parameters).

### Connection / wiring errors

Symptoms: "cannot connect X to Y", type mismatch on `~`, or missing pins.

1. You can only connect interfaces of the same type. `ElectricPower ~ Electrical` will fail -- you need to connect to the correct sub-interface (e.g. `power.hv ~ some_electrical`).
2. Use `ato inspect --inspect  --context ` to see what is actually connected where.
3. Check `~` vs `~>` usage. `~>` is the bridge-connect operator and requires `#pragma experiment("BRIDGE_CONNECT")` and the module must have the `can_bridge` trait.
4. Make sure pin names match. Use `get_hover` or `get_definition` on the component to verify pin names.

### Import / dependency errors

Symptoms: "module not found", "cannot resolve import", file path errors.

1. Check `ato.yaml` -- is the dependency listed? Is the path correct for `type: file` deps?
2. Run `ato dependencies sync` to install/update dependencies.
3. For registry packages: `ato dependencies add ` to add and install.
4. For local packages: use `type: file` with a relative path from the project root.
5. Verify the import path matches the actual file path and module name.

### Build hangs or is very slow

The part picker queries JLCPCB and can be slow. If it hangs:

1. Check your internet connection -- part picking requires network access.
2. Use `--verbose` to see which stage is stalling.
3. If stuck on "Picking parts", you may have too many unconstrained components. Add package constraints to narrow the search space.
4. Use `--keep-picked-parts` to reuse previously picked parts and skip re-solving.

### PCB-related errors

1. `--frozen` mode (CI) fails if the PCB needs changes. Remove `--frozen` locally to let it update, then commit the result.
2. "Backing up unsaved pcb changes" is informational, not an error -- it saves your KiCad session before overwriting.
3. If KiCad is open and locked, close it or remove the `.lck` file before building.

## Package Management

```yaml
# ato.yaml dependency types:
dependencies:
  - type: registry          # From packages.atopile.io
    identifier: atopile/netties
    release: 0.2.0

  - type: file              # Local/vendored package
    identifier: /
    path: ../packages/
```

| Command | What it does |
|---------|-------------|
| `ato dependencies add ` | Add a registry package (e.g. `atopile/netties`) |
| `ato dependencies add file://` | Add a local package |
| `ato dependencies remove ` | Remove a dependency |
| `ato dependencies sync` | Install/update all deps to match ato.yaml |
| `ato dependencies sync -U` | Upgrade deps, ignoring pinned versions |
| `ato dependencies list` | Show current dependencies |

## LSP Integration for Debugging

Use the atopile LSP MCP tools (see the `lsp` skill) alongside builds:

- **`get_diagnostics`** -- faster than a full build for catching syntax errors after edits.
- **`get_hover`** -- inspect solved parameter constraints, interface types, and member lists. Essential for debugging "no parts found" and "assertion failed".
- **`get_definition`** -- jump to where an interface or module is defined when you need to understand its structure.
- **`get_references`** -- find everywhere a symbol is used when tracing connectivity issues.

## Build Flags Quick Reference

| Flag | Use case |
|------|----------|
| `--verbose` / `-v` | See full sequential output instead of live display |
| `--open` | Launch KiCad after build |
| `--frozen` | CI mode -- fail if PCB would change |
| `--keep-picked-parts` | Reuse previously picked parts |
| `--keep-net-names` | Preserve net names from PCB |
| `--keep-designators` | Preserve designators from PCB |
| `--all` | Build all projects found recursively |
| `-j N` | Set max concurrent builds (default: 14) |

## Source & license

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

- **Author:** [mawildoer](https://github.com/mawildoer)
- **Source:** [mawildoer/atopile-agent-skill](https://github.com/mawildoer/atopile-agent-skill)
- **License:** MIT

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-mawildoer-atopile-agent-skill-build-and-test
- Seller: https://agentstack.voostack.com/s/mawildoer
- 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%.