mutinybim-groups-phases — Claude Code skill: features and setup
This Claude Code skill manages MutinyBIM groups, phases, and typed elements. It activates for tasks involving element groups, construction phases, or view filters.
Apache-2.0 ★ 108 updated 2026-11-13
npx skills add permitzip/mutinybim --skill mutinybim-groups-phases -a claude-codeWhat mutinybim-groups-phases does
The skill creates and edits groups and phases, assigns elements to groups, and sets the active group and phase. For views, it configures the phase, phase filter, and group visibility; for walls, slabs, beams, and rooms, it changes class, type, or values. Edits go through a preview and approval.
It requires the mutinybim core and the MutinyBIM MCP server with the groups-phases family enabled. A locked group cannot be edited, moved, or deleted; such a request is refused without changing anything. The skill can also mark existing and demolished elements for a demolition plan.
What it helps with
- organize model elements into groups
- assign construction or demolition phases to elements
- set a view's phase filter and group visibility
- change the class or type of a wall, beam, or room
Example prompts for the agent
- Create a group called “Roof” and assign the selected elements to it.
- Mark the existing elements and set a demolition phase for the ones being removed.
- Show existing and demolished elements in this view using a phase filter.
How to install mutinybim-groups-phases
1Skills CLI (Vercel)
npx skills add permitzip/mutinybim --skill mutinybim-groups-phases -a claude-code2Manually: put the files in place
~/.claude/skills/mutinybim-groups-phases/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/mutinybim-groups-phases/
1Skills CLI (Vercel)
npx skills add permitzip/mutinybim --skill mutinybim-groups-phases -a codex2Manually: put the files in place
.agents/skills/mutinybim-groups-phases/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add permitzip/mutinybim --skill mutinybim-groups-phases -a cursor2Manually: put the files in place
.cursor/skills/mutinybim-groups-phases/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install permitzip/mutinybim packages/bim-plugin/skills/mutinybim-groups-phases2Manually: put the files in place
.github/skills/mutinybim-groups-phases/SKILL.md1Skills CLI (Vercel)
npx skills add permitzip/mutinybim --skill mutinybim-groups-phases -a gemini-cli2Platform CLI
gemini skills install https://github.com/permitzip/mutinybim --path packages/bim-plugin/skills/mutinybim-groups-phasesManually: put the files in place
.devin/skills/mutinybim-groups-phases/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.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 mutinybim-groups-phases
How do I install mutinybim-groups-phases in Claude Code?
Run npx skills add permitzip/mutinybim --skill mutinybim-groups-phases -a claude-code. The skill file is at ~/.claude/skills/mutinybim-groups-phases/SKILL.md.
What does mutinybim-groups-phases do?
It manages MutinyBIM groups, phases, phase filters, and properties of typed elements. It also configures a view's phase and group visibility.
What does mutinybim-groups-phases need to run?
It requires the mutinybim core and a MutinyBIM MCP server with the groups-phases family enabled.
Source text
SKILL.md · Apache-2.0
---
name: mutinybim-groups-phases
description: "MutinyBIM pack for groups, phases and typed elements: create, update, lock and delete groups, assign elements, the active group and phase, phases and phase filters, a view's phase and groups, and the class, type and values of typed elements (walls, slabs, beams, rooms). Use with the mutinybim core. Trigger on: group, lock, phase, existing, demolition, new construction, phase filter, element type, element values."
license: Apache-2.0
compatibility: "Needs the mutinybim MCP server with the groups-phases family turned on (bim_enable_pack, --packs groups-phases, or /packs/groups-phases/mcp under the MutinyBIM base)."
metadata:
pack: "groups_phases"
mcp-server: "mutinybim"
family: "groups-phases"
token-cap: "5200"
tools: "bim_list_groups_and_phases bim_preview_organization_edit bim_create_group bim_update_group bim_delete_group bim_assign_to_group bim_set_active_group_and_phase bim_create_phase bim_update_phase bim_set_element_phases bim_set_view_organization bim_set_phase_filter bim_delete_phase bim_delete_phase_filter bim_set_element"
---
# MutinyBIM: groups and phases
A family of the `mutinybim` core. Activate `mutinybim` first: it has the
script tools, the four starting reads and the rules for every change (preview, say the change, edit with `base_revision`, report the server's
answer). The pictures and printing are the `model` family.
Every MutinyBIM element (duct, pipe, part, wall…) is in one **group** and is
**built in** one **phase**, and may be **demolished in** a later one. Elements
with no group are in General; with no phase, New construction. Built-in
groups: General, Existing to remain, New work, Demolition, Coordination.
Built-in phases: Existing, New construction. A view shows the model as of its
**phase** through its **phase filter** (Show all, Show new, Show existing +
demo, Show complete), and shows / halftones / hides each group. Views, sheets,
levels and types have no group or phase.
| Tool | Use it to |
| --- | --- |
| `bim_list_groups_and_phases` (read) | Groups (locked?, default visibility), phases in time order, phase filters, the active group and phase, and each view's phase, filter and group visibility. `include_counts` adds elements per group (reads the whole model) |
| `bim_preview_organization_edit` (read) | Run one groups/phases kernel command without saving: what would change or the reason it would be refused |
| `bim_create_group` / `bim_update_group` / `bim_delete_group` (approval) | Add, rename, recolour, set default visibility, **lock / unlock** (on its own call), delete (`move_to` when it has elements; General can't be deleted) |
| `bim_assign_to_group` (approval) | Put `element_ids` (a run, a branch, a box selection) in a group |
| `bim_set_active_group_and_phase` (approval) | Where new work goes: the active group, or the phase new elements are built in (one per call) |
| `bim_create_phase` / `bim_update_phase` (approval) | Add a phase (`after` a phase, `null` = first, absent = last), rename, or move it in time |
| `bim_set_element_phases` (approval) | `built_in` / `demolished_in` (null = not demolished), or `action: "demolish"` (in `phase`, default the active one) / `"restore"` |
| `bim_set_view_organization` (approval) | A view's `phase`, `phase_filter`, and `groups` (name → show / halftone / hide; other groups keep theirs). Reaches the canvas, printed drawing, sheets and PDF |
| `bim_set_phase_filter` (approval) | Create a filter (name + all four of new, existing, demolished, temporary) or change one; each is show, halftone, dashed or hide |
| `bim_set_element` (approval) | **Typed elements**, one change per call on walls, slabs, openings, rooms, grids, columns, beams and components (see below): `class`, `type_id`, `values`, `place`, `lock` / `lock: false`, or `new_type`. A part takes its class and its add-on parameters (`<pack>.<name>`) here too |
| `bim_delete_phase` / `bim_delete_phase_filter` (approval) | Remove a phase or phase filter nothing uses; otherwise refused with what uses it (elements, views, the default phase, the last one) |
**Locked groups.** Nothing in a locked group can be created, changed, moved,
demolished or deleted, by anyone, agents included; an edit that would touch
one (a part move that would push a locked run, too) is refused and nothing
changes. Report the refusal word for word and ask the person whether to unlock
the group. Never unlock a group yourself unless the person asked for exactly
that, and never route around a lock.
## Workflows
**Demolition plan:** `bim_list_groups_and_phases` → `bim_set_element_phases`
with `built_in: "Existing"` on what was there before the project, then
`action: "demolish"` on what is removed (default: the active phase) →
`bim_create_view` (or reuse one; `mutinybim-views-sheets`) →
`bim_set_view_organization` with `phase_filter: "Show existing + demo"`:
demolished work prints dashed, new work is hidden → sheet and print as usual.
**Organise work by group:** `bim_inspect_network` or `bim_query_elements` for
the run's ids → `bim_assign_to_group` → `bim_set_view_organization` with
`groups` to hide or halftone it per view. Lock a finished group only when the
person asks.
**Typical unit or bay:** put one unit's elements in their own group
(`bim_create_group` → `bim_assign_to_group`), then `bim_update_group` with
`typical { count, columns, spacing_ft: { x, y }, mark? }` (count includes the
original; negative `y` goes down the plan) on its own call. Copies draw on
plans and count in every trade's totals (drain fixture units, service,
meter, project), once per copy. `typical: null` stops repeating. General
can't be a typical.
**Contract cap on typicals:** `bim_set_active_group_and_phase` with
`typical_cap` alone sets how many typical types the contract covers;
`bim_list_groups_and_phases` reads `typicals { count, contract_covers }`.
More typicals than the cap is a coordination warning, not a refusal: say it
and let the person decide. A finding id like `<group>#<mark>/<element>` is
copy `<mark>` of that group: explain it as "copy 002 of Unit A" and point at
`<element>`.
If a tool here is missing after turning this family on, say exactly which
tool is missing; don't substitute another.
## Typed elements (`bim_set_element`)
Building and structure elements carry what the engineer says about them, the
same way in every trade. Preview with `bim_preview_part_edit`
(`tool: "bim_set_element"`), say the change, then call it (one Approve card).
Give `element_ids` (from `bim_query_elements`) and exactly one of:
- `class`: a class id from the model's registry (`arch.wall`, `struct.beam`,
an add-on's or the firm's class; `bim_schedule_fields` in
`mutinybim-schedules` lists them). `null` clears it so the class is
recognised from the element again. A class that doesn't admit the kind is
refused with the reason.
- `type_id`: a shared type (`null` clears it). Make one first with
`new_type: { name, class?, for_kinds? }` (no `element_ids`); its id comes
back in the saved answer. Type values read under the element's own.
- `values`: by parameter key. A plain value goes as given; `{ "value": 1.3935456,
"unit": "m2/occ" }` converts to the unit the parameter stores and is refused,
in words, when the key has no definition for that element's class or the
unit is of the wrong kind. `null` removes a value. On a part, only add-on
parameters (`<pack>.<name>`) go here; its type's parameters stay with
`bim_set_parameters`.
- `place`: geometry in plan feet on a `level`: `point` (one point, with
`rotation_deg`), `line` (start, end: walls, beams, grids), `path` (two or
more), `area` (three or more: slabs, rooms); `z_ft` above the level.
`null` clears it.
- `lock: { state: "existing" | "issued", reason }` stops anyone changing the
elements until `lock: false`. Lock only when the person asks, and quote
their reason.
`bim_query_elements` reads it back: `class`, `type`, `value.<key>` (in the
parameter's stored unit) and `locked`. Built-in building parameters use
namespaced keys: `arch.fire_resistance` (hours) on walls, `arch.area_per_occupant`
on rooms, `arch.fire_rating` on doors, `struct.camber` on beams; the bare names
still read. Add-on classes bring their own `<pack>.<name>` parameters with units.
<!-- tools: rendered from the catalogue by `npm run build:files`; edit the catalogue, not this list -->
## Tools in this family
| Tool |
| --- |
| `bim_list_groups_and_phases` |
| `bim_preview_organization_edit` |
| `bim_create_group` |
| `bim_update_group` |
| `bim_delete_group` |
| `bim_assign_to_group` |
| `bim_set_active_group_and_phase` |
| `bim_create_phase` |
| `bim_update_phase` |
| `bim_set_element_phases` |
| `bim_set_view_organization` |
| `bim_set_phase_filter` |
| `bim_delete_phase` |
| `bim_delete_phase_filter` |
| `bim_set_element` |
<!-- end tools -->
© permitzip · Apache-2.0 · permitzip/mutinybim