scenario-maya-modeling — Claude Code skill for Maya modeling
The scenario-maya-modeling skill guides Maya modeling and topology cleanup for game props, SubD assets, and deforming characters. Use it when shaping a mesh or preparing it for UVs or rigging.
MIT 426 installs ★ 3,964 updated 2026-10-23
npx skills add scenario-labs/skills --skill scenario-maya-modeling -a claude-codeWhat scenario-maya-modeling does
The skill approaches a model from large forms to small details. It guides support-loop placement, triangle cleanup, and topology for deforming surfaces, with choices shaped by the asset’s purpose, mesh density, and camera distance. A metallic highlight render is one way it recommends checking the surface rather than trusting the wireframe alone.
The toolkit includes scripts/mx_modeling.py and the tools mx_audit, mx_validate, mx_review, and mx_run. It requires scenario-maya-expert as background for execution and review; without that dependency, the toolkit workflow has a gap. The Python layer passed offline tests, while Maya calls still need validation with tests/code/maya-modeling/run_all.sh.
What it helps with
- choose mesh density for an asset’s camera distance
- clean up pinching and uneven surface highlights
- prepare character topology for deformation
- check a mesh for non-manifold or zero-length geometry
- reduce a game mesh while preserving useful edge loops
Example prompts for the agent
- Model a game prop in Maya and explain which edges to keep for this triangle budget.
- Check this mesh before UV work and suggest fixes for its topology problems.
- Prepare this character mesh for deformation and place the supporting loops.
How to install scenario-maya-modeling
1Skills CLI (Vercel)
npx skills add scenario-labs/skills --skill scenario-maya-modeling -a claude-code2Manually: put the files in place
~/.claude/skills/scenario-maya-modeling/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/scenario-maya-modeling/
1Skills CLI (Vercel)
npx skills add scenario-labs/skills --skill scenario-maya-modeling -a codex2Manually: put the files in place
.agents/skills/scenario-maya-modeling/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add scenario-labs/skills --skill scenario-maya-modeling -a cursor2Manually: put the files in place
.cursor/skills/scenario-maya-modeling/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install scenario-labs/skills skills/dcc/maya/scenario-maya-modeling2Manually: put the files in place
.github/skills/scenario-maya-modeling/SKILL.md1Skills CLI (Vercel)
npx skills add scenario-labs/skills --skill scenario-maya-modeling -a gemini-cli2Platform CLI
gemini skills install https://github.com/scenario-labs/skills --path skills/dcc/maya/scenario-maya-modelingManually: put the files in place
.devin/skills/scenario-maya-modeling/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add scenario-labs/skills --skill scenario-maya-modeling -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about scenario-maya-modeling
How do I install scenario-maya-modeling in Claude Code?
Run npx skills add scenario-labs/skills --skill scenario-maya-modeling -a claude-code. The skill file is at ~/.claude/skills/scenario-maya-modeling/SKILL.md.
What does scenario-maya-modeling do?
It guides Maya mesh modeling and topology checks for game assets, SubD work, and deformation. Its advice accounts for the asset’s intended use, mesh density, and camera distance.
What does the skill need to work with its toolkit?
It requires scenario-maya-expert for the execution and review workflow. The included scripts/mx_modeling.py has an offline-tested Python layer; Maya calls need validation with tests/code/maya-modeling/run_all.sh.
Source text
SKILL.md · MIT
---
name: scenario-maya-modeling
description: 'Use when modeling in Autodesk Maya, such as hard-surface props, weapons, vehicles, a sci-fi crate, a game-ready or SubD film model, or a character or creature base mesh, or when asked to "clean up this model" or a scene before rigging or UVs. Also for support loops vs bevels vs creases, Smart Bevel, weighted normals, hard edges, pinching or wobbly highlights, a faceted cage, flipped faces, a triangle budget, n-gons, non-manifold geometry, mirroring a half, a low poly from a high poly, or deformation-ready topology.'
license: MIT
---
# Maya modeling (hard surface, organic, props)
Expert modeling is purposeful topology: every loop exists for the silhouette, a highlight, a bake, a
UV seam or a joint, and the model arrives downstream with nothing the next person has to clean. The
agent works big to small, measures each stage with the toolkit, and looks at a metal highlight
render before believing a surface. If a sibling skill named here is missing from your available
skills, load it with `skill_get` (Scenario MCP) or ask the user to install it
(https://github.com/scenario-labs/skills#install); unattended, proceed from tool schemas and flag
the gap.
**REQUIRED BACKGROUND:** scenario-maya-expert (execution channel, review loop, 2027 version traps).
Toolkit: [`scripts/mx_modeling.py`](scripts/mx_modeling.py)
(`sys.path[:0] = ["<skills>/scenario-maya-modeling/scripts", "<skills>/scenario-maya-expert/scripts"]; import mx_modeling as MM`),
used with `mx_audit`, `mx_validate`, `mx_review`, `mx_run`. **Not yet run in Maya:** its pure-Python
layer passed offline tests; every Maya call is pending `tests/code/maya-modeling/run_all.sh`.
## Stance (the expert delta)
- **Purpose first, then density.** A still from CAD or booleans can skip clean topology; games,
animation and close-ups cannot (Mario Elementza [00:00:32]). Minimum density is the narrowest
feature, "the shortest distance between the two edges" [00:17:19]; then camera distance decides:
low density needs redirected edges and pinches slightly (background), high density needs none
(hero close-up) [01:09:20] [01:39:46]. Vertex count is the real cost: UV seams, hard edges and
materials split vertices; a hard edge on a UV seam is free (Polycount).
- **Clean uncut form, then cut.** On flats, offset before cutting: the offset ring becomes the
support loop; on curved parts, cut the support loop before the detail (Mario [00:16:13] [00:38:16]
[01:19:49]).
- **Even grid, never double; loops are the proof.** Neighbor quads under 2:1 (Mario [00:08:31]); a
breaking loop is an unsolved area, a loop that stops dead is a hidden double extrude [00:18:57]
[00:39:22].
- **Triangles: remove, solve, reinstate; n-gons never.** On a cage, take triangles out, solve the
rest, put one back only where the metal test holds; flats forgive, curves and deforming areas do
not (Mario [00:20:36] [00:29:59]; Jessica Dru Johnson [01:12:33]). On a game low, triangles end
loops locally (On Mars [00:10:29]). Cleanup fixes only lamina, non-manifold and zero-length
geometry; n-gons by hand (FlippedNormals ToWRH4IXF7A [00:11:15] [00:11:50]).
- **Cylinders in quarters, quad caps, ring loops only** (Mario [00:57:43] [01:12:04] [01:14:16];
Pixar OpenSubdiv: no high-valence fans).
- **The destination picks the edge-holding method,** and subdivision lives in one place: Arnold
renders Smooth Mesh Preview's state on top of its own iterations, so every save goes out with
preview off (Arnold subdivision doc; FlippedNormals [00:24:00]). Creases are lost on export
(antCGi RlNnp4qQIrU [00:28:12]).
- **Deformation topology is the modeler's job.** One control plus two support loops per joint
(Jessica [01:15:51]), isolation loops bound controls [01:14:11], no pole on a deforming surface
(antCGi QW8w15J00Ok [00:09:58]); prove a fix by bending two topologies with identical settings
(antCGi x07USYlvu2o [00:16:24]).
- **Hygiene is a delivery contract.** Rebuild beats repair, unique short names, render stats at
defaults; two-sided lighting hides flipped faces (FlippedNormals [00:08:31] [00:18:16] [00:02:35]
[00:20:47]).
## Establish first
| Input | Changes | Default when silent |
| --------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Destination | edge-holding method, triangulation, normals | game (PC/console) if an engine is named, else offline SubD |
| Budget | how much to strip | ask the lead; meanwhile anchor on On Mars' bands (grenade-class prop): hero seen large on screen 20k to 30k tris, secondary or tertiary props at 10 to 15% of the screen "much less" (no number given), background 10k or 5k. Report tris and engine vertices, justify each kept edge |
| Camera distance | narrowest feature kept, density vs redirection, corner softness | mid-ground, player can walk up to it [assumption, written in the report] |
| Deformation | loops per joint, no weighted normals, symmetry | none for props; characters: yes |
| Size, units | bevel widths, texel math | real size in cm, grounded; the Maya scene stays Y up even for a Z-up engine (FBX export or import converts the axis) |
| Pivot | engine placement | base center at the origin; a corner if the level snaps by corner (Epic) |
| Texture set | stacking, mirroring, UV2 | 2048, unique UVs (UVs belong to scenario-maya-retopology-uv) |
## Workflow
Every stage is a headless `mx_run` job that saves a new version with preview off; the GUI bridge is
for playblasts and interactive tools (substitutes in
[`references/procedures.md`](references/procedures.md)). Component lists cross stages only through
`MM.component_record` and `MM.carry_components`, never by name or by an index read before a topology
edit (P18).
1. **Session and brief.** `cmds.about(version=True)` (Smart Bevel changed in 2027.1 and 2027.2),
units cm, Y up, brief in numbers (P1). GATE: assumptions written.
2. **Blockout at real size.** Primitives named at creation, stand on the grid, pivot per convention,
freeze, delete history (P2). GATE: `mx_audit` frozen, no `default_name` or
`duplicate_short_name`, dimensions within 2% [added]; silhouette and clay sheets compared to
reference.
3. **Primary form, clean grid.** Write down the narrowest feature (groove, recess wall, gap) and its
width: the grid near it takes that spacing, the rest balances to it; decide density or
redirection per corner from the camera distance. Close the biggest quads, balance, stress-test by
adding loops (Mario [00:10:11]); curves with Edit Edge Flow (antCGi [00:16:04]). GATE:
`MM.balance(m)["edges_over_limit"] == 0` before support loops; `MM.cage_report(m)`: n-gons 0,
every curved triangle removed or proven by the highlight review; loops continuous on the wire
sheet.
4. **Secondary forms.** `MM.extrude(faces, offset_cm=...)` then recess (P3; refuses the empty
extrude); openings from one quad; cylinders with `MM.cylinder_sides_for` and
`MM.build_quad_cylinder` (P4), support loops cut before the opening; or `polyCBoolOp` on manifold
meshes, then Smart Bevel (P5). GATE: zero-length edges, coincident pairs, non-manifold all 0.
5. **Edge holding, per destination:**
- SubD hero or bake high, portable: support loops (offset rings, beveled-cube corner routing,
Mario [00:44:24]).
- SubD staying in Maya, Arnold or USD: creases, one method, values at or below render levels
(`MM.crease`, `MM.crease_report`, P6).
- Game low: chamfers with `MM.bevel` (Smart Bevel after booleans, legacy Fractional on clean
quads) plus `MM.weighted_normals`, or hard edges on UV seams and a baked normal map
(Polycount).
- Still only from CAD or booleans: Smart Bevel, no retopology. GATE:
`MM.cage_report(cage)["ready_to_smooth"]` (hard edges 0, since a faceted patch is a hard edge,
Mario [01:28:38]; no fan caps; 6+ poles justified); `MM.highlight_review(..., subdiv=n)`
stripes continuous across every cut; bevel `problems` empty; `crease_report` clean.
6. **Game low and bake prep** (P10). `MM.smooth_copy` the high; duplicate the cage and reach the low
only by deleting edges (`MM.flat_edges` off the silhouette, loops ended with triangles); radius
edges on round corners, evenly spaced, one on the crest (On Mars [00:12:50] [00:26:34]); parts
touching the body welded in or their hidden faces deleted (Polycount: contiguous low);
`MM.shrink_wrap`; `MM.set_hard_by_angle(low, 45)`; `MM.triangulated_copy(low, toward=high)` for
bake and export. GATE: `MM.deviation` recorded, silhouettes overlap, tris in budget, engine
vertices reported, each separate shell (`polyEvaluate(shell=True)`) justified,
`diagonals_wrong_after == 0`.
7. **Characters: deformation check** (P13). Loops across wrist and ankle, lids and lips with
matching counts, mouth-corner loop under the cheek, neutral face (antCGi; Jessica [01:00:30]).
GATE: `MM.bend_test` shows no flips and no regression against the previous topology; `restored`
true.
8. **Hygiene and handoff** (P14, P15). `MM.cleanup_technical`, `MM.inverted_shells`,
`MM.handoff_report(roots, out, to=...)`,
`mx_validate.validate(profile="model", fix=SAFE_FIXES + ("render_stats",))`, report again, save a
new version. GATE: report `ok`; cleanup `ok`; 0 inverted shells; preview off; pending items
named; sheets opened.
## Numbers
| Value | Setting | Relative to / source |
| -------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Neighbor quad size | under 2:1 | base grid, support loops excluded (Mario [00:08:31]) |
| Minimum density | spacing = narrowest feature | balance the rest to it (Mario [00:17:19]) |
| Cylinder sides | 20, 24, 28, 32 | multiples of 4, aligned with the cut (Mario [01:12:04]) |
| Round feature on a cage | about 6 spans hero, 4 background | OpenSubdiv |
| Valence | 4 regular; flag 6+; GPU limit about 27 | OpenSubdiv |
| Radius edges on a visible round corner | more than 2 to 3, even spacing, one on the crest | On Mars [00:25:29] [00:26:34] |
| Loops per joint | 1 control + 2 support; knuckles 3 | Jessica [01:15:51] [01:17:34] |
| Crease | Maya value N creases N levels; above 5 rarely; 10 tears under displacement | Maya Help; OpenSubdiv |
| Smart Bevel | Width world units; Depth 1 chamfer, 0.5 rounded; 1 segment hard, 2 to 3 typical | Maya 2027 Help |
| Legacy bevel defaults | Fractional, 1 segment, depth 1, smoothing angle 30; 2 segments on box corners | Maya 2027 Help; FlippedNormals [00:18:18] |
| Hard edges on a mechanical low | above about 45 degrees, and on UV seams | Polycount |
| Grenade budgets | cage 61k, low 24k; "polygons" is about half the tris | On Mars [00:04:21] [00:21:31] |
| Sheet share | surface cm² x (px/cm)² / map px² (12,800 cm² at 10.24 = 32% of 2048²) | arithmetic [added] |
| Subdivision cost | x4 polygons per level; preview levels + Arnold iterations add up | Arnold doc |
## Quality gates
Measurable, per mesh:
`mx_audit.verdict(mx_audit.audit(m, texture_size=2048), "game" | "film" | "subd", max_tris=budget)`
has no `error`, plus the `MM` checks named in each GATE; scene:
`mx_validate.validate(profile="model")` no `fail`; together: `MM.handoff_report`. Visual, opened
every time: `mx_review.review` sheet (silhouette vs reference, clay, wire loops, normals);
`MM.highlight_review` with `focus=` closeups on every cut (kinks, dark streaks, wobbles are
pinching, Mario frames 00:12:45, 01:38:42); high and low silhouettes side by side; in a GUI session,
two-sided lighting off or backface culling. Judge with
[`references/critique.md`](references/critique.md).
## Common mistakes
| Mistake | Looks like | Fix |
| ------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------ |
| Empty extrude | loop stops dead; crease in smooth preview | `MM.extrude` refuses it; `mx_audit` zero-length edges |
| Vertical cuts on a cylinder | wobbling highlight | rebuild with more sides, or smooth once |
| Fan cap | dimple at the cap center | `cage_report` fan poles; `MM.build_quad_cylinder` |
| Hard edges left on a cage | faceted patches when smoothed | `polySoftEdge(angle=180)` until `cage_report` hard edges 0 |
| Cleanup with tessellation on | random triangulation | `MM.cleanup_technical`; n-gons by hand |
| Preview on at save, plus Arnold iterations | heavy files, huge slow renders | `MM.subdiv_setup` in one place; `mx_validate` smooth_preview |
| Creases on an FBX asset | sharpness gone in engine | bevel, or ship a smoothed copy |
| Weighted normals on a deforming mesh | shading stuck while skinning | static meshes only |
| Hard edges off UV seams | vertex count up, nothing gained | seams on hard edges (`hard_edge_components`) |
| Whole shell inside out | black with two-sided lighting off, fine with it on | `MM.inverted_shells`, reverse |
| V-snap without weld | seam in smooth preview | Target Weld; `coincident_vertices` |
| Round high corner, sharp low | bake artifacts | radius edges on the low, one on the crest |
| Low left floating, or parts intersecting | bake misses, overlap errors, UV space on hidden faces | `MM.shrink_wrap`; weld parts in or delete hidden faces |
| Engine picks the diagonal | ridge instead of valley, zig-zag shading | `MM.triangulated_copy(toward=high)`, export triangulated |
| Component ids reused after an edit | wrong edges deleted, silhouette lost | `MM.carry_components` refuses; re-derive |
| Spiral limb loops, pole on the chest | muddy weights, kinks | concentric loops, reroute the pole |
## Handoffs
- **Receives** the brief from scenario-maya-expert; sculpts from scenario-zbrush-expert (check
scale, ZBrush has no units; orientation; locked normals); generated meshes from scenario-3d
(reference or bake high only).
- **Delivers to scenario-maya-retopology-uv** (UVs, bake prep): a new version
`<asset>_model_v###.ma`, `<asset>_GRP` with `_geo` meshes (engine names such as `SM_` and `UCX_`
for games), the cage, `<asset>_high` with floaters separate and `castsShadows` off for AO
(Polycount), the low if built, `handoff_<to>.json` with UVs pending, the hard-edge list for UV
cuts, and the sheets looked at. Manifold after triangulation too: Unfold3D refuses non-manifold
meshes and unfolds a triangulated copy (P17).
- **Delivers to scenario-maya-rigging** (deformation-ready): `to="rigging"` clean (X symmetry, no
locked normals, no history), grounded and centered, eyes separate and looking ahead, symmetric
parts combined, `bend_test` numbers (antCGi e74K checklist).
- **Delivers to scenario-maya-lookdev** (film SubD): subdivision set in one place, crease sets named
with values, preview off. FBX export goes to scenario-maya-pipeline-scripting.
## Maya 2027 notes
- Smart Bevel (`polySmartBevel`, 2027): world-unit Width, Depth profile, Filter default Selected
Edges; output differs 2027.0, .1, .2; flags unknown until probed (`MM.bevel` records `attr_map`).
Its box-corner behavior is untested: the 2-segment rule comes from the legacy bevel, so read the
`problems` census. Old bevel is "legacy bevel", with Filter attributes and intersection-only
bevels on booleans since 2025.
- Shift+drag is "Shift Extrude" (2025); Smart Extrude stitches overlapping faces, Edit Mesh >
Extrude does not. Booleans: `polyBoolean` (2023), 3ds Max engine (2025.3), Volume mode (2026).
- Smooth Mesh Preview is OpenSubdiv Catmull-Clark; Crease Tool and Crease Sets are exclusive per
component.
- New scenes default to OpenPBR Surface; the highlight review uses aiStandardSurface.
- Reduce is decimation, not retopology; Quad Draw is interactive only.
- FBX import can bring user normals (2027); imported normals may arrive locked (Mesh Display >
Unlock Normals).
- macOS keys: Ctrl is Control, Alt is Option.
## References
- `references/procedures.md`: full code P1 to P18 with test paths. Load before writing any modeling
code.
- `references/critique.md`: the judging rubric. Load at every gate and before reporting.
- [`references/expert-notes.md`](references/expert-notes.md): each expert's reasoning, timestamps,
disagreements. Load for an unfamiliar asset type or a judgment call.
- [`references/gui-paths.md`](references/gui-paths.md): menus and hotkeys for a GUI or computer-use
session.
- [`references/sources.md`](references/sources.md): sources, credentials, best timestamps.
© scenario-labs · MIT · scenario-labs/skills