kicad-sch-tweak

KiCad Schematic Editor

Edit KiCad 6+ schematic files (.kicad_sch) using S-expression text format.

Quick Reference

• Format docs: See references/kicad-sch-format.md for complete S-expression syntax

Recommended Workflow: User + AI Collaboration

Best practice for adding components:

1. User adds components via KiCad GUI: Use KiCad's graphical interface to add new symbol types. This automatically:

• Populates the lib_symbols section with full symbol definitions
• Ensures correct UUID formats
• Handles footprint assignments
• Places components roughly where needed

2. AI performs text-based tweaks: After user adds components, AI can efficiently:

• Add/modify global labels and net labels
• Add wires and junctions
• Change component values
• Adjust coordinates
• Add text annotations
• Duplicate existing components (copy from file)

Why this workflow?

• Adding NEW symbol types programmatically requires copying entire symbol definitions to lib_symbols - tedious and error-prone
• KiCad GUI handles library caching automatically
• AI excels at repetitive text operations (adding 80 labels for 8 IDC headers)
• Reduces risk of file corruption from format mismatches

Workflow example:

1. User: "I need 8 IDC headers and 4 fuses" → adds in KiCad, saves
2. AI: "Let me add power rail labels to all headers" → edits .kicad_sch
3. User: Opens KiCad, adjusts layout, verifies connections

Workflow

1. Safety Check & Discover Project

Before editing, always:

1. Verify file is version-controlled: Run git status to confirm changes can be reverted
2. Read the target .kicad_sch file to understand current structure
3. Find symbol libraries: Read sym-lib-table for available symbol library names
4. Find available symbols: Read the project's .kicad_sym file(s) referenced in sym-lib-table
5. Get sheet UUIDs: Read root .kicad_sch for sheet hierarchy and UUIDs

2. Understand User Request

Clarify with user if needed:

• Which components to add/modify/remove
• Component values (resistance, capacitance, etc.)
• Connection requirements (what connects to what)
• For new circuits: reference documentation or ASCII diagram

3. Make Edits

Use the Edit tool for targeted changes. Always copy patterns from existing components in the same file.

Change component value:

(property "Value" "10k"   ;; Change to new value

Add new component: Copy existing symbol block from same file, then update:

• uuid (generate new unique UUID)
• (at X Y rotation) coordinates
• (property "Reference" "R99" - next available designator
• (property "Value" "..." - component value
• Pin UUIDs (generate new unique ones)
• Instance path (copy from similar component, update reference)

Add wire:

(wire
  (pts (xy X1 Y1) (xy X2 Y2))
  (stroke (width 0) (type default))
  (uuid "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
)

Add net label:

(label "SIGNAL_NAME"
  (at X Y rotation)
  (effects (font (size 1.27 1.27)) (justify left bottom))
  (uuid "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
)

4. Validate

After editing:

• Ensure all UUIDs are unique (36-char format, lowercase hex: a1b2c3d4-e5f6-7890-abcd-ef1234567890)
• Check S-expression syntax (balanced parentheses)
• Verify library references exist (lib_id matches library in sym-lib-table)
• Suggest user open in KiCad to visually verify - Claude cannot confirm connectivity
• For complex edits: Recommend running KiCad ERC (Electrical Rules Check)

Project Discovery

For any KiCad project, find these key files:

File	Purpose	Key Info
*.kicad_pro	Project config	Project name, settings
sym-lib-table	Symbol libraries	Library names and paths
fp-lib-table	Footprint libraries	Footprint library names
Root .kicad_sch	Main schematic	Sheet UUIDs, hierarchy
*.kicad_sym	Symbol definitions	Available component symbols

Get library prefix: Read sym-lib-table to find (name "...") - use as lib_id prefix (e.g., "mylib:ComponentName").

Get sheet UUID: Read root schematic's (uuid "...") field for root UUID. For sub-sheets, find (sheet ... (uuid "...")) blocks.

Symbol Template

CRITICAL: Copy from existing component in same file first! This ensures UUID format and other details match.

If creating from scratch, check the file's UUID format first (quoted vs unquoted), then use:

(symbol
	(lib_id "LIBRARY:SYMBOL_NAME")
	(at X Y ROTATION)
	(unit 1)
	(exclude_from_sim no)
	(in_bom yes)
	(on_board yes)
	(dnp no)
	(uuid UNIQUE-UUID-HERE)
	(property "Reference" "R1"
		(at X Y 0)
		(effects
			(font
				(size 1.27 1.27)
			)
		)
	)
	(property "Value" "10k"
		(at X Y 0)
		(effects
			(font
				(size 1.27 1.27)
			)
		)
	)
	(property "Footprint" "LIBRARY:FOOTPRINT"
		(at X Y 0)
		(effects
			(font
				(size 1.27 1.27)
			)
			(hide yes)
		)
	)
	(property "Datasheet" ""
		(at X Y 0)
		(effects
			(font
				(size 1.27 1.27)
			)
			(hide yes)
		)
	)
	(property "Description" ""
		(at X Y 0)
		(effects
			(font
				(size 1.27 1.27)
			)
			(hide yes)
		)
	)
	(pin "1"
		(uuid PIN1-UUID-HERE)
	)
	(pin "2"
		(uuid PIN2-UUID-HERE)
	)
	(instances
		(project ""
			(path "/ROOT-UUID"
				(reference "R1")
				(unit 1)
			)
		)
	)
)

Notes:

• UUID format: Check existing file - use quoted "uuid" or unquoted uuid to match
• PROJECT_NAME_OR_EMPTY: Check existing components - usually ""
• ROTATION: 0, 90, 180, or 270 degrees
• Pin count varies by component - check symbol definition in .kicad_sym file

Power Symbols

Use built-in power: library:

(symbol
  (lib_id "power:GND")
  (at X Y 0)
  (unit 1)
  (exclude_from_sim no)
  (in_bom yes)
  (on_board yes)
  (dnp no)
  (fields_autoplaced yes)
  (uuid "UNIQUE-UUID")
  (property "Reference" "#PWR01" (at X Y 0) (effects (font (size 1.27 1.27)) (hide yes)))
  (property "Value" "GND" (at X Y 0) (effects (font (size 1.27 1.27))))
  (pin "1" (uuid "PIN-UUID"))
  (instances
    (project "..."
      (path "/..." (reference "#PWR01") (unit 1))
    )
  )
)

Common power symbols: power:GND, power:+5V, power:+12V, power:-12V, power:VCC, power:VDD

Coordinate System

• Origin: top-left of page
• Units: millimeters
• Rotation: degrees (0, 90, 180, 270)
• Grid: 2.54mm (0.1 inch) typical spacing
• Tip: Look at nearby components for reasonable coordinates

Reference Designators

Prefix	Component
R	Resistors
C	Capacitors
L	Inductors
D	Diodes
U	ICs/Modules
J	Connectors
TP	Test points
F	Fuses
#PWR	Power symbols (hidden)

Limitations

• Layout quality: Components placed programmatically may overlap. User adjusts in KiCad GUI.
• Wire routing: Prefer net labels over complex wire routing for drafts.
• Pin positions: Estimated from symbol definitions; may need adjustment.

CRITICAL: lib_symbols Section (KiCad 9.0+)

When adding a NEW symbol type to a schematic, you MUST also add its definition to the lib_symbols section.

KiCad caches symbol definitions inside the schematic file. If you add a symbol instance without adding its definition to lib_symbols, the file will crash on open.

How to add a new symbol:

1. Copy symbol definition from the .kicad_sym library file
2. Add to lib_symbols with library prefix (e.g., "zudo-bus:CL10B104KB8NNNC")
3. Add symbol instance referencing the same lib_id

Example lib_symbols entry:

(lib_symbols
	(symbol "library-name:SymbolName"
		(exclude_from_sim no)
		(in_bom yes)
		(on_board yes)
		(property "Reference" "C"
			...
		)
		;; Copy entire symbol definition from .kicad_sym file
		;; Including all properties, graphics, and pins
		(embedded_fonts no)
	)
)

Notes:

• Symbol name in lib_symbols must include library prefix: "library:Symbol" not just "Symbol"
• Copy the ENTIRE symbol definition including all (symbol "Name_0_1" ...) graphics blocks
• Add (embedded_fonts no) at the end of each symbol in lib_symbols
• If adding multiple symbols, each needs its own definition in lib_symbols

CRITICAL: Format Matching

ALWAYS match the existing file's format exactly. Different KiCad projects may use slightly different S-expression styles. Key variations:

UUID Format (CRITICAL - causes crashes if wrong!)

Check how UUIDs appear in the existing file:

;; Some projects use UNQUOTED UUIDs:
(uuid 26efc87e-0264-438c-bf9f-152a5d6f0f11)

;; Some projects use QUOTED UUIDs:
(uuid "26efc87e-0264-438c-bf9f-152a5d6f0f11")

You MUST use the same format as existing UUIDs in the file! Mixing formats causes KiCad to crash on open.

Pin Format

Pins should have uuid on its own line:

(pin "1"
	(uuid 00000001-0001-0001-0001-000000000002)
)

Instances Format

The path should have reference and unit on separate lines:

(instances
	(project ""
		(path "/26efc87e-0264-438c-bf9f-152a5d6f0f11"
			(reference "C1")
			(unit 1)
		)
	)
)

Text Elements

Text elements should NOT have (exclude_from_sim no):

;; CORRECT:
(text "POWER INPUT"
	(at 25.4 25.4 0)
	(effects (font (size 3.81 3.81) (bold yes)))
	(uuid a0000001-0001-0001-0001-000000000001)
)

;; WRONG - causes crashes:
(text "POWER INPUT"
	(exclude_from_sim no)  ;; <-- DO NOT ADD THIS TO TEXT
	(at 25.4 25.4 0)
	...
)

Labels Format

Net labels follow this format:

(label "SIGNAL_NAME"
	(at X Y rotation)
	(effects
		(font
			(size 1.27 1.27)
		)
		(justify left bottom)
	)
	(uuid c0000001-0001-0001-0001-000000000001)
)

sym-lib-table Required

If the project doesn't have a sym-lib-table file, create one:

(sym_lib_table
  (version 7)
  (lib (name "library-name")(type "KiCad")(uri "${KIPRJMOD}/symbols/library-name.kicad_sym")(options "")(descr ""))
)

All libraries referenced by lib_id in the schematic MUST be listed in sym-lib-table.

Error Recovery

If schematic won't open in KiCad:

KiCad crashes on open:

1. Check UUID format - must match existing file (quoted vs unquoted)
2. Check text elements don't have (exclude_from_sim no)
3. Verify sym-lib-table exists and references all used libraries

Parenthesis mismatch: Check line-by-line for missing ). Common: deleted symbol block with dangling reference.

Invalid UUID: Must be exactly 36 chars, lowercase hex (0-9, a-f). Quick fix: copy existing UUID and change last 4 digits.

Missing lib_id: Symbol not in library. Check:

1. sym-lib-table file exists
2. Library is listed in sym-lib-table
3. Symbol name exists in the .kicad_sym file

Revert changes:

git checkout -- path/to/file.kicad_sch

Required properties: Reference, Value, Footprint (Datasheet and Description recommended).