Kicad-happy kidoc

install

source · Clone the upstream repo

git clone https://github.com/aklofas/kicad-happy

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/aklofas/kicad-happy "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/kidoc" ~/.claude/skills/aklofas-kicad-happy-kidoc && rm -rf "$T"

manifest: skills/kidoc/SKILL.md

source content

kidoc — Engineering Documentation Skill

Generate professional engineering documentation from KiCad project files.

Quick Start

One command generates the full scaffold — analyses, diagrams, renders, and markdown are all produced automatically:

python3 skills/kidoc/scripts/kidoc_scaffold.py \
  --project-dir /path/to/kicad/project \
  --type hdd \
  --output reports/HDD.md

This auto-detects

.kicad_sch

and

.kicad_pcb

files, runs schematic/PCB/EMC/thermal analyses, generates block diagrams and schematic SVG renders, and produces a structured markdown scaffold with pre-filled data tables and narrative placeholders.

To produce a PDF:

python3 skills/kidoc/scripts/kidoc_generate.py \
  --project-dir /path/to/kicad/project \
  --doc reports/HDD.md \
  --format pdf

Creates

reports/.venv/

automatically on first run (PDF/DOCX/ODT only — HTML is zero-dep).

Workflow

Generate scaffold —
```
kidoc_scaffold.py
```
auto-runs all available analyses, renders schematics, generates diagrams, and writes the markdown scaffold.
Fill narratives — The agent reads the scaffold and writes engineering prose for each
```

```
placeholder. The engineer reviews and edits.
Regenerate — On re-run, data sections between
```

```
markers update from fresh analysis; user-written narrative content is preserved.
Render output —
```
kidoc_generate.py
```
produces PDF, HTML, DOCX, or ODT.

Document Types

Type	Name	Key Sections
`hdd`	Hardware Design Description	System overview, power, signals, analog, thermal, EMC, PCB, mechanical, BOM, test, compliance
`ce_technical_file`	CE Technical File	Product ID, essential requirements, harmonized standards, risk assessment, Declaration of Conformity
`design_review`	Design Review Package	Review summary (cross-analyzer scores), findings, action items
`icd`	Interface Control Document	Interface list, per-connector pinout details, electrical characteristics
`manufacturing`	Manufacturing Transfer Package	Assembly overview, PCB fab notes, assembly instructions, test procedures
`schematic_review`	Schematic Review Report	System overview, power, signals, analog, BOM, schematic appendix
`power_analysis`	Power Analysis Report	Power design, thermal, EMC, BOM
`emc_report`	EMC Pre-Compliance Report	EMC analysis, compliance, schematic appendix

Custom Reports

Use

--spec

to generate reports with arbitrary section ordering:

python3 skills/kidoc/scripts/kidoc_scaffold.py \
  --project-dir . --spec my-report.json --output reports/custom.md

Spec format (JSON):

{
  "type": "custom",
  "title": "USB Interface Analysis",
  "sections": [
    {"id": "front_matter", "type": "front_matter"},
    {"id": "signal_interfaces", "type": "signal_interfaces"},
    {"id": "bom", "type": "bom_summary"}
  ]
}

Each section's

type

must match a known section type (same names used in the document types table above). The

id

field is a unique key for that section instance.

To see the full default spec for any built-in type:

python3 skills/kidoc/scripts/kidoc_spec.py --expand hdd
python3 skills/kidoc/scripts/kidoc_spec.py --list

The

--spec

flag also works with

kidoc_generate.py

(uses the spec title as fallback project name).

Schematic and PCB Rendering

Rendering is integrated into the figure generation engine. The orchestrator and scaffold automatically render schematics and PCB views as part of document generation:

# Generate all figures (diagrams + schematic/PCB renders) from analysis JSON
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --output reports/figures/

# Full orchestration with spec, analysis, and project files
python3 skills/kidoc/scripts/kidoc_orchestrator.py --analysis schematic.json \
    --project-dir . --output reports/figures/

The figure generators support: full-sheet rendering (root + all sub-sheets), subsystem cropping (

focus_refs

in spec sections), net highlighting, pin-level net annotation, and all PCB layer presets. These options are configured in the document spec or passed through the analysis dict.

Rendering features available through the generator framework:

Crop: Focus on a subsystem bounding box around specific component refs
Focus/dim: Show focused components at full opacity, dim the rest to 15%
Highlight nets: Color-trace specific nets via BFS
Pin nets: Annotate pin-level net names at pin tips

For direct programmatic access, use

figures.renderers

from figures.renderers import render_schematic, render_pcb
render_schematic('design.kicad_sch', 'output/', crop_refs=['R1', 'R2'], highlight_nets=['VCC'])
render_pcb('board.kicad_pcb', 'output/', preset_name='assembly-front')

Layer presets:

Preset	Shows
`assembly-front`	Front silk, fab, pads, outline
`assembly-back`	Back silk, fab, pads, outline (mirrored)
`routing-front`	Front copper, pads, vias, outline
`routing-back`	Back copper, pads, vias, outline
`routing-all`	All copper layers, pads, vias, zones
`power`	Power planes, vias, zone outlines

Additional options:

--highlight-nets

--crop-refs

--crop x,y,w,h

--mirror

--overlay annotations.json

(callout boxes with leader lines).

Block Diagrams

python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --all --output diagrams/
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --power-tree --output diagrams/
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --bus-topology --output diagrams/
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --architecture --output diagrams/

Generated from schematic analysis JSON. Power trees show regulator topology with inductor values, capacitor summaries, and output voltages.

Output Formats

Format	SVG Handling	Dependencies
Markdown	Image references	Zero-dep
HTML	Inlined as vector	Zero-dep
PDF	Vector via svglib, custom converter fallback, raster fallback	Venv ( `reports/.venv/` )
DOCX	Rasterized to 300 DPI PNG	Venv
ODT	Rasterized to 300 DPI PNG	Venv

PDF output includes a styled cover page, table of contents, formatted tables with alternating rows, and vector SVG diagrams.

Configuration

Report settings live in

.kicad-happy.json

under the

"reports"

key. Config files cascade:

~/.kicad-happy.json

(user-level defaults, e.g. company branding) merges with project-level config.

{
  "project": {
    "name": "Widget Board",
    "number": "HW-2024-042",
    "revision": "1.2",
    "company": "Acme Electronics",
    "author": "Jane Smith",
    "market": "eu"
  },
  "reports": {
    "classification": "Company Confidential",
    "documents": [
      {"type": "hdd", "output": "HDD-{project}-{rev}", "formats": ["pdf", "docx"]}
    ],
    "branding": {
      "logo": "templates/logo.png",
      "header_left": "{company}",
      "header_right": "{number} Rev {rev}"
    }
  }
}

Writing Narratives

After generating a scaffold, fill the narrative placeholder sections with engineering prose.

Workflow

Run the context builder to get focused data for each section:

python3 skills/kidoc/scripts/kidoc_narrative.py \
  --analysis analysis/schematic.json \
  --section power_design

Or build contexts for all narrative sections at once:

python3 skills/kidoc/scripts/kidoc_narrative.py \
  --analysis analysis/schematic.json \
  --report reports/HDD.md

For each section, read the context and write prose that:
- Explains why, not just what — engineering rationale, tradeoffs
- References specific component values and part numbers
- Uses quantitative language ("2.3ms hold-up time" not "adequate capacitance")
- Flags deviations from datasheet recommendations
- References SPICE validation results when available
Replace the italic placeholder
```
*[...]*
```
in the markdown with real prose.
On regeneration, data tables update automatically. Review narratives for consistency with any changed data.

Style Guide

Write as a senior EE explaining to a peer:

Lead with the key finding or decision
Support with specific numbers from the analysis
Note any risks or deviations
Keep paragraphs to 3-5 sentences
Don't repeat data that's already in tables

Requirements

Python 3.9+ with
```
python3-venv
```
(for PDF/DOCX/ODT generation)
KiCad schematic file (
```
.kicad_sch
```
, KiCad 6+) — for SVG rendering
Optional: Analysis JSONs are auto-generated from
```
.kicad_sch
```
/
```
.kicad_pcb
```
; pre-generated JSONs in
```
analysis/
```
(or the path configured in
```
.kicad-happy.json
```
) are used if present. Generated figures (diagrams, schematic SVGs) are placed in
```
reports/figures/
```
for git tracking

Limitations

Schematic and PCB renderers support KiCad 6+ formats only (
```
.kicad_sch
```
,
```
.kicad_pcb
```
)
Narrative sections require the agent or manual authoring — the scaffold provides structure and data, not prose
SPICE simulation results require manual simulation setup (not auto-run by scaffold)
PDF vector SVG embedding uses svglib when available; falls back to raster if svglib cannot parse a particular SVG

Related Skills

Skill	Relationship
`kicad`	Produces schematic/PCB/thermal analysis JSON consumed by scaffolds
`emc`	Produces EMC analysis JSON for EMC sections
`spice`	SPICE simulation results appear in analog design sections
`bom`	BOM data appears in BOM summary sections

Run the

kicad

skill's analyzers first, then

emc

and

spice

if available. The scaffold auto-runs

kicad

and

emc

analyses when source files are present, so manual pre-analysis is only needed for SPICE.