skill

KiCad to Markdown

Unreviewed

by Kyle Bergstedt

Parses KiCad projects into structured markdown documents optimized for AI consumption — extracts components, netlist connectivity, hierarchical sheets, PCB layout, and design rules.

Overview Files Versions Dependencies Discussions Activity
kicad-to-markdown / README.md
Raw

KiCad to Markdown Parser

Converts KiCad 6+ projects into structured, AI-readable markdown documents. Upload a .zip or point it at a project directory — get back a comprehensive breakdown of your schematic and PCB.

What It Extracts

Source File Data Extracted
.kicad_pro Project name, net class definitions, design settings
.kicad_sch Components, net labels, power symbols, wires, hierarchical sheets, full netlist connectivity
.kicad_pcb Footprints, traces, vias, zones, board outline, layer stackup, design rules

Key Features

  • Netlist extraction from schematics — traces wires using union-find, resolves net names from labels and power symbols
  • Hierarchical sheet support — follows sub-sheets and extracts interface pins
  • PCB layout parsing — board dimensions, layer stackup, component placement, routing summary
  • Coordinate system handling — correctly transforms KiCad library Y-up to schematic Y-down with rotation/mirror support
  • Labels on wire segments — handles labels placed mid-wire, not just at endpoints
  • Zip file support — handles flat zips and single-subdirectory zips

Usage

CLI (preferred)

cd /home/adom/project/kicad-to-markdown
python3 cli.py /path/to/project/ -o output.md
python3 cli.py /path/to/project.zip -o output.md

HTTP API

# Start server
cd /home/adom/project/kicad-to-markdown
uvicorn server:app --host 0.0.0.0 --port 8000 &

# Upload zip → get markdown
curl -F "[email protected]" http://localhost:8000/parse

# Upload zip → get JSON with stats
curl -F "[email protected]" http://localhost:8000/parse/json

Output Structure

# KiCad Project: {name}
## Overview — component count, net count, board dimensions
## Components — table of all parts with ref, value, footprint, description
## Connectivity (Netlist) — named nets then unnamed nets, each listing connected pins
## Hierarchical Sheets — sub-sheet structure and interface pins
## Power Nets — which components connect to each power rail
## PCB Physical Layout
  ### Board Outline, Layer Stackup, Component Placement
  ### Routing Summary, Most Routed Nets, Copper Zones
## Design Rules — net classes with clearance/trace width settings

Example Output

Tested on real projects:

  • Crosspoint Matrix 2CH 4x8 — 28 components, 78 PCB footprints, 169 nets, 7 hierarchical sheets, 4-layer 202×106mm board
  • STLink V3 Mods — 72 components, 2 sheets, 79 nets

Dependencies

Python 3.10+, kiutils, fastapi, uvicorn, python-multipart, click.

Trigger Phrases

  • "Parse a KiCad project"
  • "Convert KiCad to markdown"
  • "Understand a KiCad schematic"
  • "Extract netlist"
  • "Analyze a .kicad_sch"
  • "What's in this KiCad project"