Agent skills
A library of 45 skills for an AI agent that works with Ferret: building a game, porting a level from Unreal, editing levels by commands, and every physics capability. Each skill is a folder with a SKILL.md that says when to use it, the steps, what to check afterwards and what usually goes wrong, and reference files that are opened only when needed: the guides, the API of the packages involved and their debug commands, generated from the same sources as this site.
Download ferret-skills.zip (803 KB, 45 skills)
Install#
- Claude Code: unzip into
~/.claude/skills/(every project) or.claude/skills/(one project). Each skill appears by its name and description. - Caroline and other agents that read skill folders: point the skill source at the unzipped
ferret-skillsfolder. - Start from the skill
ferret: it maps a task to the skill that covers it. - The folders are also in the Ferret repository under
skills/;pnpm skillsrebuilds them.
The library is version 0.1.0, built from this documentation and the sources of the packages. index.json lists every skill and its files.
The skills#
| Skill | Use it for |
|---|---|
| ferret | Start here for any work with the Ferret game engine (TypeScript over Babylon.js, runs on OS Beroun and in browsers). Maps a task to the skill that covers it: game setup, levels, characters, AI, UI, net, editing by commands, Unreal porting, and the physics capabilities. |
| ferret-ai-navigation | Use for NPC movement and behaviour in Ferret: NavService (NavMesh build or load, path and point queries), NavAgent in the crowd, Roam, Follow, Attention, BehaviorTree. Read when NPCs do not path, get stuck, or must stop and face the player. |
| ferret-animation | Use for animation in Ferret: Animator and animation graphs (states, blend spaces, layers, transitions), montages, notifies, locomotionGraph, retargetGroup between skeletons, and buildPuppet to run a game before real models exist. Deterministic with the fixed step. |
| ferret-character | Use for the Ferret player and character movement: spawnCharacter, CharacterMovement (capsule, walk, run, crouch, jump, steps, slopes), PlayerController with named actions, CameraRig first/third person. Parameters follow Unreal's Character Movement Component. |
| ferret-combat | Use to make two armed characters fight in Ferret, by the player or by the AI on the same rules: Fighter, MoveSet, Duel, weapon sweeps against hit capsules (BoneGeometry, ClipPoseGeometry), blocks, parries, stamina, health, reactions, death, FighterAI levels and FighterBody in the scene. |
| ferret-debugging | Use to look inside a running Ferret game and to test it: world.commands (list, execute), the inspector (entity tree, component values, stats), scene and camera commands, asset and package commands, headless worlds in unit tests and the Playwright runs. |
| ferret-flow | Use for moving air and water in Ferret levels: wind, fronts, tornadoes, jets, lee shelters, rivers (channel), baked fields, and flow boxes that solve the flow round bodies (wakes, drag, lift); one field everything reads. |
| ferret-getting-started | Use to set up the Ferret repository, build and run the samples, and write a first game with createGame, a character and a level. Covers the pnpm commands, what a build produces, and where each sample (greybox, npc, showcase, physics) is useful. |
| ferret-input-ui | Use to bind input and build the HUD in a Ferret game: actions and bindings per device kind (console, keyboard, gamepad, touch), touch controls, prompts, toasts, loading screen and the cursor/A/B menu with UIService and MenuModel. |
| ferret-interaction-zones | Use for usable things and named areas in a Ferret level: Interactor and Interactable, Door, LevelDoor, Lever, Pickup, Inventory, installInteraction; and ZoneService with enter/exit events and zoneHash. Read when a prompt does not show or a zone does not fire. |
| ferret-level-editor | Use when an agent builds or changes a Ferret level by commands: edit.open, edit.entity., edit.spawn., edit.zone., edit.anim., edit.physics.*, edit.patch (JSON pointer), undo/redo, edit.validate, edit.diff and edit.save, with the model viewer for screenshots. |
| ferret-levels | Use to describe, load, validate or travel between Ferret levels: the manifest.json (scene, spawns, entities, zones, colliders, environment, physics), LevelService, level doors, streaming and environment. Not for building the level contents by commands; see ferret-level-editor. |
| ferret-media | Use for sound, video, recording and web pages in a Ferret world: AudioService with four buses, AudioPlayer, AmbientZones, VideoScreen (HLS or MP4 on a plane), HtmlScreen (a page as a texture), MediaPlayer, recording, frame-exact capture to WebM/PNG (captureFrames) and cutaways (SectionView). |
| ferret-motion | Use for writing or running programs in Ferret's motion language: timed sequences, parallel and racing motions, state machines, events, defmotion/defn, with a step budget, seeded random and snapshots; text and JSON forms. |
| ferret-net-accounts | Use for multiplayer and backends in Ferret: NetService with transports (memory, HTTP poll, LiveKit), Replicated fields, remote avatars, Gateways to a game's own backend with safe fallbacks, voice rooms by zone, and AccountService with sign-in. |
| ferret-packages | Use for Ferret asset loading and the .ferret package format: packing, signing and encrypting packages, catalogs, the persistent cache and its quota, security checks and code policy, streaming levels from a catalog. Read before publishing or loading downloaded content. |
| ferret-physics-actuators | Use for pushing and turning things on a schedule in Ferret: forces, impulses, torques and motors at chosen points of bodies and vessels; shafts that always turn or can jam; oars, winches, levers, conveyors; and wiring them to input, interactables, zones, events, AI and animations. |
| ferret-physics-bodies | Use for Ferret rigid bodies and materials: choosing the light or Havok kernel, shapes and body kinds, joints and constraints, contact events, layers, triggers, raycasts, PhysicalMaterial tables and combine rules, and the physics block of a level manifest. |
| ferret-physics-chemistry-nuclear | Use for reactions and radiation in Ferret: well-stirred vessels with rate laws, equilibrium, heat of reaction, pressure and runaway; radioactive decay, dose through shielding, Geiger counters, reactors with rods and scram, critical assemblies, activation and fallout. |
| ferret-physics-combustion-explosions | Use for burning and blasting in Ferret: combustion chambers, guns, rockets, piston engines, jets and boilers; blast waves by scaled distance, shielding, craters, casings that throw fragments, armour, and vessels that burst. detonate, fireGun, nozzle, blastAt, craterRadius. |
| ferret-physics-electric | Use for circuits in Ferret: Circuit with sources, wires, resistors, lamps, heaters, motors, generators, inductors, capacitors, diodes, transformers, relays, fuses and breakers; mains and three-phase; faults and tying a motor to a shaft. |
| ferret-physics-engines | Use for steam engines (a boiler, a double-acting cylinder with valve gear, a locomotive's two cylinders, reverser, cut-off, governor) and multi-cylinder piston engines (firing order, ignition advance, fuel cut, starter, idle) in Ferret, and for the shaking of an engine on its mounts. |
| ferret-physics-friction-impact | Use to dial friction and collisions per scope in Ferret: ice and sticky zones, grip per body, rolling and pivot resistance, anisotropic skates and skis; restitution scale, rest threshold, bounce falloff, sticking bodies and the physics:impact event. |
| ferret-physics-fx-tuning | Use to draw physics results and keep them affordable in Ferret: glow of hot parts, water meshes, particle liquids, lamp lights (physics-fx); tiers, the Governor that gives up detail, sub-steps and step rates, and what to switch off first when the frame is over budget. |
| ferret-physics-gravity-media | Use for gravity and fluids acting on bodies in Ferret: uniform and zone gravity, planets and attractors, per-body scale, weightlessness; and media with drag and buoyancy (water, mud, wind, air by altitude), gas volumes, currents, gusts, wading. |
| ferret-physics-heat | Use for temperature in Ferret: HeatNetwork parts with conduction, convection and radiation, phase change with latent heat, thermal expansion and stress, friction heat, and steel that loses strength when hot. Boiling pots, beams in a fire, hot walls, cooling. |
| ferret-physics-host | Use to switch realistic physics on in a Ferret game: PhysicsHost, registering and enabling capabilities, the order of the step, scoped values (world, level, zone, entity), physics.* commands, and writing a capability of your own. |
| ferret-physics-links | Use to close loops between Ferret physics capabilities with links: fire heats a pot, steam turns a turbine, a generator lights a lamp, a brake heats its drum, with an energy account that must add up. Covers gasInPart, slipHeats, wireFire, arcFlash and your own links. |
| ferret-physics-liquids | Use for liquids in Ferret: tanks and pipes, height-field water (waves, boats), particle liquids (splashes), foil lift and Magnus force, capillarity and wicks, and hydraulics (jacks, rams, valves, accumulators). |
| ferret-physics-mechanisms | Use for rotating machinery in Ferret: Drivetrain of shafts, gears, belts, clutches, brakes, differentials, worm gears, cardan joints, turbines and propellers, flywheels, tooth strength and breaking, and binding a shaft to a body. |
| ferret-physics-pneumatics | Use for compressed air and gas networks in Ferret: tanks, pipes, valves, regulators, compressors, air cylinders and springs, air guns, gas mixtures (Dalton) and dissolved gas (Henry), with heating on fast filling. |
| ferret-physics-recipes | Use to turn a physics wish into Ferret capabilities and a worked recipe: "make the bridge break", "boil a pot", "flood a cellar", "a tank that explodes in a fire". Maps wishes to the capability skills and carries the whole cookbook and the scenarios. |
| ferret-physics-rotors | Use for wind turbines and windmill sails, propellers, water wheels (undershot with paddles, overshot with buckets) and oars in Ferret: blades, paddles and buckets that turn wind or water into torque on a body or a drivetrain shaft, and the blade actuator. |
| ferret-physics-strength | Use to make things break in Ferret: bodies that take impact damage and split into pieces, joints that snap at the force their material holds, pre-fractured walls, the piece budget and replication of breaks by seed. Values toughness, threshold, pieces, burst. |
| ferret-physics-stretch | Use for things that give way in Ferret: springs, ropes that sag and snap, bungees with yield and break strain, cloth and flags by position-based dynamics with colliders and wind, and soft jelly bodies. Includes budgets and what to do when cloth does not move. |
| ferret-physics-terrain | Use for ground that changes in Ferret: a layered soil height field you can dig, fill, compact and dump; slopes that slump to their angle of repose, pits that flood, soft ground that swallows heavy bodies, tunnels that hold or cave in, Unreal landscape import. |
| ferret-physics-testing | Use to test Ferret physics: a headless world, driving the fixed step by hand, asserting against the laws the capabilities implement (not numbers seen once), golden traces, what determinism promises, and Playwright screenshots for what only eyes can judge. |
| ferret-physics-vehicles | Use to build boats, submarines, balloons and similar in Ferret: a Vessel is one body with a hull that displaces water, ballast tanks, flooding compartments, gas envelopes, thrusters, rudders, foils and sails; stability (GM), breaches and doors. |
| ferret-platform-display | Use for how a Ferret game talks to OS Beroun or the browser: FerretPlatform (saved state, suspend, exit, screen, log), device class, Display, field of view, render scale and quality tiers. Read before saving state or laying out for phone, console and desktop. |
| ferret-transform | Use to swap what an entity looks like and how it animates in Ferret (mesh, skeleton, graph, movement values) while keeping position and AI state: Transformer, ZoneTransform and effects such as particleBurst, scalePulse and combine. |
| ferret-unreal-characters | Use to bring Unreal characters, NPCs and animals into Ferret: inventory, export one mesh per editor run with its clips, clips to one skeleton, assembling parts on one skin, hair, morph targets, size per tier, Animation Blueprints to graphs, and the character viewer check. |
| ferret-unreal-level-look | Use when a level ported from Unreal loads but looks wrong in Ferret (black or dark surfaces, smeared or wrong-coloured materials, black metal, flat light) and to check it against the original from the same cameras. Find the cause first; symptom-to-cause table inside. |
| ferret-unreal-porting | Use to port an Unreal Engine 5 level or game to Ferret with tools/ue-export: what maps, the order of the work (census, spike, export, postprocess, Blueprints, viewer, parity), how to run the Unreal side so the output is complete, and the traps of real ports. |
| ferret-world | Use when writing Ferret game logic: the World, the fixed step, entities, components with onFixedUpdate/onUpdate, services, the event bus, the component registry and logging. Also for slow motion, pausing and deterministic tests. |
| ferret-xr | Use to make a Ferret game playable in a VR headset (WebXR, Meta Quest): turning it on, the Enter VR button, controller and hand bindings, comfort settings, menus in the world, grabbing, VR budgets and testing without a headset. |