reference-design

SKILL.md

Component Package Design

Grow component packages beyond a generated wrapper when the part benefits from reusable surrounding circuitry. A good component package captures the support circuitry, default mode, key equations, layout-sensitive notes, and evidence needed to use the part confidently.

Hard Rules

Reuse before create. Search existing registry/workspace packages first.

New work lives in components/<NAME>/, never in a separate reference/ tree. Legacy reference/ packages in the registry are read-only examples — inspect them for structure and API shape, but don't copy their placement.

The .kicad_sym file is the source of truth for the primitive component interface and pin structure. Keep the .zen API aligned to it.

The .zen docstring is the canonical design document. The README is for usage examples only.

Review pcb build warnings, especially BOM/sourceability warnings such as bom.match_generic.

Don't guess ambiguous passives, straps, sequencing, or oscillator details. Get evidence or stop and ask.

Imitate only strong exemplars. Weak/generated packages are useful for pin lookup and starting structure, not authoring style.

Preserve # pcb:sch ... comments (tool-managed schematic layout metadata). When renaming a referenced component, module instance, or net, update the matching # pcb:sch names.

If an existing registry example conflicts with this skill, this skill wins.

Reuse Before Create