kicad-tools-skill

AI skill for automating KiCad project workflows via the kicad-tools CLI (kct). Enables AI agents (GitHub Copilot, Google Antigravity, and others supporting the open Agent Skills standard) to analyze, validate, repair, and export KiCad projects — no MCP server required.

Table of Contents

• kicad-tools-skill
  • Table of Contents
  • Features
  • Compatibility
  • Project Structure
  • Installation
    • GitHub Copilot (VS Code)
    • Google Antigravity
    • Other AI Tools
  • How It Works
  • Supported Workflows
  • Requirements
  • Troubleshooting
  • Related Projects
  • Contributing
  • License
  • Support

Features

• Schematic Analysis — symbol listing, net tracing, hierarchy validation, BOM generation
• PCB Analysis — board summary, footprint tracing, nets, traces, and layer stackup
• DRC/ERC Validation — pure Python DRC (no kicad-cli), manufacturer rule checking (JLCPCB, OSHPark, PCBWay, Seeed)
• Schematic Repair — symbol swapping, value/footprint setting, wire cleanup, component addition
• PCB Repair — clearance repair, DRC repair, via repair, silkscreen, footprint fixes
• Autorouting — routing with strategy escalation (2L → 4L → 6L), checkpoints, auto-fix DRC
• Placement Optimization — CMA-ES optimizer with anchor-weight for locked footprints
• Manufacturing Export — Gerber generation, BOM, CPL, PDF reports, production readiness validation
• Library Tools — footprint generation, LCSC component search, datasheet parsing
• Auto-install — automatic .venv creation and kicad-tools installation from PyPI when the tool is not available

Compatibility

The skill uses the open Agent Skills standard (SKILL.md + YAML frontmatter), ensuring compatibility with multiple AI tools:

Tool	Skill Path	Status
GitHub Copilot (VS Code)	.github/skills/kicad-tools/	✅ Native support
Google Antigravity	.agents/skills/kicad-tools/	✅ Native support
Claude Code	.claude/commands/	✅ Native support in kicad-tools
Cursor	.cursor/rules/	⚠️ Requires format adaptation

Note: kicad-tools provides native slash commands for Claude Code in .claude/commands/. This skill (Agent Skills format) is intended primarily for GitHub Copilot and Google Antigravity. The core — kct commands with --format json — is universal and AI tool-agnostic.

Project Structure

kicad-tools/
├── SKILL.md                    # Main agent instructions (required)
└── resources/
    ├── cli-reference.md        # Full reference for ~50 kct commands
    └── workflows.md            # Detailed multi-phase workflows

File	Description	Size
SKILL.md	Environment bootstrapping, command quick reference, workflow patterns, constraints, troubleshooting	~340 lines
resources/cli-reference.md	Complete CLI documentation — all commands, flags, exit codes, environment variables	~450 lines
resources/workflows.md	6 multi-phase workflows: schematic review/repair, PCB review/repair, manufacturing export, full build pipeline	~330 lines

Installation

GitHub Copilot (VS Code)

Copy the entire kicad-tools/ folder to the .github/skills/ directory in your workspace:

<your-workspace>/
└── .github/
    └── skills/
        └── kicad-tools/
            ├── SKILL.md
            └── resources/
                ├── cli-reference.md
                └── workflows.md

The skill will be automatically detected by GitHub Copilot.

Google Antigravity

Copy the entire kicad-tools/ folder to the .agents/skills/ directory in your workspace:

<your-workspace>/
└── .agents/
    └── skills/
        └── kicad-tools/
            ├── SKILL.md
            └── resources/
                ├── cli-reference.md
                └── workflows.md

Other AI Tools

The content of SKILL.md and resources/ files can be adapted for any AI tool that supports contextual instructions. The core consists of kct commands run in a terminal — the format is universal.

How It Works

1. Discovery — The agent sees the skill name and description in the list of available skills
2. Activation — When the user mentions KiCad files or EDA tasks, the agent loads the full SKILL.md
3. Bootstrap — The agent checks kct --version availability; if missing — creates a .venv and installs kicad-tools from PyPI
4. Execution — The agent runs kct commands in the terminal with --format json and parses the results
5. Progressive disclosure — For complex tasks, the agent reaches for resources/cli-reference.md or resources/workflows.md

Supported Workflows

Workflow	Description	Source
Schematic Review	4-phase schematic review: pre-checks → per-sheet analysis → cross-sheet analysis → report	resources/workflows.md
Schematic Repair	4-phase repair process: gather context → triage → execute repairs → verification	resources/workflows.md
PCB Review	4-phase PCB review: pre-checks → per-layer analysis → cross-layer analysis → report	resources/workflows.md
PCB Repair	4-phase repair process: baseline → triage → execute → verification	resources/workflows.md
Manufacturing Export	6-phase export: validation → manufacturer → export → verify → copy → report	resources/workflows.md
Full Build Pipeline	Complete pipeline: schematic → ERC → PCB → route → stitch → verify → export	resources/workflows.md

Workflows were adapted from the official slash commands in the kicad-tools repository (.claude/commands/).

Requirements

• Python 3.10+ — for .venv creation and kicad-tools installation
• AI tool supporting the Agent Skills format (GitHub Copilot, Google Antigravity, or other)
• KiCad 8+ (optional) — required only for kct erc and kct drc (kicad-cli report parsing). The kct check command (pure Python DRC) does not require a KiCad installation

Troubleshooting

Problem	Solution
kct: command not found	The agent will automatically create a .venv and install kicad-tools. If not — run manually: python -m venv .venv && .venv\Scripts\Activate.ps1 && pip install kicad-tools
kicad-cli not found	Affects only kct erc/kct drc. Solutions: 1) set the KICAD_CLI_PATH variable, e.g. $env:KICAD_CLI_PATH = "C:\Program Files\KiCad\<version>\bin\kicad-cli.exe" 2) add the KiCad bin folder to PATH 3) use kct check instead — pure Python DRC, no kicad-cli required
ImportError: no module named ...	Some commands require optional extras. Activate the .venv and install the appropriate package: pip install "kicad-tools[datasheet]", pip install "kicad-tools[drc]", pip install "kicad-tools[route]", pip install "kicad-tools[lcsc]". The agent will do this automatically after user confirmation
Skill does not activate	Make sure the folder is in the correct path (.github/skills/ for Copilot, .agents/skills/ for Antigravity)

Related Projects

• kicad-tools — Source CLI tools for working with KiCad (Python, MIT)
• KiCad — Open-source EDA software for electronics design
• Agent Skills (open standard) — Open standard for extending AI agent capabilities

Contributing

Bug reports and improvement suggestions are welcome. Create an issue on GitHub.

License

Copyright © 2026 Michal Protasowicki

This project is licensed under the MIT License.

Author: Michał Protasowicki

Support

If you find my projects interesting and would like to support my work, you can buy me a coffee or a barrel of beer :)