{
  "markdown": "# Embedded / IoT Mentor — a Claude Skill\n\n**English** · [Svenska](./README.sv.md) · [فارسی](./README.fa.md)\n\n[![check-skill](https://github.com/mh-mansouri/embedded-iot-mentor/actions/workflows/check-skill.yml/badge.svg)](https://github.com/mh-mansouri/embedded-iot-mentor/actions/workflows/check-skill.yml)\n[![check-links](https://github.com/mh-mansouri/embedded-iot-mentor/actions/workflows/check-links.yml/badge.svg)](https://github.com/mh-mansouri/embedded-iot-mentor/actions/workflows/check-links.yml)\n[![latest release](https://img.shields.io/github/v/release/mh-mansouri/embedded-iot-mentor?label=release)](https://github.com/mh-mansouri/embedded-iot-mentor/releases/latest)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\nA skill for [Claude](https://claude.ai) that acts as an experienced embedded-systems mentor:\nit picks the microcontroller, board, and toolchain for your project, estimates what it will\ncost and how long it will take, and hands you a build plan that stops at a **working\nbreadboard** instead of a production line you didn't ask for.\n\nMost embedded advice fails in one of two directions — a parts list with no plan, or a\nproduction roadmap for someone who hasn't blinked an LED yet. This skill asks what you've\nactually built before, then answers at that level.\n\n## Try it\n\n| Where | One click |\n|---|---|\n| **Claude** | [Download `embedded-iot-mentor.skill`](https://github.com/mh-mansouri/embedded-iot-mentor/releases/latest/download/embedded-iot-mentor.skill) and open it |\n| **VS Code (Copilot Chat)** | Copy [`vscode-copilot/`](./vscode-copilot/)'s prompt in — nothing to install |\n| **Your own code** | [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/mh-mansouri/embedded-iot-mentor) then call the REST API — [routes](./api/) |\n| **Any other AI chat** | Copy [`universal-prompt.md`](./universal-prompt.md) into the first message — no install, works in ChatGPT, Gemini, Copilot, and others |\n\nPrefer a page over a chat? [`docs/index.html`](./docs/index.html) is a static overview with the\nsame \"Try it\" links and demo — live at\n[mh-mansouri.github.io/embedded-iot-mentor](https://mh-mansouri.github.io/embedded-iot-mentor/),\nor open the file locally, no server needed.\n\nEverything below is the longer way round: build it yourself, change it, or read why it\nanswers the way it does.\n\n## Demo\n\n![A farmer asks for soil moisture and nitrogen across a meadow; the skill declines the nitrogen half, asks two questions, and returns a six-node LoRa plan with no code in it](./embedded-iot-mentor-demo.gif)\n\nA sheep farmer in Devon, with no coding experience, requests six sensing points, and the furthest sensing point is around 400 m away from the house. All of those are below the minimum cost for such a project.\nWorth watching for what the skill *doesn't* suggest: It opens by refusing half the request - no cheap probe measures soil nitrogen honestly - then lets three constraints do the choosing. The 400 meters away from home picks radio over Wi-Fi, \"I don't write code\" picks ready-made firmware over a toolchain, and a wet meadow picks the enclosure. The board is the last thing decided, not the first. The full transcript is\n[Scenario D](./embedded-iot-mentor/examples/worked-examples.md#scenario-d--when-half-the-brief-cannot-be-built).\n\n## What it does\n\n- **Picks a platform** — ESP32, Pico, STM32, nRF52 — and says plainly why that one, plus one\n  or two alternatives and when each would win instead.\n- **Separates the hardware path from the firmware path**, so you know what to buy and what to\n  install without conflating them.\n- **Checks whether you need to write firmware at all.** If ESPHome, Meshtastic or Tasmota\n  already does the job, that's the answer — writing code is a cost, not a deliverable.\n- **Takes the reading all the way to a person** — Home Assistant, a page the device serves\n  itself, a hosted dashboard, or just an alert. \"On my phone\" in the kitchen and \"on my\n  phone\" from work are two different builds, and it says so before you pick one.\n- **Estimates time and cost** as ranges, and flags what actually drives them — including\n  what the thing costs to *run*, once it's six nodes eating batteries in a field.\n- **Says what a sensor really measures.** Cheap \"NPK\" probes read conductivity and guess;\n  you get told that before you buy six of them, not after.\n- **Plans to MVP and stops there.** Engineering prototype, pre-production, and production\n  phases exist, but you only get them when you ask.\n- **Names the risks** — power budget, part availability, no debug path, certification, the\n  learning curve on whatever it just recommended.\n- **Rejects its own suggestions** against a fixed bar: no maintained library, single-supplier\n  part, a package you can't solder, no serial console — it drops the candidate and picks again.\n\n## Why it exists\n\nThe failure modes it's built to catch:\n\n- **A beginner pointed at an STM32 with an ST-Link** because a forum said it was \"more\n  professional\" — three evenings lost to toolchain setup before the first LED.\n- **A battery project designed around a dev board** whose regulator idles at 20 mA, so the\n  \"two month\" runtime is really four days. The board was never the problem; nobody costed the\n  sleep current.\n- **A first PCB ordered with 0402 passives and a QFN**, hand-assembled with a soldering iron,\n  and dead on arrival with no test points to find out why.\n- **Six sensors deployed in a field in indoor boxes**, sealed with tape instead of cable\n  glands, condensing on their own PCBs by the second week.\n\n## Install\n\n**Option A — one file.** Download `embedded-iot-mentor.skill` from the\n[latest release](https://github.com/mh-mansouri/embedded-iot-mentor/releases/latest) (or\n[straight from the repository](./embedded-iot-mentor.skill)), then in [claude.ai](https://claude.ai):\n\n1. Click your name in the bottom-left corner, choose **Settings**, then open the **Skills** page under Customize:\n\n   ![Settings menu with Skills highlighted under Customize](assets/install-steps/1-settings-skills.png)\n\n2. Click **Add**, then **Upload a skill**:\n\n   ![Add skill menu showing Create with Claude, Write skill instructions, and Upload a skill](assets/install-steps/2-add-skill-menu.png)\n\n3. Drag the downloaded `embedded-iot-mentor.skill` file onto the upload box (or click it to browse):\n\n   ![Upload skill dialog with a drag-and-drop area](assets/install-steps/3-upload-dialog.png)\n\n(Skill saving must be enabled for your account or organization.)\n\n**Option B — Claude Code.** Unpack it into your skills directory:\n\n```bash\npython package_skill.py --install                                     # for your user\npython package_skill.py --install --skills-dir <repo>/.claude/skills  # for one project\n```\n\nOr install a bundle you already have, with no copy of this repo:\n\n```bash\npython package_skill.py --install-from embedded-iot-mentor.skill\n```\n\nOr by hand — a `.skill` is just a zip:\n\n```bash\nmkdir -p ~/.claude/skills && unzip embedded-iot-mentor.skill -d ~/.claude/skills/\n```\n\n```powershell\n# Windows: Expand-Archive refuses any extension but .zip, so rename a copy first\nNew-Item -ItemType Directory -Force \"$HOME\\.claude\\skills\" | Out-Null\nCopy-Item embedded-iot-mentor.skill \"$env:TEMP\\embedded-iot-mentor.zip\"\nExpand-Archive \"$env:TEMP\\embedded-iot-mentor.zip\" -DestinationPath \"$HOME\\.claude\\skills\" -Force\n```\n\nClaude Code picks it up on the next session — `/skills` lists it, and Claude also loads it on\nits own when a conversation matches the description.\n\n## Use it\n\nJust describe the project. For example:\n\n> I want to log soil moisture in a greenhouse and see it on my phone. I've done a couple of\n> Arduino sketches. Budget maybe €100, and I'd like it running in a month.\n\nor\n\n> Which board for a battery sensor that has to last a year on a coin cell? I've shipped\n> firmware before, so don't dumb it down.\n\nor\n\n> I have an ESP32 and a BME280 sitting in a drawer. What's worth building with them?\n\nor, the one in the demo above:\n\n> I am a farmer and want to measure soil moisture and nitrogen in different parts of my\n> meadow to make sure my sheep are well fed.\n\nIt will ask a couple of short questions if the goal, experience level, power source,\nenvironment, or timeline are still unclear — then answer in tables rather than essays. A\nwhole project plan is meant to fit on one screen; if you want the reasoning behind a pick,\nask for it.\n\n## Elsewhere: VS Code and the REST API\n\nThe mentor is judgement written down, not a Claude feature, so it ports. Every port keeps\nthe behaviour that matters — MVP first, hardware and firmware kept apart, ready-made\nfirmware ahead of code to be written, the reject bar, and the hand-off on safety-critical,\nvehicle, and privacy questions.\n\n| Route | What you do | Worth it when |\n|---|---|---|\n| [`vscode-copilot/`](./vscode-copilot/) | Copy one file to `.github/copilot-instructions.md`, or paste it into Copilot Chat | Always start here in VS Code — nothing to install |\n| [`api/`](./api/) | Deploy the REST API — [one click on Render](https://render.com/deploy?repo=https://github.com/mh-mansouri/embedded-iot-mentor) — and call it from your own code | The caller is a script or a service, not a person in a chat window |\n\nWhat the two carry differs. The Copilot port is judgement only — no reference files, no\nscripts, so a real battery runtime or a BOM total is still the skill's job. The REST API\nreads both straight out of the skill folder, so it can never fall behind a change made\nhere.\n\n## Good to know\n\n- **Prices and stock go stale.** Estimates are ranges, not quotes. Check LCSC, Digi-Key, or\n  your local supplier before ordering.\n- **It cannot verify part availability** in your country, and that is the most common reason\n  a good plan stalls.\n- **It stops at MVP by design.** Ask explicitly for the later phases.\n- **Not for safety-critical work.** It will help you to a prototype for medical, automotive,\n  or safety systems, then tell you plainly where hobbyist advice ends.\n\n## Layout\n\nThe skill itself lives in `embedded-iot-mentor/`. Everything at the repository root is\npackaging and project metadata that the skill never reads.\n\n| Path | What it is |\n|---|---|\n| `embedded-iot-mentor/SKILL.md` | The instructions Claude follows. Most changes go here. |\n| `embedded-iot-mentor/references/` | Detail read on a trigger: MCU selection, connectivity, where the data is seen, cost estimation, PCB checklist, power/battery, field deployment, OTA, EMC, safety boundary, learning resources. |\n| `embedded-iot-mentor/scripts/` | Small deterministic helpers, run only when a concrete number is asked for. |\n| `embedded-iot-mentor/examples/` | Worked scenarios showing the *shape* a reply should take when a request doesn't fit the standard mould. |\n| `embedded-iot-mentor.skill` | **Generated.** A zip of the folder above — don't edit by hand. |\n| `package_skill.py` | Builds, verifies, and installs the bundle. |\n| `embedded-iot-mentor-demo.gif` | The recording shown at the top. Not bundled — the packer only takes the skill folder. |\n| `universal-prompt.md` | The same mentor as a copy-paste prompt, for any AI chat that isn't Claude. |\n| `assets/install-steps/` | Screenshots for the Claude Skill upload walkthrough in Install, above. |\n| `docs/index.html` | Static landing page for GitHub Pages — the \"Try it\" links and the demo, no chat needed. |\n| `create_skill_demo_gif.py` | Generates a mock-up demo GIF (`assets/skill-demo-mockup.gif`) from a scripted scenario, for when a real recording isn't available. |\n| `scripts/check_links.py` | Checks that every README, landing-page, `CONTRIBUTING.md`, and distribution link still resolves. Run by `check-links.yml` on push, PR, and weekly. |\n| `vscode-copilot/` | The Copilot port — the paste-in prompt and example queries. |\n| `api/` | The REST API — reads the reference library from the skill folder and shells out to its scripts. |\n| `api/instructions.md` | The mentor's rules condensed to a self-contained prompt, for `POST /chat` and `GET /instructions`. Mirror a behaviour change here if you make one in `SKILL.md`. |\n| `render.yaml` | Blueprint behind the one-click deploy of the API. Has to sit at the root for Render to find it. |\n| `.github/DISTRIBUTION.md` | Where the project is listed and how to list it — the steps that need a login rather than a workflow. |\n\nKeeping the skill in its own folder matters: the spec requires a skill's `name` to match its\nfolder name, so building it straight from the repository root would break the moment someone\ndownloaded the repo as a ZIP and got `embedded-iot-mentor-main/`.\n\n## Build\n\n```bash\npython package_skill.py          # -> ./embedded-iot-mentor.skill\npython package_skill.py --check  # validate source + bundle, build nothing\n```\n\nA `.skill` file is a zip archive holding the skill folder — the format is defined by the\n[Agent Skills specification](https://agentskills.io/specification). The packer bundles\neverything under `embedded-iot-mentor/`, so a new reference file is picked up automatically\nwith no build-script edit. Text files are stored with LF and zip timestamps are pinned, so\nthe bundle is byte-identical whoever builds it.\n\n`--check` is the gate, and CI runs it on every push and pull request. It fails when:\n\n- the frontmatter breaks a spec constraint (`name` pattern/length, folder match, `description` length);\n- `SKILL.md` points at a `references/…` or `scripts/…` file that doesn't exist;\n- the committed `.skill` doesn't match the source folder.\n\nThat last one matters because the bundle is committed: edit the skill, forget to rebuild, and\nthe download would ship a different version than the source folder.\n\n## Scripts\n\n```bash\npython embedded-iot-mentor/scripts/cost_estimator.py 1 4.50 \"ESP32 DevKit\" 10 0.12 \"10k resistor\"\npython embedded-iot-mentor/scripts/footprint_hint.py 0603\npython embedded-iot-mentor/scripts/sleep_budget.py --capacity 2000 --active-ma 80 \\\n    --active-ms 250 --sleep-ua 15 --interval-s 600\n```\n\n`sleep_budget.py` takes duty-cycle inputs rather than an average current, because the\naverage is the number nobody knows up front. Same firmware, same battery, sleep current\nchanged from 15 µA to a dev board's 8 mA regulator: **3.8 years becomes 8.3 days.**\n\n## More skills like this\n\n- **[Project Planning & Journaling](https://github.com/mh-mansouri/Project-Planning-Journaling)** —\n  scopes a project before any code is written, then keeps a living, resumable\n  documentation journal with a weekly routine review.\n- **[Business Name Fit](https://github.com/Elham-Farajnejad/business-name-fit)** —\n  picks or checks a business/brand name that's authentic to your origin and lands well\n  in the markets you're selling into.\n\n## Contributing\n\nImprovements are welcome — especially hands-on knowledge about parts, suppliers, and what\nactually goes wrong on a bench. See [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## License\n\nReleased under the [MIT License](./LICENSE) — free to use, share, and build on.\n",
  "bytes": 15062,
  "sha": "bc666e01f94be398c6d1e925c7f8c1d55a84cb5c17ac28cc9288848828ce5ca1",
  "repo_slug": "mh-mansouri/embedded-iot-mentor",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mh_mansouri_embedded_iot_mento_3f1db212/readme"
}