菜单
Use when renaming or refactoring components in .ato files that have existing PCB layout placements. Triggers on "layout broken", "components at origin", "lost placement after rename", "relink layout", or any .ato refactor that changes component names or module structure.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | layout-relinking |
| description | Use when renaming or refactoring components in .ato files that have existing PCB layout placements. Triggers on "layout broken", "components at origin", "lost placement after rename", "relink layout", or any .ato refactor that changes component names or module structure. |
When you rename a component in .ato code, its atopile_address in the .kicad_pcb becomes stale. On the next build, atopile can no longer match the placed footprint to the renamed component, so the component loses its placement (moved to origin, unrouted).
Critical: relink BEFORE building. If you build with stale addresses, atopile orphans the old placements and creates new unplaced footprints. Relinking after that means recovering from backups.
Each footprint in the .kicad_pcb carries an atopile_address property — the dot-path of instance names from the build entry point down to that component. If Board has charger = new BQ25756Charger and BQ25756Charger has _richg = new Resistor, the address is charger._richg. Renaming any instance in that chain changes the address; relinking rewrites the stored address to match the new path so the placement is preserved.
This workflow relies on two small scripts that operate on the .kicad_pcb. Many projects vendor them under tools/; if yours doesn't, they're trivial to write (parse the s-expression / KiCad file, read or rewrite the atopile_address property on each footprint):
atopile_address in a .kicad_pcb (optionally with the footprint each maps to).The commands below assume tools/layout-list-addresses.py and tools/layout-rename-address.py. Substitute your project's equivalents.
Make your .ato changes (renames, submodule extraction, etc.) — do NOT build yet.
Examine what changed:
git diff -- "*.ato"
List current PCB addresses:
python tools/layout-list-addresses.py <pcb_file>
Figure out the mapping. Construct new paths from the module hierarchy in the .ato source. The address path is the chain of instance names from the build entry point down.
Note: the LSP tools (get_hover, get_definition, get_references) do NOT provide atopile_address paths. Use git diff and the .ato source to determine mappings.
Relink each renamed component:
python tools/layout-rename-address.py <pcb_file> "old.path" "new.path"
A prefix-aware tool renames all children of a renamed parent in one call.
Now run ato build — addresses match, placements preserved.
Verify:
python tools/layout-list-addresses.py <pcb_file>
Extracting a submodule — moving charger.richg into charger._sense._shunt:
python tools/layout-rename-address.py <pcb> "charger.richg" "charger._sense._shunt"
Renaming a parent module (catches all children):
python tools/layout-rename-address.py <pcb> "charger.acov_div" "charger._acov_divider"
# Renames charger.acov_div.chain.resistors[0], [1], etc. automatically
.kicad_pcb (or rely on a tool that writes a .bak on first modification) before bulk renames — restore with cp file.bak file.Use when writing, reading, or reviewing .ato files. Triggers on "what interface for X", "how to connect Y", choosing between interface types, parameter constraints, tolerance syntax, or atopile design patterns.
Use when designing a new board or modifying board-level architecture in atopile. Triggers on new board creation, connector wiring, power rail routing, MCU peripheral assignment, or composing packages into a board.
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.
Use when adding a new IC, component, or subcircuit to an atopile project. Triggers on creating atopile packages, sourcing parts, vendoring an existing package, or deciding whether to make a shared package vs. inline in a board. Also use when you see ato create part or are about to write a new .ato driver module.
Use when reviewing or completing an atopile package or board design. Triggers on design review, pre-commit check, "is this ready", quality audit, finishing a package implementation, or verifying a design before build.
Use when working with .ato files and you need semantic code intelligence — hover info, diagnostics, go-to-definition, find-references, or symbol inspection. Triggers on questions like "what type is this", "what members does X have", "where is X defined", "what uses Y", checking for parse errors, or understanding atopile module/interface signatures.