Guide · Agent skill
How to use the Matter.js Physics Skill agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The matterjs agent skill is a set of instructions and example code that teaches an AI agent how to add 2D physics simulation to a web page using the Matter.js library. It is aimed at front-end developers and designers who want a working starting point for bodies, gravity, collisions and draggable elements. After reading this guide you will know what the skill does, how to install it, how to ask for it in plain language, and what to check before using the result.
Matter.js Physics SkillMengTo/Skills · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it so the matterjs folder is available to your agent.
- 2Place it in the skills folder. Put the folder in ~/.claude/skills/ for personal use or in your project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Confirm your environment. Tell the agent whether you use plain HTML, React or a canvas-only setup, and whether you want Matter.Render or a custom renderer.
- 4Ask for the physics scene. Describe the effect in plain words, for example bodies falling onto a floor, and mention Matter.js.
- 5Add interaction if you want it. Ask for mouse or touch dragging only if you need it, since the skill adds constraints only when requested.
- 6Test in a browser. Open the generated HTML file in a browser with JavaScript enabled and check the scene behaves as you expected.
- 7Add cleanup for SPAs. If the scene lives in a single-page app, ask for the stop, remove and clear steps so the runner does not keep running after the view closes.
What is an agent skill and what does matterjs do?
An agent skill is a folder of instructions that an AI agent can load when a task matches the skill's description. The matterjs skill is described as useful when implementing 2D physics interactions with Matter.js, including Engine/World setup, Render/Runner configuration, adding bodies and constraints, and scroll or interaction-friendly canvas scenes.
Once installed, the agent knows how to set up a physics engine, create bodies such as boxes and floors, render them on a canvas, and optionally add mouse or touch dragging. It also knows basic cleanup steps for single-page apps. The skill is instructions and example code only; it does not run anything by itself.
- Creates an Engine and World and adds bodies to the world
- Renders a scene with Matter.Render, or suggests a custom renderer
- Adds mouse dragging through a MouseConstraint when you ask for it
- Lists cleanup steps: stop the runner, remove the canvas, clear the engine and world
How do you install the matterjs skill?
Download the ZIP from the skill's page on this site and unzip it. For a personal setup, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder instead.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/ (available across your projects)
- Project install: .claude/skills/ inside the project folder (shared with that project)
- Claude apps: Settings → Capabilities → Skills, then upload the skill
What does the skill folder contain?
The package includes SKILL.md, which holds the workflow, code patterns and setup checklist the agent reads. It also includes demo/index.html, a standalone example page, and demo/PROMPT.md, which lists prompts used to build the demo.
You do not need to edit these files to use the skill. Reading demo/index.html is a useful way to see what a finished scene looks like.
- SKILL.md: workflow, minimal setup, mouse interaction, cleanup checklist
- demo/index.html: standalone example page
- demo/PROMPT.md: example prompts for the demo
How do you trigger the skill with a natural request?
Describe the physics effect you want in plain language and mention Matter.js or a 2D physics scene. The agent matches your request against the skill description. The demo prompts in the package use the form Use $matterjs to ..., which is a clear way to name the skill directly.
The skill asks some questions when specs are missing, such as the viewport size, whether to use Matter.Render or a custom renderer, whether you want drag interaction, and whether the loop should pause when offscreen. Answering these up front gives a better result.
- Use $matterjs to create a polished standalone HTML example that clearly demonstrates the skill.
- Use $matterjs to add a draggable box and floor to my landing page with Matter.js.
- Use $matterjs to set up a Matter.js canvas that pauses when it scrolls out of view.
What does a minimal Matter.js setup look like?
The skill's minimal example loads the Matter namespace, creates an engine, creates a render on document.body at 800 by 600 pixels with wireframes turned off, starts a runner, and adds a static ground and a dynamic box to the world. The agent adapts this pattern to your page.
Matter.js must be loaded in the page through a script tag or a package. The skill requires a browser with JavaScript enabled.
- Engine.create() makes the physics engine
- Render.create({ element, engine }) makes a canvas automatically
- Bodies.rectangle(...) creates boxes and floors; isStatic: true keeps the floor fixed
- Composite.add(engine.world, [...]) adds bodies to the world
<script>
const { Engine, Render, Runner, Bodies, Composite } = Matter;
const engine = Engine.create();
const render = Render.create({ element: document.body, engine: engine, options: { width: 800, height: 600, wireframes: false } });
const runner = Runner.create();
Runner.run(runner, engine);
Render.run(render);
const ground = Bodies.rectangle(400, 610, 810, 60, { isStatic: true });
const box = Bodies.rectangle(400, 200, 80, 80);
Composite.add(engine.world, [ground, box]);
</script>How do you add mouse or touch dragging?
Mouse dragging is optional and is added only when requested. The skill creates a Mouse from the render canvas, wraps it in a MouseConstraint attached to the engine, adds the constraint to the world, and assigns the mouse to the render.
- Use this only if you want drag interaction; the skill adds constraints only when requested
- Mouse is created from render.canvas
const { Mouse, MouseConstraint } = Matter;
const mouse = Mouse.create(render.canvas);
const mouseConstraint = MouseConstraint.create(engine, { mouse });
Composite.add(engine.world, mouseConstraint);
render.mouse = mouse;How do you clean up a Matter.js scene in a single-page app?
In a single-page app, a scene can keep running after you leave its view. The skill's checklist stops the runner, removes the render canvas from the DOM, and clears the engine and world if needed. Run these steps when the component unmounts or the page changes.
- Stop the runner with Runner.stop(runner)
- Remove the render canvas from the DOM
- Clear the engine and world if needed
Runner.stop(runner);What people use it for
- Adding a few falling, bouncing shapes with a floor to a landing page hero
- Building a draggable card or box demo for a product page
- Prototyping interactive motion for a design review with a working example
- Creating a canvas scene that stops its loop when it scrolls out of view
- Setting up and tearing down a Matter.js scene inside a single-page app component
Frequently asked questions
How do I install the matterjs agent skill?
Download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder. In the Claude apps, you can upload it under Settings → Capabilities → Skills.
Is the matterjs skill free to use?
The skill is published under the MIT licence, as listed on this page. Check the licence file in the package for the full terms.
What do I need to run it?
You need a web browser with JavaScript enabled and the Matter.js library loaded in the page, either through a script tag or a package. The skill itself runs no scripts and uses no network access.
Does the skill run code on my machine?
No. The skill is a set of instructions and example code. It does not run anything by itself. The code it helps the agent write runs in your browser when you open the page.
Is Matter.js good for 3D or scientific physics?
No. Matter.js is a 2D library and is not designed for scientific accuracy or production 3D physics. Use this skill for playful effects and interactive canvas scenes, and pick a different tool for precise simulation.
Will this skill work with libraries other than Matter.js?
Not well. The guidance is specific to the Matter.js API, so it is not useful for projects that do not use Matter.js.
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 matterjs skill if you are a front-end developer or designer who wants a correct, working starting point for 2D Matter.js physics on a web page, including setup, rendering, optional dragging and teardown. Pick a different tool if you need 3D, high-precision or scientific physics, or if your project does not use Matter.js.
Download the skill