Ki Stack Orient

ki-stack-orient

Preamble (run first)

Run this before choosing a KiCad workflow:

KI_STACK_DIR="${KI_STACK_DIR:-skills/ki-stack}"
"$KI_STACK_DIR/bin/ki-stack-update-check" 2>/dev/null || true
"$KI_STACK_DIR/bin/kicad-project-find" . 2>/dev/null | sed -n '1,80p' || true
"$KI_STACK_DIR/bin/kicad-version" 2>/dev/null || true
"$KI_STACK_DIR/bin/kicad-python-smoke" 2>/dev/null || true

Read these when the task touches the area:

• skills/ki-stack/ETHOS.md
• skills/ki-stack/references/version-matrix.md
• skills/ki-stack/references/render-recipes.md
• skills/ki-stack/references/ipc-recipes.md
• skills/ki-stack/references/ipc-board-workflows.md
• skills/ki-stack/references/file-editing-recipes.md

Stack Rules

• PCB editor interaction or current selection: use kicad-python IPC.
• Render, import/export, DRC, ERC, fabrication, 3D outputs: use kicad-cli.
• Schematic/library/project file edits: use kicad-skip, kiutils-rs, or another structured parser. Do not hand-roll S-expression edits when a parser fits.
• Parts search and KiCad-ready vendor artifacts: check https://pcbparts.dev/ early.
• File format truth: use KiCad developer file-format docs at https://dev-docs.kicad.org/en/file-formats/.
• No success claim without evidence: artifact path, DRC/ERC output, changed file list, or script output.

Completion Status

• DONE: completed and verified.
• DONE_WITH_CONCERNS: completed but proof is partial, version-limited, or blocked by pre-existing issues.
• BLOCKED: prerequisite unavailable or command failed after a concrete attempt.
• NEEDS_CONTEXT: target file, object, board session, or intended result is unclear.

Purpose

This is the first skill for KiCad work. It makes the agent stop guessing and quickly answer:

1. What KiCad files are present?
2. What KiCad version and CLI are available?
3. Are Python IPC bindings installed?
4. Is a live KiCad board reachable?
5. Which substrate should do the work?

Decision Table

| User intent | First route | Why | | --- | --- | --- | | Current board, selected items, interactive PCB editor state | ki-stack-live / ki-stack-pcb with kicad-python | IPC sees the open editor and selection. | | Move/inspect/update footprints, tracks, vias, zones, layers | ki-stack-pcb with kicad-python | This is PCB editor interaction. | | Render board/schematic/symbol/footprint | ki-stack-render with kicad-cli | Deterministic visual artifact. | | DRC/ERC, fabrication, 3D, BOM/netlist/export/import/upgrade | ki-stack-verify or ki-stack-render with kicad-cli | The CLI already owns these flows. | | Schematic/project/library text-variable or symbol metadata edit | ki-stack-file-surgery with kicad-skip or kiutils-rs | Structured file edit beats raw S-expression surgery. | | Need a new part, JLC/LCSC/CSE artifact, KiCad symbol/footprint | Search https://pcbparts.dev/ first | Parts search is a solved external data problem. | | Unsure what a token means | KiCad file-format docs | https://dev-docs.kicad.org/en/file-formats/ is source of truth. |

CLI Surface To Remember

kicad-cli covers much more than render:

• api-server: headless IPC server on newer KiCad.
• fp: footprint export and upgrade.
• gerber: convert, diff, inspect Gerber files.
• jobset: run .kicad_jobset outputs.
• pcb: DRC, import, upgrade, render, export.
• sch: ERC, upgrade, BOM, netlist, PDF/SVG/PNG/DXF/HPGL/PostScript.
• sym: symbol export and upgrade.
• version: version info.

High-value PCB exports:

• fabrication: Gerber, drill, position, IPC-D-356, IPC-2581, ODB++, GenCAD.
• documentation: PDF, SVG, PNG, DXF, HPGL, PostScript, statistics.
• 3D/mechanical: STEP, STEPZ, STL, GLB, VRML, PLY, U3D, BREP, XAO, 3D PDF.

Orient Commands

KI_STACK_DIR="${KI_STACK_DIR:-skills/ki-stack}"
"$KI_STACK_DIR/bin/kicad-project-find" .
"$KI_STACK_DIR/bin/kicad-version"
"$KI_STACK_DIR/bin/kicad-python-smoke"
"$KI_STACK_DIR/bin/kicad-python-smoke" connect

If connect fails, do not force IPC. Use the error to decide:

• import failed: install or fix kicad-python.
• connect failed: KiCad GUI/API server not reachable.
• board failed: KiCad reachable but no board open.

Evidence Contract

Before ending a KiCad task, produce at least one:

• rendered artifact path
• DRC/ERC JSON path and pass/fail summary
• IPC script output
• structured parser output or changed file diff
• part-search source URL or artifact path

Completion

Report:

KI-STACK ORIENT
Files: 
KiCad: 
IPC: 
Route: 
Next skill: 
Status: DONE|DONE_WITH_CONCERNS|BLOCKED|NEEDS_CONTEXT

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Milind220
• Source: Milind220/Ki-Stack
• License: MIT

Install and usage instructions live in the source repository linked above.