Using Circuitpal with an AI agent
Give an AI assistant a skill file and it can build, run and analyse circuits in Circuitpal for you, the same way you would with the mouse.
An agent skill is a short instruction file that tells an AI assistant how to use a tool. The Circuitpal skill teaches an agent to drive the simulator through the same scripting interface described on the scripting page: it builds a circuit, runs it, reads the numbers, and explains what they mean. It does not add a chat box to the site; the agent works in your own browser, on your own page, and nothing is sent anywhere unless you ask it to share something.
Get the skill#
- SKILL.md: the skill itself (when to use it, the loop that works, the rules).
- references/api.md: every method, with examples.
- llms.txt: a plain index of these files for tools that look for one.
Save the two files in a folder called circuitpal (with references/api.md inside it) and add that folder to your assistant's skills. For Claude Code that is .claude/skills/circuitpal/ in your project or in your home folder; other assistants have their own place for custom instructions, and you can also just paste SKILL.md into the conversation.
What the agent needs#
A browser tool that can open a page and run JavaScript in it, such as a browser extension, Playwright or the browser built into your assistant app. The agent opens circuitpal.com, waits for window.Circuitpal and calls it.
What it can do#
Everything a person can do, as code, and it can read the results back:
| Area | What the agent can do |
|---|---|
| Build | Add any of the ${D.parts.length} parts, wire them on the 2D sheet or place them on the 3D breadboard, change values, move, rotate, lock, group, undo. |
| Run and read | Start and stop the circuit, then read the voltage, current and power of every part, brightness and state, warnings and burnt-out parts, and what the details panel says. |
| Measure | Oscilloscope traces with min, max, frequency and samples; frequency response (Bode), parameter sweeps and Monte Carlo runs; SPICE export and import. |
| Settings | Beginner or Advanced mode, theme, graphics quality, ambient temperature, tolerances and noise, simulation speed and accuracy. |
| Learn | List and start the lessons and challenges, and read the current step. |
| Community | Search and open shared circuits, read comments, like, comment and share (when you are signed in). |
Things to ask it#
- "Design a voltage divider that gives 3.3 V from 9 V, build it in Circuitpal, and check the readings."
- "Is a 220 Ω resistor safe for a red LED on 5 V? Show me the current."
- "Build an RC low-pass with a corner near 1 kHz and plot its frequency response."
- "Work through the first LED lesson and tell me what each step teaches."
Safety, privacy and moderation#
- Moderation: anything an agent (or you) shares or comments on the Community page waits for a moderator and is invisible to others until approved.
- Your session only: the agent uses your open page. It cannot sign in for you, and the skill tells it never to type passwords.
- Same accuracy limits as the simulator: results are approximate. Do not treat an agent's answer as a safety certificate. See How accurate is it?