Guide · Agent skill
How to use the SimPy discrete-event simulation agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The simpy skill gives an AI coding agent the working knowledge and bundled tools to build, test and analyze discrete-event simulations with the SimPy Python library. It is for people modelling queues, service lines, logistics or production systems over time. After reading this guide you will know how to install the skill, ask for simulation work in plain language, and what the agent will check before reporting results.
SimPy Discrete-Event SimulationK-Dense-AI/scientific-agent-skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the skills/simpy ZIP from our page.
- 2Install the skill. Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.
- 3Prepare Python and SimPy. Create a virtual environment with uv using Python 3.10 or newer, activate it, and install simpy 4.1.2 with uv pip.
- 4Confirm the SimPy version. Run the version check command and make sure it reports 4.1.2.
- 5Describe your system. Ask the agent for a SimPy model, giving entities, resources, time units and the question you want answered.
- 6Set bounds and replications. Ask for a time horizon, entity and event caps, and several independent replications with recorded seeds.
- 7Review the report. Check the stated limitations, unfinished entities and validation evidence before using the numbers.
What the simpy skill makes the agent do
An agent skill is a folder of instructions and helper files that an agent loads when a task matches it. With this skill installed, the agent designs and builds process-based discrete-event simulations: models where entities such as customers or parts move through a system, wait for shared resources, and trigger events over simulated time.
The skill steers the agent toward safe, checkable models. It asks for the decision or question the model supports, requires explicit caps on time, entities, events and replications so runs cannot loop forever, uses separate random seeds for distinct sources of randomness, and reports limitations. It also includes a basic simulation template and small command-line tools for bounded queue scenarios and for summarizing trace and monitor files.
Install the simpy skill from the ZIP or the Claude apps
Download the ZIP for skills/simpy from our page. Then choose one of these options. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP there.
After installing, start a new session so the agent can pick up the skill. The skill folder should contain SKILL.md at its top level alongside the references and scripts folders.
- Personal: ~/.claude/skills/
- Project: .claude/skills/ inside your project
- Claude apps: Settings, Capabilities, Skills, then upload
Set up the Python environment the tools need
The bundled command-line tools need Python 3.10 or newer, uv for environment setup, and SimPy 4.1.2. SimPy has no runtime dependencies beyond the standard library. The skill's own setup steps create a reproducible environment and confirm the installed SimPy version.
The bundled scripts build their --help output even when SimPy is absent, so you can read their options before installing anything.
uv venv --python 3.13
source .venv/bin/activate
uv pip install "simpy==4.1.2"
python -c "import importlib.metadata; print(importlib.metadata.version('simpy'))"Trigger the skill with natural requests
You do not need a special command. Describe the system and what you want to learn, and mention simulation, queues or SimPy. The skill's description covers event scheduling, resource queues, interrupts, monitoring, independent replications, warm-up and reproducible output analysis, so requests using those terms are most likely to load it.
Good requests state the question, the entities, the resources and the time units. Say what you want measured, such as waiting time or throughput, and how long the run should be.
- Build a SimPy model of a clinic with 3 nurses and Poisson arrivals; report average wait over 480 minutes.
- Run 20 independent replications of my checkout queue with reproducible seeds and give me a confidence interval for mean wait.
- Summarize this SimPy event trace file and check that every customer who arrived was served or is listed as unfinished.
- Add a warm-up period to my production line simulation and explain how you chose it.
Example: a bounded queue model
The skill's minimal model shows the pattern the agent follows. Arrivals are generated by a process with an entity cap. Each customer requests a shared server, waits in a FIFO queue if the server is busy, and is served for a random time. Separate random generators are used for arrivals and service.
The run stops at a fixed horizon. The skill notes that the numeric horizon excludes events scheduled exactly at that time, and that unfinished customers should be reported rather than dropped from the results.
import random
import simpy
HORIZON = 480.0
arrival_rng = random.Random(101)
service_rng = random.Random(202)
env = simpy.Environment()
server = simpy.Resource(env, capacity=2)
completed = []
def customer(arrival):
with server.request() as request:
yield request
wait = env.now - arrival
yield env.timeout(service_rng.expovariate(1 / 6.0))
completed.append((env.now, wait))
def arrivals():
for _ in range(10_000): # Entity cap.
delay = arrival_rng.expovariate(1 / 4.0)
if env.now + delay >= HORIZON:
return
yield env.timeout(delay)
env.process(customer(env.now))
env.process(arrivals())
env.run(until=HORIZON)Safety notes: scripts, local files and network
The skill runs scripts, so read what it asks to execute. The bundled tools use only SimPy and the Python standard library. They make no network or external-service calls and work on local files only. They accept only local regular files with fixed suffixes and reject URLs, symlinks, duplicate JSON keys, NaN or infinity values, unknown keys and oversized inputs.
The tools never evaluate configuration text, run user Python code, or import plugins. They enforce caps on time, events, entities, queues, traces and replications. Explicit outputs are written atomically with restricted permissions, and existing files are not overwritten unless you pass --force.
- Runs scripts: yes
- Uses network: no
- Files: scripts/_common.py, basic_simulation_template.py, bounded_queue_scenario.py, event_trace_summary.py, replication_runner.py, resource_monitor.py
Tips for reliable simulation results
Treat the simulation as a model, not a fact. SimPy schedules events but does not validate your assumptions, input distributions, warm-up or run length. The skill directs the agent to check results against real system data or expert knowledge for the purpose you stated.
Keep bounds generous enough for your question but explicit. If a study needs more time, events, entities or replications than the bundled tools allow, the skill's guidance says to change those limits deliberately rather than remove them.
- State the decision, time units and terminating condition before modelling.
- Use independent replications for confidence intervals, not many entities within one run.
- Ask the agent to list assumptions, unfinished entities, seeds and sensitivity checks in the report.
- Never read a simulation association as a causal finding without further evidence.
What people use it for
- Estimating customer waiting time and server utilization for a clinic or service desk with a fixed number of staff.
- Comparing staffing levels or server counts in a queue by running replications for each scenario.
- Modelling a production or logistics line with shared resources and checking throughput over a set time window.
- Teaching event-driven simulation, with a bounded example and a trace file to inspect step by step.
- Summarizing an existing SimPy trace or monitor file to check that entities are accounted for.
Frequently asked questions
How do I install the simpy agent skill?
Download the ZIP for skills/simpy from the page, then unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings, Capabilities, Skills.
Is the simpy skill free to use?
The skill and SimPy are both MIT-licensed, according to the skill's metadata and its description of SimPy. The skill has no paid tier described in the source.
What do I need to run the simpy skill?
You need Python 3.10 or newer, uv for setting up the environment, and SimPy 4.1.2. SimPy has no runtime dependencies beyond the standard library. The bundled tools will not run without these.
Does the simpy skill need internet access?
No. The bundled scripts make no network or external-service calls and operate only on local files. They do run Python scripts, so review what the agent executes.
Why won't my SimPy simulation stop?
A time horizon alone cannot stop a process that yields zero-delay events forever, because the simulation clock never advances. The skill says to add an event-count or no-time-progress guard and to wait on state-change events instead of busy polling. Also avoid calling env.run() on models with endless processes without a stop condition.
Can SimPy tell me whether my simulation results are correct?
No. SimPy schedules events but does not validate your model, inputs or assumptions. The skill directs you to compare results against real system data or expert evidence for the stated purpose.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use the simpy skill if you model queues, staffing, throughput or logistics in Python and want an agent to build bounded, reproducible simulations with documented limitations. Pick something else if you need non-Python tooling, very large or unbounded models beyond the bundled caps, or conclusions about cause and effect drawn from simulation output alone.
Download the skill