Skip to content

README.md

Latest commit

 

History

History
217 lines (147 loc) · 6.03 KB

README.md

File metadata and controls

217 lines (147 loc) · 6.03 KB

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-orient First stop for KiCad work: find project files, check KiCad CLI/version, probe Python IPC, and choose live IPC vs CLI vs structured file edits.

  • 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-orient/
  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

scripts/gen-skill-docs --check
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

For a new KiCad task, start with ki-stack-orient. It routes:

  • PCB editor/current-selection work to kicad-python
  • render, import/export, DRC/ERC, fabrication, and mechanical outputs to kicad-cli
  • schematic/library/project file edits to structured file libraries such as kicad-skip or kiutils-rs
  • part search to https://pcbparts.dev/
  • token/file-format questions to KiCad's file-format docs: https://dev-docs.kicad.org/en/file-formats/

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.