Ki-Stack

Deep skills for coding agents that need to work in KiCad.

ki-stack is a skill-first KiCad automation stack for agents like Claude Code, Codex, and OpenCode. Instead of forcing the model through a giant pile of tiny domain-specific tools, it teaches the model how to use the real, expressive action space it already has:

• kicad-python for live IPC automation
• kicad-cli for render, export, DRC, and ERC
• kiutils-rs for structural offline file surgery

The result is a stack that is closer to a KiCad operating manual for coding agents than a brittle tool zoo.

Why

KiCad tasks are open-ended.

Agents do better when they can:

• write code
• inspect live state
• render artifacts for vision
• run checks
• recover and reroute when one path fails

They do worse when intelligence is pre-sliced into dozens or hundreds of tiny atomic verbs.

ki-stack is built around that idea.

What is in here

Phase 1 substrate skills

• ki-stack-render Render schematics, PCBs, symbols, and footprints into SVG, PDF, PNG, and JPEG workflows.

• ki-stack-live Use the official Python IPC bindings as the main live action space.

• ki-stack-file-surgery Do deterministic structural file edits with kiutils-rs.

• ki-stack-verify Prove changes with render-after-edit, DRC, ERC, and evidence-first reporting.

Phase 2 domain skills

• ki-stack-pcb
• ki-stack-schematic
• ki-stack-symbols
• ki-stack-footprints

These compose the Phase 1 substrate skills into domain-specific workflows.

Repo layout

skills/ki-stack/
  ETHOS.md
  bin/
  references/
  templates/
  examples/
  ki-stack-render/
  ki-stack-live/
  ki-stack-file-surgery/
  ki-stack-verify/
  ki-stack-pcb/
  ki-stack-schematic/
  ki-stack-symbols/
  ki-stack-footprints/
docs/

Highlights

• G-Stack-style skill structure: discoverability, shared ethos, shared preamble mindset, helper scripts, references, templates, and phased workflows
• real helper scripts for kicad-cli, DRC/ERC JSON, project discovery, SVG-to-PNG conversion, and kiutils-inspect
• copy-paste Python IPC examples for common board tasks
• domain skills layered on top of substrate skills instead of duplicating raw primitive guidance

Quick start

1. Requirements

• KiCad installed with kicad-cli
• Python 3
• Rust toolchain for kiutils-rs workflows
• optionally kicad-python installed:

pip install kicad-python

2. Inspect your KiCad environment

skills/ki-stack/bin/kicad-cli-path
skills/ki-stack/bin/kicad-version
skills/ki-stack/bin/kicad-python-smoke
skills/ki-stack/bin/ki-stack-version

2.5 Install the skills into OpenCode

OpenCode discovers skills from directories like ~/.config/opencode/skills/<name>/SKILL.md.

This repo is organized as a skill pack, so the easiest install path is:

skills/ki-stack/bin/ki-stack-install-opencode

That symlinks all ki-stack-* skills into ~/.config/opencode/skills/.

If you prefer, you can also symlink or copy the individual skill folders manually into:

• ~/.config/opencode/skills/
• ~/.claude/skills/
• ~/.agents/skills/

3. Render something immediately

skills/ki-stack/bin/kicad-render pcb-render board.kicad_pcb board.png --width 1800 --height 1200 --side top

4. Try a live IPC example

python3 skills/ki-stack/examples/ipc/board_inventory.py

5. Run verification

skills/ki-stack/bin/kicad-drc-json board.kicad_pcb drc.json
skills/ki-stack/bin/kicad-erc-json design.kicad_sch erc.json

6. Check for updates

skills/ki-stack/bin/ki-stack-update-check

If a newer release is available, it prints:

UPGRADE_AVAILABLE <current> <latest>

Otherwise it stays quiet.

The core idea

This repo is not trying to hide KiCad behind a fake universal abstraction.

It is trying to teach agents how to use the right native substrate for each job:

• live state and chaining many operations: kicad-python
• rendering and checks: kicad-cli
• structural offline mutation: kiutils-rs

Next directions

• deeper PCB examples for nets, zones, and footprint analysis
• more schematic-side examples
• richer symbol and footprint workflows
• packaging this as a drop-in skill pack for agent environments

Versioning

Ki-Stack now carries a top-level VERSION file.

• current version: read with skills/ki-stack/bin/ki-stack-version
• update detection: skills/ki-stack/bin/ki-stack-update-check

The update checker compares the local VERSION file against the remote VERSION file on GitHub and caches the result locally in ~/.ki-stack/last-update-check.

Recommended release flow:

1. bump VERSION
2. commit the bump
3. create a Git tag like v0.1.0
4. create a GitHub release for that tag

Publishing to the OpenCode ecosystem page

The OpenCode docs do not expose a dedicated skill registry upload flow. The documented way to get listed publicly is to submit a PR to the OpenCode ecosystem page.

Practical path:

1. keep the repo public on GitHub
2. make sure README.md explains what the skill pack does
3. submit a PR to the OpenCode docs/ecosystem list adding Ki-Stack

For local usage, the actual skill installation path is the normal skill discovery directories described above.

Status

Early, but already useful.

The Phase 1 substrate is in place, the first domain skills exist, and the repo is structured to grow without turning into an unreadable pile of notes.