kidoc
Generate professional engineering documentation from KiCad projects — Hardware Design Descriptions (HDD), CE Technical Files, Interface Control Documents (ICD), Design Review Packages, and Manufacturing Transfer Packages. Auto-runs schematic, PCB, EMC, and thermal analyses; renders schematic and PCB SVGs with subsystem cropping, focus dimming, net highlighting, and pin-net annotation; generates power tree, bus topology, and architecture block diagrams. Produces styled PDF with cover pages, TOC, and vector SVG embedding. Markdown source of truth — human-editable, version-controllable. Use for "generate documentation", "create report", "HDD", "CE technical file", "design review package", "ICD", "render schematic", "render layout", "generate block diagram", "manufacturing package", "generate PDF", or "custom report".
- Installs
- 167
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/aklofas/kicad-happy --skill kidoc- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads kidoc automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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.pyauto-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
<!-- NARRATIVE: section_name -->placeholder. The engineer reviews and edits. - Regenerate — On re-run, data sections between
<!-- GENERATED: section_id -->markers update from fresh analysis; user-written narrative content is preserved. - Render output —
kidoc_generate.pyproduces 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 |
| 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_designOr 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 inanalysis/(or the path configured in.kicad-happy.json) are used if present. Generated figures (diagrams, schematic SVGs) are placed inreports/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.
FAQ
What does the kidoc skill do?
Generate professional engineering documentation from KiCad projects — Hardware Design Descriptions (HDD), CE Technical Files, Interface Control Documents (ICD), Design Review Packages, and Manufacturing Transfer Packages. Auto-runs schematic, PCB, EMC, and thermal analyses; renders schematic and PCB SVGs with subsystem cropping, focus dimming, net highlighting, and pin-net annotation; generates power tree, bus topology, and architecture block diagrams. Produces styled PDF with cover pages, TOC, and vector SVG embedding. Markdown source of truth — human-editable, version-controllable. Use for "generate documentation", "create report", "HDD", "CE technical file", "design review package", "ICD", "render schematic", "render layout", "generate block diagram", "manufacturing package", "generate PDF", or "custom report".
How do I install kidoc?
Run npx skills add https://github.com/aklofas/kicad-happy --skill kidoc in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/kidoc/ (personal) or .claude/skills/kidoc/ (project).
Which AI agents can use kidoc?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is kidoc safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains kidoc?
It is published by aklofas in aklofas/kicad-happy. It has 167 recorded installs.
More from aklofas/kicad-happy
kicad
aklofas/kicad-happy
Analyze KiCad projects and PDF schematics: schematics, PCB layouts, Gerbers, footprints, symbols, netlists, and design rules. Reviews designs for bugs, traces nets, cross-references schematic to PCB, extracts BOM data, checks DRC/ERC, DFM, power trees, and regulator circuits. Every finding carries a confidence label and evidence source with trustsummary rollup. Analyzes PDF schematics from dev boards, reference designs, eval kits, and datasheets. Supports KiCad 5–10. Use whenever the user mentions .kicadsch, .kicadpcb, .kicadpro, PCB design review, schematic analysis, PDF schematics, reference designs, Gerber files, DRC/ERC, netlist issues, BOM extraction, signal tracing, power budget, DFM, or wants to understand, debug, compare, or review any hardware design. Also for "check my board", "review before fab", "what's wrong with my schematic", "is this ready to order", "check my power supply", "verify this circuit", OSHWA certification readiness, or any electronics/PCB design question
jlcpcb
aklofas/kicad-happy
JLCPCB PCB fabrication and assembly — BOM/CPL generation, basic vs extended parts, assembly constraints, design rules, ordering workflow. Use with KiCad for JLCPCB manufacturing. Use this skill when the user mentions JLCPCB, wants to order PCBs or assembled boards, needs prototype bare PCBs and stencils, wants to know JLCPCB design rules and capabilities, or is asking about PCB manufacturing costs or turnaround times. For gerber/CPL export, stencil ordering, and BOM management, see the bom skill.
bom
aklofas/kicad-happy
BOM (Bill of Materials) management for electronics projects — the workflow skill that coordinates DigiKey, Mouser, LCSC, element14, JLCPCB, PCBWay, and KiCad skills around a unified BOM lifecycle. Create, update, and maintain BOMs with part numbers, costs, quantities stored as KiCad symbol properties. ALWAYS trigger this skill for any task involving component sourcing, pricing, ordering, distributor searches, BOM export, or fabrication preparation — even if the user names a specific distributor or fab house (e.g. "search DigiKey for...", "generate JLCPCB BOM", "order from Mouser"). This skill analyzes the schematic for sourcing gaps, recommends which distributor/fab skills to call for each gap, and writes results back as symbol properties — the agent (or user) performs the actual searches via the called skills. Also trigger on phrases like "what parts do I need", "order components", "how much will this cost", "export for JLCPCB", "find parts for this board", "compare pricing", or "chec
lcsc
aklofas/kicad-happy
Search LCSC Electronics for electronic components — find parts by LCSC number (Cxxxxx) or MPN, check stock/pricing, download datasheets, analyze specifications. Sister company to JLCPCB, same parts library. Sync and maintain a local datasheets directory for a KiCad project, or use batch MPN-list seeding (--mpn-list) for bulk workflows without a project. No API key needed — uses the free jlcsearch community API. Use this skill when the user mentions LCSC, JLCPCB parts library, JLCPCB assembly parts, production sourcing, Cxxxxx part numbers, needs to find LCSC equivalents for parts, is preparing a BOM for JLCPCB assembly, or wants to download datasheets and LCSC is available. For package cross-reference tables and BOM workflow, see the bom skill.
spice
aklofas/kicad-happy
Run automatic SPICE simulations on subcircuits detected from KiCad schematic analysis — validates filter frequencies, divider ratios, opamp gains, LC resonance, and crystal load capacitance. Supports ngspice, LTspice, and Xyce (auto-detected). Generates testbenches, runs batch mode, produces structured pass/warn/fail report. Use when the user asks to simulate, verify, or validate any analog subcircuit — RC filters, LC filters, voltage dividers, opamp circuits, crystal oscillators. Also for "simulate my circuit", "run spice", "verify with simulation", "check my filter cutoff", "does this divider give the right voltage", "what's the bandwidth of this opamp stage". Consider suggesting simulation during design reviews when the schematic analyzer reports simulatable subcircuits and a SPICE simulator is available.
emc
aklofas/kicad-happy
EMC pre-compliance risk analysis for KiCad PCB designs — 18 check categories, 44 rule IDs covering ground planes, decoupling, I/O filtering, switching harmonics, clock routing, differential pair skew, board edge radiation, PDN impedance, return paths, crosstalk, ESD protection, shielding, and magnetic leakage from switching inductors. Produces severity-ranked risk report with pre-compliance test plan. Supports FCC Part 15, CISPR 32, CISPR 25 (automotive), MIL-STD-461G. SPICE-enhanced when available. Use when the user asks about EMC, EMI, radiated/conducted emissions, FCC compliance, CE marking, CISPR, ground plane issues, decoupling strategy, clock routing EMC, switching noise, differential pair skew, or whether their board will pass EMC testing. Also for "will this pass FCC?", "check my EMC", "is my ground plane okay?", "check my decoupling", or "generate an EMC test plan".
Popular docs & writing skills
grill-with-docs
mattpocock/skills
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
lark-markdown
open.feishu.cn
飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。
writing-beats
mattpocock/skills
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
writing-shape
mattpocock/skills
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
mattpocock/skills
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
mattpocock/skills
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.