# Bim Scripting

> Revit API fundamentals, Dynamo for Revit, pyRevit framework, IFC schema and openBIM, model checking, automated documentation, clash detection, and BIM interoperability tools for AEC computational design

- **Type:** Skill
- **Install:** `agentstack add skill-amanbh997-claude-skills-for-computational-designers-bim-scripting`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Amanbh997](https://agentstack.voostack.com/s/amanbh997)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Amanbh997](https://github.com/Amanbh997)
- **Source:** https://github.com/Amanbh997/Claude-skills-for-Computational-Designers/tree/main/skills/bim-scripting

## Install

```sh
agentstack add skill-amanbh997-claude-skills-for-computational-designers-bim-scripting
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# BIM Scripting

Comprehensive reference for automating Building Information Modeling workflows
through scripting, API access, and interoperability platforms. This skill covers
the full spectrum of BIM automation --- from visual programming with Dynamo
through deep Revit API scripting, pyRevit extension development, IFC/openBIM
data exchange, model checking, automated documentation, and cross-platform
interoperability via Speckle, BHoM, and Rhino.Inside.Revit.

---

## 1. BIM Automation Philosophy

### Why Script BIM

BIM models are databases disguised as 3D geometry. Every wall, door, room, and
duct segment carries structured data --- type, dimensions, material, cost code,
fire rating, acoustic class, phase, workset, design option. Manual manipulation
of that data does not scale. A 200-unit residential project may contain 40,000+
elements, each with 30--80 parameters. Changing a naming convention, verifying
parameter completeness, or exporting coordinated drawing sets by hand is not
just slow --- it is error-prone and unrepeatable.

Scripting BIM means treating the model as a programmable data source:

- **Read** element properties at scale (audit, validate, report).
- **Write** parameter values in batch (standards enforcement, data enrichment).
- **Create** elements procedurally (repetitive layouts, adaptive placement).
- **Transform** geometry computationally (facade panelization, structural optimization).
- **Export** deliverables automatically (sheets to PDF, models to IFC, data to dashboards).

### Manual vs. Automated BIM Workflows

| Workflow | Manual Approach | Automated Approach | Time Savings |
|---|---|---|---|
| Parameter QA | Open each element, check value | Script scans all elements, flags violations | 95% |
| Sheet creation | Place views, adjust crops, add tags one by one | Script generates sheets from template rules | 90% |
| Clash detection | Visual inspection in section views | Navisworks / script-based interference check | 85% |
| Export to IFC | File > Export > IFC, configure, repeat per model | Batch script exports all linked models with preset mappings | 80% |
| Room finish schedule | Manual schedule, manual formatting | API-generated schedule with conditional formatting | 75% |
| Design option comparison | Duplicate views, switch options, compare | Script generates comparison report with metrics | 90% |
| Naming convention enforcement | Manual review of browser tree | FilteredElementCollector + regex validation | 98% |

### ROI of BIM Automation

The return on investment for BIM scripting follows a clear pattern:

1. **First script** --- 2-8 hours to develop, saves 1-4 hours per use. Break-even after 2-3 uses.
2. **Script library** (20-50 tools) --- 200-500 hours to develop, saves 10-30 hours per project. Break-even within 1-2 projects.
3. **Custom application** --- 500-2000 hours to develop, saves 50-200 hours per project. Break-even within 3-5 projects.
4. **Enterprise platform** --- 2000-10,000 hours to develop, transforms entire practice workflow.

### The Automation Spectrum

```
Level 1: Visual Programming (Dynamo, Grasshopper)
  - Lowest barrier to entry
  - Best for designers who think visually
  - Limited scalability and version control
  - Good for: one-off design explorations, parameter mapping, geometry generation

Level 2: Scripting (Python in Dynamo, pyRevit, RevitPythonShell)
  - Moderate barrier to entry
  - Full API access with Python convenience
  - Version-controllable, shareable
  - Good for: batch operations, custom tools, data workflows

Level 3: Custom Tools (C# add-ins, pyRevit extensions)
  - Higher barrier to entry
  - Compiled performance, custom UI, ribbon integration
  - Deployable to teams
  - Good for: production tools, firm-wide standards enforcement

Level 4: Full Applications (standalone apps, web dashboards, microservices)
  - Highest barrier to entry
  - Complete control over UX and data pipeline
  - Cloud-scalable, multi-user
  - Good for: enterprise BIM management, cross-project analytics
```

### When to Automate vs. When to Model Manually

Automate when:
- The task repeats across projects or phases.
- The task involves more than 50 elements.
- Consistency and auditability are critical (QA/QC, code compliance).
- The output feeds downstream processes (cost, energy, structural analysis).
- Human error risk is high (naming, classification, spatial containment).

Model manually when:
- The task is a one-time creative act (early concept massing).
- Judgment and spatial intuition outweigh procedural logic.
- The element count is small and the rules are ambiguous.
- The cost of developing automation exceeds the cost of manual work.

### BIM Maturity Levels and Automation

| BIM Level | Description | Automation Role |
|---|---|---|
| Level 0 | 2D CAD, no BIM | CAD scripting (AutoLISP, VBA) for drawing automation |
| Level 1 | 3D modeling, 2D documentation | Basic Dynamo scripts, parameter management |
| Level 2 | Federated models, structured data exchange | IFC workflows, clash detection, model checking |
| Level 3 | Integrated single model, full lifecycle data | API-driven analytics, real-time dashboards, AI-assisted QA |
| Level 4 (emerging) | Digital twin, IoT-connected, predictive | Continuous model sync, ML-driven optimization, autonomous agents |

---

## 2. Revit API Fundamentals

### Architecture

The Revit API is a .NET framework (C# or VB.NET natively, Python via IronPython
or CPython with RevitPythonShell/pyRevit). The object hierarchy:

```
UIApplication
  └── Application           (Revit application-level settings, version info)
       └── Document          (the .rvt file; model database)
            ├── Elements      (everything in the model)
            ├── Views         (plans, sections, 3D views, schedules)
            ├── Phases        (existing, new construction, demolition)
            ├── DesignOptions  (option sets and options)
            ├── Worksets       (worksharing partitions)
            └── Settings       (project units, line styles, fill patterns)
```

### Element Types

Every object in a Revit model inherits from `Element`. Key subclasses:

| Class | Description | Example |
|---|---|---|
| `FamilyInstance` | Placed instance of a loadable family | Door, window, furniture, fixture |
| `Wall` | System family: wall element | Basic Wall, Curtain Wall, Stacked Wall |
| `Floor` | System family: floor slab | Generic Floor, composite assemblies |
| `Roof` | System family: roof element | Basic Roof, extrusion roof |
| `Ceiling` | System family: ceiling element | Compound ceiling, basic ceiling |
| `FamilyInstance` (structural) | Columns, beams, braces | Steel W-shapes, concrete columns |
| `Room` | Spatial element for architectural spaces | Bounded by room-bounding elements |
| `Area` | Spatial element for area plans | Gross area, rentable area |
| `View` | Any view in the model | `ViewPlan`, `ViewSection`, `View3D`, `ViewSheet` |
| `ViewSheet` | A sheet for documentation | Contains viewport placements |
| `ViewSchedule` | A schedule/quantity takeoff | Tabular data extraction |
| `Group` | Grouped elements | Model groups, detail groups |
| `Level` | Datum: horizontal reference plane | Defines story heights |
| `Grid` | Datum: vertical reference plane | Structural grid lines |
| `ReferencePlane` | Construction plane | Alignment references |

### Categories, Families, Types, Instances

This four-level hierarchy is central to Revit:

```
Category        (e.g., Doors)
  └── Family      (e.g., Single-Flush)
       └── Type     (e.g., 36" x 84")
            └── Instance  (placed door #1, #2, #3...)
```

- **Category**: broad classification (Walls, Doors, Floors, Furniture). Each has a `BuiltInCategory` enum.
- **Family**: a parametric definition (.rfa file for loadable families; system families are built-in).
- **Type**: a named set of parameter values within a family (dimensions, materials).
- **Instance**: a placed occurrence with instance-specific parameters (location, room, mark).

### Parameters

Parameters store all non-geometric data on elements.

| Parameter Kind | Scope | Definition | Access |
|---|---|---|---|
| Built-in | Hardcoded by Revit | Predefined (e.g., `WALL_BASE_OFFSET`) | `element.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET)` |
| Project | One project file | Defined in Project Parameters dialog | `element.LookupParameter("MyParam")` |
| Shared | Across projects/families | Defined in Shared Parameters file (.txt) | `element.get_Parameter(guid)` or by name |
| Family | Inside .rfa family | Defined in Family Editor | Exposed as type or instance parameter |
| Global | Project-wide value | Not element-bound; referenced by formulas | `GlobalParametersManager` |

Parameter storage types:
- `StorageType.String` --- text
- `StorageType.Integer` --- integers and YesNo (0/1)
- `StorageType.Double` --- real numbers (always in internal units)
- `StorageType.ElementId` --- reference to another element (material, type, level)

### Transactions

Every model modification must occur inside a `Transaction`. Without it, the API
throws an `InvalidOperationException`.

```python
# Python (pyRevit / RevitPythonShell)
from Autodesk.Revit.DB import Transaction

doc = __revit__.ActiveUIDocument.Document
t = Transaction(doc, "Batch Update Parameters")
t.Start()

try:
    # ... modify elements ...
    t.Commit()
except Exception as e:
    t.RollBack()
    print("Error: {}".format(e))
```

Transaction types:
- **Transaction** --- standard single transaction (most common).
- **TransactionGroup** --- wraps multiple transactions; can assimilate (merge into one undo) or roll back all.
- **SubTransaction** --- nested within a Transaction; can roll back independently without aborting the parent.

### FilteredElementCollector

The primary mechanism for querying elements in a Revit model. It operates as a
builder pattern with filters:

```python
from Autodesk.Revit.DB import (
    FilteredElementCollector, BuiltInCategory,
    ElementCategoryFilter, ElementClassFilter
)

# All walls in the model
walls = FilteredElementCollector(doc) \
    .OfCategory(BuiltInCategory.OST_Walls) \
    .WhereElementIsNotElementType() \
    .ToElements()

# All door types (not instances)
door_types = FilteredElementCollector(doc) \
    .OfCategory(BuiltInCategory.OST_Doors) \
    .WhereElementIsElementType() \
    .ToElements()

# All family instances of a specific class
instances = FilteredElementCollector(doc) \
    .OfClass(FamilyInstance) \
    .ToElements()

# Elements in a specific view
view_elements = FilteredElementCollector(doc, view.Id) \
    .OfCategory(BuiltInCategory.OST_Walls) \
    .ToElements()
```

### Geometry Access

Extracting geometry from Revit elements:

```
Element
  └── get_Geometry(Options)
       └── GeometryElement (iterable)
            ├── Solid
            │    ├── Faces (FaceArray)
            │    │    └── Face → Surface, UV domain, normal
            │    └── Edges (EdgeArray)
            │         └── Edge → Curve
            ├── GeometryInstance (for family instances)
            │    └── GetInstanceGeometry() → GeometryElement
            ├── Curve (for line-based elements)
            ├── Point
            └── PolyLine
```

### Units

Revit internal units are **always**:
- Length: **feet**
- Angle: **radians**
- Area: **square feet**
- Volume: **cubic feet**

Use `UnitUtils.ConvertFromInternalUnits()` and `UnitUtils.ConvertToInternalUnits()`
for conversion. In Revit 2022+, use `UnitTypeId` instead of `DisplayUnitType`.

### Events

The Revit API provides application and document-level events:
- `Application.DocumentOpened` / `DocumentClosing` / `DocumentSaved`
- `Application.ViewActivated`
- `Application.DialogBoxShowing` (intercept and auto-dismiss dialogs)
- `Document.DocumentChanged` (react to element modifications)
- `UIApplication.Idling` (periodic background processing)

### External Commands, Applications, Events

| Type | Purpose | Lifecycle |
|---|---|---|
| `IExternalCommand` | Single button click action | Runs once per invocation |
| `IExternalApplication` | Ribbon tab/panel setup, startup logic | Runs at Revit startup/shutdown |
| `IExternalDBApplication` | DB-level (no UI) startup logic | For services, updaters |
| `IExternalEventHandler` | Thread-safe model modification from external threads | Raised via `ExternalEvent` |

### C# vs. Python for Revit API

| Criterion | C# | Python (IronPython/CPython) |
|---|---|---|
| Performance | Compiled; fastest | Interpreted; slower for large loops |
| Debugging | Full Visual Studio debugger | Print statements, limited debugger |
| Deployment | DLL add-in; requires compilation | Script file; instant edit-run cycle |
| Learning curve | Steeper (typed language, project setup) | Gentler (dynamic typing, REPL) |
| API coverage | 100% | 100% (same .NET API via clr) |
| Ecosystem | NuGet packages, .NET libraries | Python packages (limited in IronPython) |
| UI creation | WPF, WinForms with full designer | WPF possible but harder; rpw simplifies |
| Best for | Production add-ins, enterprise tools | Rapid prototyping, small utilities, pyRevit |

---

## 3. Dynamo for Revit

### Core Advantages

Dynamo is a visual programming environment integrated with Revit (ships with
Revit since 2017). Key strengths:

- **Visual dataflow** --- nodes connected by wires; intuitive for non-programmers.
- **Live Revit connection** --- read/write model elements in real time.
- **Geometry preview** --- 3D preview of computational geometry before committing to Revit.
- **Extensibility** --- custom nodes in Python, C#, or DesignScript; package manager ecosystem.

### Revit-Specific Nodes

Dynamo provides dedicated Revit node categories:

- **Selection**: Select Model Element, Select Elements by Category, All Elements of Category
- **Create**: Wall.ByCurveAndHeight, Floor.ByOutlineTypeAndLevel, FamilyInstance.ByPoint
- **Modify**: Element.SetParameterByName, Element.MoveByVector, Element.OverrideColorInView
- **Query**: Element.GetParameterValueByName, Element.BoundingBox, Room.Boundaries

### Dynamo Player

Dynamo Player exposes Dynamo scripts as simple button-click tools for end users
who do not need to understand the graph. Configure inputs as user-facing
prompts. Best practice: design scripts specifically for Player with clear input
labels and minimal required interaction.

### Geometry Kernels

Dynamo uses **two separate geometry engines**:

1. **DesignScript / ASM (Autodesk Shape Manager)** --- Dynamo's native geometry kernel.
   Creates Points, Curves, Surfaces, Solids in Dynamo's 3D preview.
2. **Revit geometry** --- the actual BIM model geometry.

These are **not interchangeable**. A Dynamo `Surface` is not a Revit `Face`.
Converting between them requires explicit nodes:
- `Surface.ByPatch` (Dynamo) vs. `FaceWall.Create` (Revit)
- `Curve.ByPoints` (Dynamo) vs. `ModelCurve.ByCurve` (Revit)

### Common Revit Workflows in Dynamo

1. **Room-based floor finish placement** --- query room boundaries, offset curves, create floor elements by outline.
2. **Adaptive component placement** --- distribute families along curves or surfaces with parameter-driven spacing.
3. **Parameter read/write** --- bulk read element parameters to Excel, modify, write back.
4. **View creation** --- generate scope boxes, create dependent views per scope box, apply view templates.
5. **Sheet setup** --- create sheets from list, place viewports at coordinates, populate titleblock parameters.
6. **Keynote management** --- read keynote table, validate against model, update keynote parameters.
7. **Area analysis** --- extract room areas, calculate ratios (net-to-gross, circulation percentage), color-code by metric.

### Essential Packages

| Package | Author | Key Capabilities |
|---|---|---|
| Clockwork | Andreas Dieckmann | 500+ utility nodes; view manipulation, element filtering, string operations |
| Rhythm | John Pierson | Revit-focused; sheet management, view manipulation, element creation |
| archi-lab | Konrad S

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Amanbh997](https://github.com/Amanbh997)
- **Source:** [Amanbh997/Claude-skills-for-Computational-Designers](https://github.com/Amanbh997/Claude-skills-for-Computational-Designers)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-amanbh997-claude-skills-for-computational-designers-bim-scripting
- Seller: https://agentstack.voostack.com/s/amanbh997
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.