# Kicad Project

> >

- **Type:** Skill
- **Install:** `agentstack add skill-avatarsd-kiskill-kicad-project`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AvatarSD](https://agentstack.voostack.com/s/avatarsd)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AvatarSD](https://github.com/AvatarSD)
- **Source:** https://github.com/AvatarSD/KiSkill/tree/main/skills/kicad-project

## Install

```sh
agentstack add skill-avatarsd-kiskill-kicad-project
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# KiCad project state machine

Repo: `$(kx root)` (engine + design docs).

## Session entry protocol (always)

1. `kx env PROJECT_DIR` — one call: kicad-cli (+nightly) version, lock
   files (tilde = literal filename prefix), IPC socket/aliveness,
   recommended backend. If `backends.file.writable_now` is false, KiCad
   has the project OPEN: do not write; ask the user to close/reload, or
   work on a scratch copy.
   `kx` = ~/.local/bin/kx → repo bin/kx (self-sets PYTHONPATH; works
   from any cwd). Python API instead: run with
   PYTHONPATH=$(kx root) (no pip install).
   kicad-cli is resolved by kicad_lib/kcli.py: KX_KICAD_CLI env →
   native on PATH → flatpak → nightly. VERSION-SKEW RULE: evidence
   (ERC/render/netlist) must come from the same engine that writes the
   files — if the user edits with the v11 nightly, set
   `KX_KICAD_CLI=kicad-cli-nightly` for the session; a stable CLI may
   misread nightly-saved files and the diff/ERC evidence silently lies.
2. Git: checkpoint-commit the project BEFORE the first modification.
3. `kx probe FILE` — inventory (uuid, paper, symbols/refs, labels,
   sheets, cached libs).

## State machine (DESIGN.md §3)

CLEAN → PROBED → STAGED → VERIFIED (geometric verifier 0 violations) →
RENDERED (svg→png, ERC run) → REVIEWED (pixel+semantic+ERC diff judged
against rule canon) → COMMITTED. Never skip a state; never write a file
that has not passed VERIFIED; never commit one that has not been REVIEWED.

## Live IPC against the v11 nightly (validated 10.99.0 build 87de73b)

- Enable once (KiCad closed): set `api.enable_server: true` in
  `~/.config/kicad/10.99/kicad_common.json`.
- Launch on a SCRATCH COPY (the nightly upgrades file formats on save):
  `DISPLAY=:1 sh -c '. /usr/share/kicad-nightly/kicad-nightly.env &&
  /usr/lib/kicad-nightly/bin/eeschema COPY.kicad_sch'` in background.
  GUI needs X11 — pick the `DISPLAY` where `xset q` answers. Kill it
  later with pkill; then rm stale `~*.lck` files.
- Socket appears at `/tmp/kicad/api.sock` within ~1 s; verify with
  `kx env` → `ipc_alive: true`, `open_documents` lists the schematic.
- kipy MASTER is required (PyPI 0.7.1's schematic module is broken
  against its own protos). Bootstrap: `tools/bootstrap_kipy.sh`
  (protoc 29.x in ~/.local + protol; .pth-installs .tools/kicad-python).
- HANDLER MAP (each frame registers its own handlers in-process):
  - standalone eeschema HANDLES: get_open_documents, get_schematic,
    get_items/symbols/lines/labels/text, begin/push commit,
    create_items, remove_items — full live editing, undoable in GUI.
  - standalone eeschema LACKS (ApiError "no handler"): ping,
    get_version, save, save_as, revert, run_action — the agent CANNOT
    persist from IPC; the USER saves (Ctrl+S), or do at-rest edits via
    the file backend instead.
  - kicad PM process handles ONLY ping + get_version (no frames).
    Opening eeschema FROM the PM should merge both sets — needs one GUI
    click (no xdotool on this box). Re-test on newer nightlies:
    tests/test_live_ipc.py prints the gap map and flags improvements.
- live.py's ipc_ping treats a structured ApiError as alive (transport
  answered). `kicad-cli-nightly` (wrapper in /usr/bin) is the only way
  to run the nightly CLI — the raw binary fails on LD_LIBRARY_PATH.

## Project hygiene

- References are global across ALL sheets — collision-check project-wide.
- Preserve root uuid and per-sheet uuids; instance paths depend on them.
- sym-lib-table / fp-lib-table: project-local libs use `${KIPRJMOD}` URIs.
- Scratch outputs (svg_out/, *.rpt, *.net, *.png) never get committed.

## Source & license

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

- **Author:** [AvatarSD](https://github.com/AvatarSD)
- **Source:** [AvatarSD/KiSkill](https://github.com/AvatarSD/KiSkill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-avatarsd-kiskill-kicad-project
- Seller: https://agentstack.voostack.com/s/avatarsd
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.