Bundled agent skill

The installed distribution includes a pykicad-cli agent skill with the CLI workflow, query patterns, schema documentation, and a machine-readable JSON Schema. Copy it into a repository's project skills with:

pykicad skill copy .agents/skills

The destination parent defaults to .agents/skills, so pykicad skill copy creates .agents/skills/pykicad-cli. The command refuses to overwrite an existing skill directory.

The complete export is designed to compose with standard JSON tools instead of providing a separate query language. For example:

# Footprint references, values, and positions
pykicad json board.kicad_pcb | jq '.document.footprints[] | {reference, value, position}'

# Pads belonging to U1
pykicad json board.kicad_pcb | jq '.document.footprints[] | select(.reference == "U1") | .pads[]'

# Unique connected net names
pykicad json board.kicad_pcb | jq '[.document.footprints[].pads[].net.name] | map(select(. != null)) | unique'

# Placed schematic symbols
pykicad json design.kicad_sch | jq '.document.symbols[] | {reference, value, footprint, position}'

# Tracks and copper zones
pykicad json board.kicad_pcb | jq '{tracks: .document.tracks, zones: .document.zones}'

Schema version 1 guarantees the envelope and modeled semantic field names. Additional modeled fields may be added compatibly; removing a field or changing its meaning requires a new schema version. Contents of extensions are best-effort and are not part of that compatibility guarantee. JSON export is read-only and does not retain source whitespace, comments, quoting choices, or exact numeric spelling.

Supported documents

read_from_file() and read_from_string() return a KicadDocument containing the parsed model and its original source. They recognize:

• .kicad_pcb board files as Pcb
• .kicad_mod footprint files as Footprint
• .kicad_sch schematic files as Schematic
• KiCad-exported S-expression netlists as Netlist

The parser uses one Pydantic model family for released KiCad 6 and newer file variants. Unknown enum values and malformed S-expressions remain validation errors.

from pydantic import ValidationError
from pykicad import read_from_string

try:
    document = read_from_string(
        "(kicad_pcb (version 20240101) (generator pcbnew))"
    )
    board = document.model
except (ValueError, ValidationError) as error:
    print(f"Invalid KiCad document: {error}")

Writing

PCB documents loaded through read_from_file() or read_from_string() retain their original source. Writing a parsed KicadDocument updates only changed S-expression nodes, preserving the formatting and numeric spelling of untouched content. Inserted and changed content follows KiCad 10 formatting, including local indentation, aligned multiline closing parentheses, and compact numeric spelling such as 0 instead of 0.0. Bare PCB models constructed in Python use the same formatting with tab indentation:

from pykicad import read_from_file, write_to_file

document = read_from_file("project.kicad_pcb")
write_to_file(document, "copy.kicad_pcb")

Use PcbBuilder.create() to construct an empty KiCad 10 board. Standalone .kicad_mod footprints can also be read and written. Models remain declarative data structures; document I/O, serialization, and authoring live in dedicated modules. Schematic writing is not implemented.

Unmodeled fields retain the distinction between bare keywords and quoted text. When constructing such fields directly, use pykicad.parser.sexp.SexpSymbol("outline") for a bare keyword; a plain Python string such as "outline" is written as quoted text. The parser preserves this distinction automatically when importing footprints and boards.

Common authoring operations are available through builders:

from pykicad import BoardSide, FootprintBuilder, PcbBuilder, write_to_file
from pykicad.models.base import Point
from pykicad.models.pcb import Position

board = PcbBuilder.create(copper_layer_count=4)
ground = board.ensure_net("GND")
board.add_via(Position(x=10, y=10), size=0.6, drill=0.3, net=ground)
board.add_graphic_rect(
    Point(x=0, y=0), Point(x=20, y=20), layer="Edge.Cuts"
)

footprint = FootprintBuilder.create("Example:Part")
footprint.set_reference("U1", at=Position(x=0, y=-2), layer="F.SilkS")
footprint.place(Position(x=5, y=5), side=BoardSide.BACK)
board.add_footprint(footprint.build())

write_to_file(board.build(), "authored.kicad_pcb")

Place a .kicad_mod file directly onto a board with a reference and pad-net mapping. Each placement receives fresh identifiers, so the same file can be reused safely:

from pykicad import BoardSide, PcbBuilder, write_to_file
from pykicad.models.pcb import Position

board = PcbBuilder.create()
board.add_footprint_file(
    "Package_SO.pretty/SOIC-8.kicad_mod",
    reference="U1",
    at=Position(x=25, y=40, angle=90),
    side=BoardSide.BACK,
    pad_nets={"1": "GND", "8": "VCC"},
)
write_to_file(board.build(), "placed.kicad_pcb")

Development

Create an environment and install the development dependencies:

python -m pip install -e ".[dev]"
python -m pytest

Build and validate release artifacts with:

python -m build
python -m twine check dist/*
python scripts/check_distribution.py dist/*

See RELEASING.md for the trusted-publishing release process.