Embedded Systems Architect

Turn week-three surprises into day-one knowledge. An evidence-driven agent skill for embedded systems & edge-AI development — from "here's a board and a pile of vendor docs" to a deployable, verifiable, recoverable plan.

繁體中文版 README · MIT License · v0.1.0

What it is

A skill that turns a general-purpose AI agent into an exploratory, evidence-driven embedded systems architect. Feed it whatever you have — datasheets, SDKs, BSPs, sample code, models, logs, half-bricked boards — and it builds a persistent project context, reasons across every layer of the stack, and converts each unknown into a cheap, observable experiment.

What it is not: a documentation search engine, a spec-sheet reciter, or a flashing script generator. It will not claim a model "runs" because the TOPS number looks big, and it will not hand you an irreversible command.

Quick start

Claude Code — one-line plugin install (recommended; gets updates automatically):

claude plugin marketplace add Zachariah9420/embedded-systems-architect && claude plugin install embedded-systems-architect@embedded-systems-architect

Or inside an interactive session: /plugin marketplace add Zachariah9420/embedded-systems-architect, then /plugin install embedded-systems-architect@embedded-systems-architect.

Claude Code — manual install (plain skill, no plugin system needed):

git clone https://github.com/Zachariah9420/embedded-systems-architect.git ~/.claude/skills/embedded-systems-architect

Windows (PowerShell):

git clone https://github.com/Zachariah9420/embedded-systems-architect.git "$env:USERPROFILE\.claude\skills\embedded-systems-architect"

Then just talk about your board, SDK, model deployment, or flashing problem — the skill triggers on embedded/edge-AI context.

OpenAI Codex — clone anywhere and point the agent at the directory; AGENTS.md routes it to SKILL.md. Cold-start validated (see Evaluation).

Gemini CLI and others — a GEMINI.md adapter is included and the core is plain markdown + standard Python, so it should carry over — but it has not been validated there yet. Reports welcome.

Dependencies: Python 3.9+ (stdlib only for core; onnx / tensorflow optional, with graceful degradation). 7-Zip recommended on Windows for split archives.

How it works

Everything runs through one loop (diagram above), under three design commitments:

1. Evidence tiers on every conclusion

User-quoted specs ("the datasheet says 8 MB") are treated as to verify and checked against the actual documents before use. Negative results keep their evidence too: a failed model conversion is recorded with tool version, command, failing node, and full log — never just "unsupported".

Every high-impact conclusion follows one format. An illustrative example:

Conclusion: model X (640×640, INT8) cannot run fully on the NPU — SiLU nodes fall back to CPU. [Engineering inference] Evidence: the toolchain's operator-support table does not list SiLU; inspect_model.py counts 57 SiLU nodes (log saved). If wrong: the end-to-end latency budget collapses; affects SoC selection. Next verification: run the vendor converter on the real model and read the partition report. [To verify]

2. Cross-layer reasoning

flowchart LR
    P["Product context"] <--> M["Model & ops"] <--> R["Runtime"] <--> T["Toolchain"] <--> S["System SW / BSP"] <--> H["Hardware"] <--> D["Deployment"]

"The weights fit in RAM" never implies "it runs in real time" — activations, runtime overhead, memory bandwidth, operator support, and data movement are checked layer by layer before any feasibility verdict.

3. Hard gates on irreversible operations

Fuse/OTP/eFuse, secure boot keys, flash encryption, permanent write protection, anti-rollback: the skill lists steps, preconditions, and consequences — it never emits copy-paste-executable commands for these, and it refuses to output any device-write flow until a recovery path is confirmed. Flashing defaults to dry-run with read-back verification. These gates held under direct user pressure and injected fake specs during evaluation.

Persistent project memory

Each engagement maintains an EMBEDDED_CONTEXT.md in your project root: platform facts, stack versions, verified procedures, open questions — every entry dated and evidence-tiered. A new session (or a new teammate) picks up where the last one left off instead of re-reading two gigabytes of PDFs.

"Isn't this just pasting docs into an LLM?"

Half true — the LLM is the engine. The skill adds what raw pasting cannot:

1. The paste doesn't physically fit. Real vendor drops are gigabytes; every context window forces selective reading. The skill makes the selection systematic (list archives before extracting, index before reading, route by task) instead of lucky — verdicts like "you're missing X" get checked against archive contents, not just file names.
2. Memory across sessions. Raw chat resets to zero; the context file compounds.
3. Honesty discipline. Raw LLMs blend documentation, memory, and plausible guesses into fluent prose. The tier system keeps them separated.
4. Safety gates. A raw LLM will paste an eFuse command from a forum. This one won't, by construction.

How it was validated

Summary — full protocol and numbers in docs/evaluation.md:

• Built and exercised end-to-end against a fixed multi-gigabyte private document corpus from a commercial edge-AI NPU platform, alongside a production-grade image-recognition application.
• Cold-start examination: 15 fresh-context sessions on Claude Sonnet with nothing but this skill and the corpus — 2/2 trigger accuracy, no fabricated claims found by graders, no safety-gate breaches (including under direct pressure and fake-spec injection), ≈93% average on 8 held-out field-debugging cases graded against pre-registered answer keys.
• Cross-agent: the same protocol passed on OpenAI Codex (gates held; evidence-tiered citations down to SDK source lines). Gemini CLI: untested.
• Known floor: on very small models (Haiku-class), safety gates still held in probes, but evidence discipline degraded. Recommended: Sonnet-class or better.

What it can and cannot save you from

Pits come in two kinds. Information-integration pits — the answer exists on page 300 of a PDF, in an operator support table, or in a forum thread; the skill is built to catch these on day one. Reality-only pits — a camera mounted at the wrong angle, a data-distribution mismatch, a hardware quirk no document mentions; no tool can foresee these. The skill's job there is to put a cheap, observable experiment in front of each one, and to make sure no pit is stepped in twice within the same project.

Repository layout

embedded-systems-architect/
├── SKILL.md                 # the skill: triggering, routing, evidence rules, hard gates
├── references/              # 10 on-demand playbooks (discovery, deployment, flashing…)
├── scripts/                 # 5 stdlib-first Python tools (model/SDK/repo inspection…)
├── assets/project-output-templates/   # context / experiment card / feasibility / recovery templates
├── docs/                    # evaluation notes and README artwork
├── AGENTS.md                # entry adapter for OpenAI Codex–style agents
├── GEMINI.md                # entry adapter for Gemini CLI
├── CONTRIBUTING.md          # authoring conventions (terminology, script spec, gate wording)
└── LICENSE                  # MIT

Language note: the skill's instruction files — and the --help output of the scripts — are written in Traditional Chinese (the skill's primary validation environment). Agents read them natively and respond in your language.

Contributing

Bug reports and field results from other boards/ecosystems are the most valuable contribution — open an issue with your platform, what the skill got right, and where it fell short. Content contributions must follow CONTRIBUTING.md.

License

MIT