Schematic Analyzer
Analysis of KiCad schematics, or Cadence OrCAD/Allegro schematics (Allegro netlist pstxnet.dat/pstxprt.dat combined with OrCAD Capture XML export .xml) via CLI tools. Produces accurate answers—query what's needed for reliable conclusions, never dumps raw files, never guesses without grounding.
Core Principle
Accuracy first, efficiency second.
Choose mode first, query what's needed for reliable conclusion.
Structure first, semantics when blocked.
Instructions
Step 1: Confirm the required environment
Before analyzing a project, confirm the inputs and runtime needed for that file type:
- For any project,
python3and the CLI script must be available - For KiCad projects,
kicad-climust be available onPATH - For Cadence projects, require
pstxnet.dat,pstxprt.dat, and the OrCAD Capture XML export together - For datasheet-dependent questions, require the relevant datasheet PDF or escalate to
ee-datasheet-master
If a required dependency or input is missing:
- Stop before claiming the skill is usable for this task
- State exactly what is missing
- Tell the user the skill may be installed, but the current task is blocked until that requirement is provided
Step 2: Choose the entry mode
Choose mode first, then query only what is needed for a reliable conclusion:
- Architecture or review tasks: start with
overview - Targeted component or net questions: start with direct
query - Pattern searches: use
query --pattern <yaml_file>
Step 3: Escalate only when structure is insufficient
Use this escalation order:
- Structural evidence from the schematic
pcbpartsMCP for part identity or package/spec cluesee-datasheet-masterfor pin functions or electrical behavior- Re-ground the conclusion back to the schematic evidence
Iron Rule
Accuracy and evidence override coverage. Every claim requires direct evidence of the matching type.
If evidence does not support a conclusion:
- Return
Unknownor a lower-confidence result - State which evidence is present and missing
- Avoid inventing roles or meanings to make output look complete
No evidence, no assertion; weak evidence, weak conclusion.
Each claim type demands specific evidence — a device's power domain requires checking its VDD/VCC pin, an interface mode requires tracing all signal lines to their endpoints, not just some. Inferences from device type, connector names, page location, or neighboring components are not sufficient on their own. See the evidence requirements table in SCHEMATIC_STRATEGY.md Rule 6.
CLI Commands
The skill uses three commands only:
overview — Project First Look
python scripts/schematic-cli.py overview <project>
Output:
- Project page count, component count, net count
- Page navigation (numbered index for
--pagequeries) - Core component candidates (ranked by structural connectivity)
Use when: Architecture analysis, design review, or need page context.
query — Inspect Objects
All query commands output JSON. Key fields for filtering:
| Query Type | Top-level Keys | Sub-object Keys |
|---|---|---|
--page |
index, name, file, type, components, nets | components[i]: ref, value, mpn; nets[i]: name, pin_count |
--component |
ref, value, mpn, page_index, properties, nets, neighbors | nets[i]: name, pin; neighbors: shared_nets |
--net |
name, hierarchical_labels, global_labels, local_labels, pages, pins | pins[i]: ref, pin |
--property |
key, values | values[i]: mpn, refs |
# Query by page index (from overview)
python scripts/schematic-cli.py query <project> --page <index>
# → Filter large output:
# | python -c "import sys,json; d=json.load(sys.stdin); print([c['ref'] for c in d['components']])"
# | python -c "import sys,json; d=json.load(sys.stdin); print([n['name'] for n in d['nets']])"
# Query component by reference
python scripts/schematic-cli.py query <project> --component <ref> # filtered (active pins)
python scripts/schematic-cli.py query <project> --component <ref> --full # complete (includes unconnected)
# → Filter large output:
# | python -c "import sys,json; d=json.load(sys.stdin); print(d.get('value'), d.get('mpn'))"
# | python -c "import sys,json; import json as j; d=j.load(sys.stdin); del d['neighbors']; print(j.dumps(d, indent=2))"
# Search components by text
python scripts/schematic-cli.py query <project> --component --match <text>
# Query net by exact name
python scripts/schematic-cli.py query <project> --net <name>
# Search nets by text
python scripts/schematic-cli.py query <project> --net --match <text>
# Query property values
python scripts/schematic-cli.py query <project> --property <key>
# → Filter large output:
# | python -c "import sys,json; d=json.load(sys.stdin); print([v['mpn'] for v in d['values'] if v['mpn']])"
# Pattern matching (explicit YAML required)
python scripts/schematic-cli.py query <project> --pattern <yaml_file>
--full switch: Use only when blocker requires complete pin-net mapping (e.g., "which pins are unconnected"). Default filtered output hides unconnected-* pins.
cache — Cache Management
python scripts/schematic-cli.py cache <project> --status
python scripts/schematic-cli.py cache <project> --clear
Negative Evidence
What is NOT connected is as important as what IS connected.
- Unconnected signal lines indicate reduced operating mode
- DNP components indicate optional/alternative configuration
- Missing connections are facts, not gaps to fill with assumptions
When determining interface mode or device configuration:
- Check ALL signal lines, not just the ones that are connected
- Unconnected lines are evidence of operating mode, not "incomplete design"
- Do not assume a function is active because the pin name suggests it
Anti-Patterns
Don't: Dump Raw Files
❌ Read the entire .kicad_sch, Cadence XML, or Allegro netlist files
❌ Paste full netlist into context
❌ Export all JSON and load into prompt
Don't: Batch Everything
❌ Look up 50 MPNs in MCP before understanding the design
❌ Read all datasheets before identifying core components
Don't: Guess Without Evidence
❌ "U10 is probably the main controller" (without connectivity evidence)
❌ "This is a power supply" (without checking nets)
Don't: Always Run Overview
❌ Run overview before every targeted query (--component U10)
❌ Run overview when user asks about a specific net (--net GND)
✓ Run overview only when: architecture mode, review mode, or need page context
Don't: Infer From One Side of a Connection
❌ Conclude interface mode from connector pin names alone without tracing signal lines to controller
❌ Conclude device power domain from bus pull-up voltage or neighboring device power
❌ Assume devices on the same bus share the same power domain
❌ Assume a function is active because the pin name suggests it, without checking the other endpoint
Don't: Ignore What's NOT Connected
❌ Skip unconnected signal lines when determining interface mode
❌ Overlook diode-connected power paths as "just protection"
❌ Fill in missing evidence with assumptions to make output look complete
Reading Strategy
For entry mode selection, reading loop, and detailed workflow, see SCHEMATIC_STRATEGY.md.
Never: Dump full .kicad_sch files, Cadence XML files, Allegro netlist files, or exported JSON into context.
MCP Integration
pcbparts tools
mcp__pcbparts__jlc_search: Search component by part numbermcp__pcbparts__jlc_get_part: Get detailed specs by LCSC code
Use when: Component role unclear from structure alone, need part specs.
ee-datasheet-master skill
Use when: MCP has no data and you need pin functions, electrical specs, or device-specific behavior.
How to invoke:
/ee-datasheet-master <datasheet_path> "<question>"
Critical rules:
- Invoke the skill explicitly — do not read datasheets with general PDF tools
- No datasheet? Ask user — if the required datasheet is not available, ask the user to provide it:
- "I need the datasheet for to answer about . Can you provide the PDF?"
- Never guess datasheet content — do not rely on prior knowledge or assume specifications
Escalation order: Structural evidence → pcbparts MCP → ee-datasheet-master → re-ground to schematic.
Troubleshooting
Error: No module named 'yaml' or another Python import failure
Cause: Python dependencies are missing.
Solution: Run pip install -r scripts/requirements.txt before continuing.
Error: kicad-cli: command not found
Cause: KiCad CLI is required for KiCad netlist export but is not installed or not on PATH.
Solution: Install KiCad, ensure kicad-cli is on PATH, and do not continue KiCad analysis until this is fixed.
Error: KiCad project opens but connectivity is incomplete
Cause: Netlist export failed, project path is wrong, or the project is only partially available.
Solution: Verify the project root path, rerun overview, and in hierarchical designs confirm the correct root schematic was selected.
Error: Cadence query lacks pages or component metadata
Cause: Allegro netlist files and OrCAD XML are both required; one side is missing.
Solution: Require pstxnet.dat, pstxprt.dat, and the Capture XML export together. If any one is missing, state that the project is only partially analyzable.
Error: MCP lookup is unavailable
Cause: pcbparts MCP is optional and not configured.
Solution: Continue with structure-only analysis when possible, but state that part/spec lookup is limited without MCP.
Error: The question depends on a datasheet, but no datasheet is available
Cause: Structural evidence identifies the device but not the required pin function or electrical spec.
Solution: Ask for the datasheet PDF or invoke ee-datasheet-master if the PDF is available. Do not answer from prior knowledge.
Error: Query result is ambiguous
Cause: Multiple refs or nets match, or the evidence is incomplete.
Solution: Return the competing candidates, state what extra query would disambiguate the answer, and prefer Unknown over a confident guess.
Examples
Example 1: Targeted Query
User: "U10 是什么?"
# Direct query, no overview - extract basic identity
python scripts/schematic-cli.py query data/E1005/ --component U10 \
| python -c "import sys,json; d=json.load(sys.stdin); print(f\"Value: {d['value']}, MPN: {d.get('mpn')}, Page: {d['page_name']}\")"
# If need net summary for context:
# | python -c "import sys,json; d=json.load(sys.stdin); print(f\"Nets ({len(d['nets'])}): {[n['name'].split('/')[-1] for n in d['nets'][:5]]}...\")"
# If role unclear, escalate to MCP
Example 2: Architecture Analysis
User: "分析这个项目的整体架构"
# Architecture mode follows SCHEMATIC_STRATEGY.md Rule 1 + Reading Loop:
# start with project scope, then page decomposition, then core anchors, then cross-page nets.
# Step 1: overview establishes page index + core candidates
python scripts/schematic-cli.py overview data/E1005/
# From overview, identify:
# - top core candidate(s)
# - page indices for main logic, power, peripherals, display, etc.
# Step 2: inspect the populated architecture pages identified by overview
python scripts/schematic-cli.py query data/E1005/ --page 8 \
| python -c "import sys,json; d=json.load(sys.stdin); print(f\"MCU page {d['index']} {d['name']}: components={[c['ref'] + ':' + c['value'] for c in d['components'] if c['ref'].startswith('U')][:8]}, nets={[n['name'].split('/')[-1] for n in d['nets'][:8]]}\")"
python scripts/schematic-cli.py query data/E1005/ --page 6 \
| python -c "import sys,json; d=json.load(sys.stdin); print(f\"Power page {d['index']} {d['name']}: components={[c['ref'] + ':' + c['value'] for c in d['components'] if c['ref'].startswith('U')][:8]}, nets={[n['name'].split('/')[-1] for n in d['nets'][:8]]}\")"
python scripts/schematic-cli.py query data/E1005/ --page 10 \
| python -c "import sys,json; d=json.load(sys.stdin); print(f\"I/O page {d['index']} {d['name']}: components={[c['ref'] + ':' + c['value'] for c in d['components'] if c['ref'].startswith(('U','J','USB'))][:8]}, nets={[n['name'].split('/')[-1] for n in d['nets'][:8]]}\")"
# Step 3: inspect the top core component from overview, but read it as an index into the design
python scripts/schematic-cli.py query data/E1005/ --component U10 \
| python -c "import sys,json; d=json.load(sys.stdin); neighbors = sorted(d['neighbors']['shared_nets'], key=lambda x: x['fanout'], reverse=True)[:8]; print(f\"Core {d['ref']} {d['value']} on {d['page_name']}: top_shared_nets={[(n['net'].split('/')[-1], n['fanout']) for n in neighbors]}\")"
# Step 4: expand around one verified cross-page net from the core to identify subsystem participants
python scripts/schematic-cli.py query data/E1005/ --net /SCH_TOP/USB_DP \
| python -c "import sys,json; d=json.load(sys.stdin); refs=sorted(set(p['ref'] for p in d['pins'])); print(f\"Net {d['name'].split('/')[-1]}: pages={d['pages']}, refs={refs}\")"
# Step 5: only after the structure is grounded, inspect secondary anchors such as power or peripherals
python scripts/schematic-cli.py query data/E1005/ --component U1 \
| python -c "import sys,json; d=json.load(sys.stdin); nets=[n['name'].split('/')[-1] for n in d['nets'] if any(k in n['name'].upper() for k in ['VIN','VBUS','VSYS','3V3','BAT'])]; print(f\"Power anchor {d['ref']} {d['value']}: nets={nets}\")"
# At this point, do not rush to summarize the whole project.
# These commands should tell you whether the design skeleton is clear: who is the main controller,
# where power comes in and is converted, and how one major external interface reaches the core.
# If that skeleton is still incomplete, look at the missing subsystem next rather than jumping around.
# A good architecture answer should read like connected blocks: controller, power, I/O, peripherals, display/storage.
# If one of those blocks is still vague, keep expanding from the nearest confirmed page, net, or anchor component.
Example 3: Bus Detection
User: "I2C 总线上挂了哪些设备?"
# Pattern mode workflow (see SCHEMATIC_STRATEGY.md Rule 1):
# Step 1: Discover actual I2C signal names in this project (--match supports regex)
python scripts/schematic-cli.py query data/E1005/ --net --match "SDA|SCL|I2C"
# Output shows hierarchical_labels: MISC_I2C_SCL, BFG_I2C_SDA, etc.
# Each match includes: name, kind (net/hierarchical_label/local_label), pages, pin_count
# Step 2: If I2C uses GPIO naming, search with $ anchor for exact match:
python scripts/schematic-cli.py query data/E1005/ --net --match "GPIO0$|GPIO1$"
# Use $ to avoid matching GPIO10, GPIO11, etc.
# Output reveals: GPIO0/GPIO1 are used for main I2C in this design
# Step 3: Trace the net to get ALL participants on the bus
python scripts/schematic-cli.py query data/E1005/ --net "/SCH_TOP/ESP32-S3R8/GPIO0" \
| python -c "import sys,json; d=json.load(sys.stdin); refs = sorted(set(p['ref'] for p in d['pins'])); print(f\"I2C participants: {refs}\")"
# Output: I2C participants: ['R58', 'U10', 'U14', 'U15', 'U16', 'U5', 'U6']
# This answers the user's question directly!
# Step 4: (Optional) Write a custom pattern YAML for validation
# Create /tmp/i2c_custom.yaml:
# name: "I2C"
# category: bus
# description: "I2C bus"
# signals:
# - role: scl
# patterns: ["(?i)GPIO0$"]
# required: true
# group_key: true
# - role: sda
# patterns: ["(?i)GPIO1$"]
# required: true
# group_key: true
# controller:
# detect_by: core_component
# Step 5: (Optional) Run pattern query with custom YAML
python scripts/schematic-cli.py query data/E1005/ --pattern /tmp/i2c_custom.yaml
Example 4: Design Review
User: "电源设计有问题吗?"
# Review mode: overview to find power page
python scripts/schematic-cli.py overview data/E1005/
# Query power page - extract power ICs only (U-prefix components)
python scripts/schematic-cli.py query data/E1005/ --page 6 \
| python -c "import sys,json; d=json.load(sys.stdin); ics = [c for c in d['components'] if c['ref'].startswith('U')]; print(f\"Power ICs: {[(c['ref'], c['value'], c.get('mpn','')) for c in ics]}\")"
# Or extract power-related nets (VDD, VSYS, GND, etc.)
python scripts/schematic-cli.py query data/E1005/ --page 6 \
| python -c "import sys,json; d=json.load(sys.stdin); power = [n for n in d['nets'] if any(k in n['name'].upper() for k in ['VDD','VSYS','VBAT','VIN','GND','3V3','5V'])]; print(f\"Power nets: {[(n['name'].split('/')[-1], n['pin_count']) for n in power[:10]]}\")"
# Identify power ICs, escalate to MCP for specs
# Check against schematic: capacitors present? enable pins correct?
# Report findings with evidence