| name | drawing-kicad-schematics |
| description | Use when a user asks to create, draw, edit, repair, validate, or export KiCad schematic files (.kicad_sch) from circuit requirements, pin lists, block diagrams, netlists, existing KiCad projects, or 原理图 requests. |
Drawing KiCad Schematics
Overview
Create or modify real KiCad schematic files, not schematic-looking prose. First model the circuit intent, then write a verifiable .kicad_sch, then use KiCad CLI outputs to prove the electrical result.
Core principle: a schematic is complete only when the requested KiCad files and requested exports exist, symbols are verified, connectivity is electrical rather than visual, and ERC results are reported honestly.
When To Use
Use for KiCad schematic, .kicad_sch, 原理图, circuit drawing, symbol placement, net labels, ERC, netlist, BOM, or PDF/SVG schematic export tasks.
Do not use for PCB placement/routing, footprint creation, SPICE model authoring, or general circuit explanation unless a KiCad schematic file is part of the requested output.
digraph source_policy {
"User asked to edit source directly?" [shape=diamond];
"Modify target file" [shape=box];
"User asked for copy/output dir?" [shape=diamond];
"Write only to requested output path" [shape=box];
"Ask one target/write-policy question" [shape=box];
"User asked to edit source directly?" -> "Modify target file" [label="yes"];
"User asked to edit source directly?" -> "User asked for copy/output dir?" [label="no"];
"User asked for copy/output dir?" -> "Write only to requested output path" [label="yes"];
"User asked for copy/output dir?" -> "Ask one target/write-policy question" [label="unclear"];
}
Required Workflow
- Resolve the target file and write policy before editing: exact
.kicad_sch, project directory, and whether to modify in place or write a copy.
- Read existing project files:
.kicad_sch, .kicad_pro, sym-lib-table, project .kicad_sym, and any opened-file context. The opened file is not the target unless the user says it is.
- Inventory the circuit: components, references, values, footprints, pins, power rails, named nets, intended no-connects, and required exports.
- Verify every
lib_id before use. Search installed KiCad symbol libraries or reuse existing verified lib_symbols. Do not invent symbols.
- Preserve existing schematic content unless the user asks to replace it. New UUIDs must be unique across symbols, pins, wires, labels, junctions, and no-connect markers.
- Place objects on a consistent KiCad grid. Use wires, labels, junctions, and no-connect markers; visual overlap is not electrical connectivity.
- Add power symbols and
PWR_FLAG when a power net has no driver. For large ICs/MCUs, intentionally handle unused pins with no-connect markers or labels.
- Run validation with explicit output paths: ERC, requested exports, and netlist checks. Never rely on KiCad CLI default report locations.
- If ERC fails, repair the schematic and rerun. If it cannot be repaired with available information, stop and report the remaining violations; do not claim completion.
Quick Reference
| Need | What to do |
|---|
| Find KiCad CLI | Try kicad-cli first; if not on PATH, use the absolute path to the KiCad CLI binary on your system. |
| Verify symbol | Confirm the library file exists and contains the exact symbol name, e.g. Device.kicad_sym contains (symbol "R" ...) before using Device:R. |
| Reuse symbol cache | Prefer existing lib_symbols from the project or a KiCad-generated schematic for the same symbol; do not paste unrelated circuitry. |
| Add symbol instance | Include lib_id, at, unit, properties, pin UUIDs, and instances with the project name/path. |
| Connect nets | Use wire endpoints on pin coordinates, net labels/global labels, and junctions at true branch points. |
| Power rails | Use power:+5V, power:GND, etc.; add power:PWR_FLAG when ERC sees no source. |
| Unused pins | Add (no_connect ...) markers on unused pins or intentionally tie them to named nets. |
| Validate | ERC with --exit-code-violations, PDF/SVG/export if requested, and netlist inspection for key nets/components. |
KiCad File Rules
Read references/kicad-schematic-format.md when writing or repairing .kicad_sch content. Read references/kicad-cli-validation.md before running validation/export commands.
Minimum .kicad_sch expectations:
- Header contains
(kicad_sch ...), format version, generator, root uuid, paper, lib_symbols, schematic objects, sheet_instances, and embedded_fonts.
lib_symbols contains cached definitions for used symbols or the file references symbols resolvable by the project/library setup.- Each placed
(symbol ...) has unique symbol UUID, per-pin UUIDs, correct properties, and an instances block matching the project.
- Wires and labels create real KiCad nets. Branches need
junction only where multiple wire segments meet electrically.
- Coordinates should align to KiCad's normal grid, commonly 2.54 mm for schematic symbols.
Validation Commands
Use explicit paths every time:
# Locate the CLI first, then run with explicit output paths
$cli = Get-Command "kicad-cli" -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source
if (-not $cli) { $cli = "<path-to-your-kicad-cli>" } # adapt to your install
& $cli sch erc --format json --severity-all --exit-code-violations --output "reports\design-erc.json" "design.kicad_sch"
& $cli sch export pdf --output "exports\design.pdf" "design.kicad_sch"
& $cli sch export netlist --format kicadsexpr --output "exports\design.net" "design.kicad_sch"
If kicad-cli is on PATH, use it directly. If not, use the verified absolute path. Create reports/ and exports/ only after confirming their parent directory is the intended output directory.
Example: LED Branch From A Blank Sheet
For +5V -> R1 330R -> D1 -> GND with J1 input:
- Verify symbols:
Device:R, Device:LED, Connector:Conn_01x02_Pin, power:+5V, power:GND, power:PWR_FLAG.
- Place rails at the left, load branch left-to-right, and connector near rails. Assign footprints only when obvious or requested.
- Wire
+5V to R1 pin 1, R1 pin 2 to D1 anode, D1 cathode to GND. Connect J1 pin 1 to +5V, J1 pin 2 to GND.
- Add
PWR_FLAG to +5V and GND if no supply symbol drives those nets.
- Run ERC and inspect the netlist for
R1, D1, J1, +5V, and GND before claiming completion.
This example shows the pattern; adapt coordinates and footprints to the user's project.
ERC Repair Guide
| ERC symptom | Likely fix |
|---|
| Power input not driven | Add verified PWR_FLAG or a real regulator/output source. |
| Pin not connected | Add the intended wire/net label or a no_connect marker. |
| Nets look connected but are separate | Align endpoints to pin/wire coordinates; add junctions only at branch nodes. |
| Symbol not found | Verify library path and lib_id; replace with an existing symbol or ask. |
| Duplicate reference or UUID | Allocate new references and UUIDs; scan the whole file before writing. |
| Requested export missing | Run the export or report the exact failure; do not say PASS. |
Rationalizations To Reject
| Excuse | Reality |
|---|
| "The schematic opens, so ERC warnings are acceptable." | Opening is syntax validation, not electrical validation. Repair ERC or report failure. |
| "The wire touches the pin visually." | KiCad connectivity depends on exact coordinates/net labels. Verify with netlist/ERC. |
| "This library symbol probably exists." | Probably is not verified. Search the library or ask. |
| "The output directory was requested, but editing the target is fine." | Output-copy tasks must not mutate source files. |
| "A PDF is optional." | If the user requested PDF/SVG/netlist/BOM, missing export is incomplete work. |
| "Unused MCU pins can float." | Intentional unused pins need no-connect markers or documented handling. |
Red Flags
Stop and fix before final response if any are true:
- You have not verified every
lib_id.
- A generated
.kicad_sch has duplicate UUIDs or references.
- You wrote outside the requested output directory.
- You modified the opened file instead of the user-specified target.
- ERC was not run, failed, or wrote to an implicit default location.
- A requested PDF/SVG/netlist/BOM export is missing.
- A connection is only visual, with no wire endpoint, label, or junction proof.
- Large IC unused pins are neither connected nor marked no-connect.
Final Report
Report concise evidence:
- Target file and write policy used.
- Files created/modified.
- Symbols verified and any assumptions about footprints/values.
- ERC command and result.
- Export commands and result.
- Any remaining violations, missing exports, or user decisions needed.
