Agent Skills › Fluid-CAD/FluidCAD › fluidcad-custom-features

fluidcad-custom-features

GitHub

Writing custom features for FluidCAD: a feature type of the project's own in a `*.feature.js` module (`fluidcad/sdk` — `Feature.with()`, `defineFeature()`, `buildTool()`, named buckets and frames, pickers, call shapes, raw OpenCascade via `fluidcad/sdk/occt`) that the Custom dropdown offers with its own dialog and that models call like a built-in; and generated definitions: a feature as an insertable part (`definePart`) or a sub-assembly made by code (`Generator`, `layout(g)`, `defineAssembly`). Use it whenever the user wants a custom feature, their own feature type or toolbar button, a `.feature.js` file, `fluidcad/sdk`, `defineFeature`, `registerBuilder`, `definePart`, `defineAssembly` or a generator, asks to turn a repeated construction into one statement, or wants to share them as a package (`package` block, `pack`). Trigger it alongside the FluidCAD skill when the FluidCAD MCP tools (`mcp__FluidCAD__*`) are available and a feature type or a generated definition, not a plain part, is being written.

mcp/skills/fluidcad-custom-features/SKILL.md Fluid-CAD/FluidCAD

Install

npx skills add Fluid-CAD/FluidCAD --skill fluidcad-custom-features -g -y
More Options

Non-standard path

npx skills add https://github.com/Fluid-CAD/FluidCAD/tree/main/mcp/skills/fluidcad-custom-features -g -y

Use without installing

npx skills use Fluid-CAD/FluidCAD@fluidcad-custom-features

指定 Agent (Claude Code)

npx skills add Fluid-CAD/FluidCAD --skill fluidcad-custom-features -a claude-code -g -y

安装 repo 全部 skill

npx skills add Fluid-CAD/FluidCAD --all -g -y

预览 repo 内 skill

npx skills add Fluid-CAD/FluidCAD --list

SKILL.md

Frontmatter
{
    "name": "fluidcad-custom-features",
    "description": "Writing custom features for FluidCAD: a feature type of the project's own in a `*.feature.js` module (`fluidcad\/sdk` — `Feature.with()`, `defineFeature()`, `buildTool()`, named buckets and frames, pickers, call shapes, raw OpenCascade via `fluidcad\/sdk\/occt`) that the Custom dropdown offers with its own dialog and that models call like a built-in; and generated definitions: a feature as an insertable part (`definePart`) or a sub-assembly made by code (`Generator`, `layout(g)`, `defineAssembly`). Use it whenever the user wants a custom feature, their own feature type or toolbar button, a `.feature.js` file, `fluidcad\/sdk`, `defineFeature`, `registerBuilder`, `definePart`, `defineAssembly` or a generator, asks to turn a repeated construction into one statement, or wants to share them as a package (`package` block, `pack`). Trigger it alongside the FluidCAD skill when the FluidCAD MCP tools (`mcp__FluidCAD__*`) are available and a feature type or a generated definition, not a plain part, is being written."
}

Provenance: maintained in the FluidCAD repo (https://github.com/Fluid-CAD/FluidCAD), under mcp/skills/. The installed local skill files are the runtime source of truth.

Writing a custom feature

This skill layers on top of the fluidcad skill. That one owns the loop: read the docs, plan in generic CAD terms, build in increments, check render.state and objectErrors, resolve filters before writing them, screenshot when a feature earns it, and report only what was checked. Follow it for the test part. This skill covers what is specific to a custom feature: deciding that one is warranted, designing it as a feature a user fills in, writing the module, and proving it in a part.

The governing principle: a custom feature is a CAD feature first and code second. Its user picks a face and types a height in a dialog, then fillets its rim and repeats it; design for that user, write the code to that design, and prove it the way that user will use it.

1. Decide whether one is warranted

Write a custom feature when one construction recurs (across models, or across places in a model with different values) and should be one statement, one dialog, one timeline row: a PCB standoff on any face, a ring of clearance holes around any axis, a vent grid on any panel, bosses at a set of connectors.

Don't write one, and say why, when:

  • the geometry occurs once: write the statements in the model;
  • it is the same geometry again in one model: repeat() re-applies a feature at new positions, copy() duplicates a finished shape;
  • it is a whole part reused with other dimensions: a part() with param() values, inserted where needed (the fluidcad-assembly skill) — unless one feature builds that part and it should carry the feature's dialog: then the feature plus definePart (section 9);
  • it is several parts that move against each other, sized from one set of values (a wardrobe with hinged doors and sliding drawers): a generated assembly, Generator + defineAssembly (section 9);
  • a built-in already does it (hole() for drilled, clearance, tapped, counterbored and countersunk holes; draft(); rib(); shell()): search the docs first.

2. Design it in CAD terms

Before code, write the design down the way a CAD user would describe a feature dialog, and show it (under the autonomous fallback, put it in the report):

  • Name and id. A label for the toolbar ("Vent grid") and a plain id (ventGrid). It may not be one of the engine's own types (extrude, fillet, part, sketch, distance, …: "'extrude' is one of the engine's own types: give the feature another id"). The id is the feature's type in every timeline: pick it once. Installed from a package, the feature's type becomes @<handle>/<package>:ventGrid (what get_scene_summary shows); a model still imports and calls ventGrid, and never writes that key.

  • What it does to the solids. Adds material, cuts it, or keeps a separate body: that is a tool (buildTool() returns solids, the base fuses or cuts them) with operations. Changes existing solids in another way (tilts faces, offsets, splits): a modifier (build()); prefer a tool whenever the feature adds or removes material — the modifier surface is the engine's internals, not a settled SDK.

  • Operations and the default. ['add', 'new'] for a boss-like feature, ['remove'] for a cut-only one (it cuts with no chain and shows no tabs), ['remove', 'new'] for a pocket that may also be a separate body. The default is add when offered, else the first listed. buildTool() reads the operation its statement applies — the chain's, else the default; the dialog's tab in the preview; the statement's on a repeat's copy — with this.getOperationMode() ('add', 'new' or 'remove'), when a remove needs a different tool than an add (an internal gear adds the whole ring but removes only the tooth space).

  • Each value, as a dialog row. Typed in: length (in the model's unit), angle (degrees), integer, number, boolean, select, radio, text, with a min/max that keep the geometry valid. A row left alone in the dialog builds what it shows: a boolean without a default is off, a select or a radio without one takes its first option (an optional one stays unset), a slider without one sits at its min, a select with multiple: true is []; a number or a text without one must be typed in (Apply says "Height is required."), so give every size a sensible default. Picked: face, edge, axis (takes world axes, axis statements, straight edges and connectors), plane, sketch, solid, feature, connector, point, anchor, or a union of kinds that take different clicks. One pick or a list (multiple: true). Hide rows that only matter for one choice (visibleWhen), or for one kind of pick (visibleWhen: { at: { not: { surface: 'cylinder' } } } hides a hub's rows while a shaft is picked); a list of such objects shows the row while any one holds ([{ type: 'wardrobe', doors: true }, { type: 'base' }]).

  • The control for each typed-in value. type is what the value is; display and the fields beside it are only how its row looks, and never change the statement. Choose by what the user is deciding:

    • a few choices, all worth seeing at once: radio — display: 'buttons' for 2–3 short labels, 'cards' when pictures tell them apart;
    • many choices: select — display: 'grid' with an image per option when they are recognised by shape, search: true beyond a dozen;
    • several at once: select with multiple: true (the value is a list; min/max count it);
    • a bounded number the user explores: display: 'slider' (needs min and max); a small count: display: 'stepper' (number/integer only); a unit: suffix: 'mm'; a remark that must stay visible: hint (description is the tooltip);
    • one choice narrows another (the sizes of the chosen standard): one select whose options carry when: { standard: 'iso' }, not two selects swapped with visibleWhen (a size table, where an option comes with several combinations, gives when a list of such objects, any one holding). when narrows the dialog only — a hand-written call may pass any declared option, so the builder must handle every one;
    • one value's sensible default depends on another (a wall cabinet is 720 high, a wardrobe 2400): defaults: [{ when: { type: 'wall' }, value: 720 }, { when: { type: 'wardrobe' }, value: 2400 }] beside the plain default, not a value per type. The first entry whose when holds wins; an untouched dialog row follows it live, a touched one keeps its value; a call that leaves the value out gets it from its other values. A when names typed-in values without defaults of their own (one level), and each value must fit the declaration (range, options, offered where its when holds);
    • images are files next to the module ('./vent/slots.svg'), drawn as pictures: use mid-tone strokes, not currentColor.
  • The layout, only when it earns it. A handful of rows needs none: declaration order is the dialog, with a value's group and tab as the short form. Write a layout (with width: 'wide' when rows sit side by side) when values pair up in a row (count and spacing), a rarely used set should fold ({ section, collapsed: true }), or a dimension drawing belongs in the aside. A value that measures something the user may not know (a pressure angle, a profile shift, a backlash) earns an aside of its own — a diagram and a one-line note the card shows while its row has the focus. Rows never cut a label short: a cell that can't fit wraps to its own line, so pair narrow controls and give a long segmented choice (or a select) its own line. A layout places every value exactly once, and then no value may keep its own group or tab.

  • The call a model writes. Picked geometry first and positional, sizes in one object of options: ventGrid(panel.endFaces(), { rows: 4, columns: 6, pitch: 8 }). A list of picks is one array argument or a trailing rest. A pick that may be left out (optional: true, a placement that defaults to the origin) stays first: a call without it goes straight to the options, gear({ teeth: 24 }) (never gear(undefined, …)), and the dialog writes it that way.

  • The buckets: declare named buckets for what a user will fillet, chamfer or sketch on. A downstream fillet, a sketch and every pick on the feature read its buckets; without them f.endEdges() names nothing and the editor writes picks on it as filters. Two layers:

    • the standard ones: which faces are its start faces (where it meets what it grew from), end faces (its far end), side faces, internal faces (bores, a cut's walls) and cap faces. For a cut, the plane the tool starts on (startPlane) classifies the rims;
    • named buckets of its own, for the parts of the result a user will name: a gear's tipFaces/tipEdges, a pocket's floorFaces/floorEdges, a boss's boreFaces/boreEdges. Declared with Feature.with(params, { buckets: { tipFaces: {}, tipEdges: {} } }), each becomes a typed method (fillet(0.3, g.tipEdges()), r.instance(2).tipEdges() on a repeat's copy), the editor writes picks through it first, and the right-click menu offers it ("Gear Tip Edges"). A name ends in Faces or Edges; an edge bucket exists only when declared, and one left out of setBuckets() is the edges of its …Faces sibling. A declaration holds only an optional label (the menus' words). Name the face the feature grows from startFaces, not a bucket of your own: a named bucket drops a face the fusion merges away, startFaces is re-homed onto the stock face.

    List each named bucket in the design with what it holds and in what order (teeth in tooth order, flanks two per tooth); that list becomes the feature's docs/ page (section 4).

  • The preview. The feature chooses with ghost in its metadata: 'toggle' (the default) gives the dialog a Preview toggle that starts off (remembered per feature once the user turns it on) — for a build that may be slow; 'always' previews from the start with no toggle — for a cheap build; false draws none. While it previews, a tool runs buildTool() on every change, and one that takes over 5 s to build times out (the user turns the toggle off and on, or presses Try again with no toggle, to ask again). Keep the build cheap, or override ghost() with a cheaper shape.

  • Can the curated kernel build it? fluidcad/sdk/kernel has cylinders, spheres, cuts and placement transforms. Anything else (a box, a loft, a sweep, an offset) needs raw OpenCascade inside this.occ(): say so in the design, since it is unstable and unchecked.

3. Read the docs

read_doc these before writing (in parallel sub-agents when your client has them; sub-agents read, never write):

  • concepts/custom-features — the module, discovery, the lifecycle, where errors show;
  • api/feature — the class, buildTool() and getOperationMode(), setBuckets() and what it refuses, named buckets in short, the reference readers, ghost();
  • api/feature-buckets — named buckets in full: the naming rule, derived edge buckets, every refusal and its message, what a fusion, a remove and a repeat do to them, the editor's picks;
  • the worked example closest to the design: api/feature-example-gear (named buckets, a raw OpenCascade outline), api/feature-example-bearing-seat (named buckets through a remove), api/feature-example-bosses (several tools at connectors and points), api/feature-example-tube (a different tool for a remove);
  • api/define-feature — the metadata, operations, the call shape, what the dialog can edit;
  • api/feature-params — every value kind, picker and option, unions; each display; the table of what an untouched row shows and the builder gets; a runnable example with every control ("a screw hole with choices");
  • api/feature-layout — only when the design has a layout, width, an aside or a value's own aside;
  • api/sdk-kernel — the geometry, and who owns which shape;
  • api/sdk-occt — only when the design needs raw OpenCascade;
  • api/register-builder — only when the builder must act before it reads its arguments;
  • api/feature-frames — when the feature publishes where it stands (a gear's axis): Feature.with(params, { frames }), setFrames(), g.frame(name);
  • api/define-part, api/generator, api/define-assembly — for a generated part or assembly (section 9).

get_type_definition resolves Feature, FeatureBuckets, FeatureWithOptions, FeatureBucketSpec, FeatureFrameSpec, NamedFrames, ParamSpec, ChoiceOption, FeatureLayout, CallShape, FeatureMeta, OccScope, the kernel classes, and the generated-definition types (Generator, GeneratorLayout, GeneratedPartSpec, GeneratedFrameSpec, GeneratedPose, GeneratorBuildContext, DefinePartMeta, DefineAssemblyMeta, GeneratedSchema); get_api_signature resolves defineFeature, registerBuilder, parseCall, getOC, definePart and defineAssembly. Then read references/traps.md in this skill.

4. Write the module

One file, <name>.feature.js, anywhere in the workspace except under node_modules, a dot directory or a gitignored path; beside the models that use it is the norm. The suffix is what the editor scans for, and it keeps the module's own stack frames out of the statement's source location. The shape:

import { Feature, defineFeature } from 'fluidcad/sdk';
import { BooleanOps, Primitives, ShapeOps } from 'fluidcad/sdk/kernel';
import { Matrix4, Plane } from 'fluidcad/math';

export class VentGrid extends Feature.with({
  face: { picker: 'face', label: 'Panel face', surface: 'planar' },
  rows: { type: 'integer', display: 'stepper', default: 3, min: 1, max: 50 },
  pitch: { type: 'length', display: 'slider', default: 8, min: 2, max: 40, suffix: 'mm' },
  // …
}, {
  buckets: {
    holeFaces: {},                      // the wall of every hole, row by row
    holeEdges: { label: 'Hole Rims' },  // declared, not filled: the edges of holeFaces
  },
}) {
  static id = 'ventGrid';

  buildTool() {
    const { rows, pitch } = this.values;       // typed: numbers
    const [face] = this.facesOf(this.values.face);
    // Build on the XY plane, sort the faces into buckets there, place with
    // ShapeOps.transformTracking, name the placed images, dispose what you drop.
    this.setBuckets({ /* startFaces, endFaces, sideFaces, internalFaces, startPlane, */ holeFaces });
    return [/* the solids */];
  }
}

export const ventGrid = defineFeature(VentGrid, {
  label: 'Vent grid',
  description: 'A grid of round vent holes through a panel',
  group: 'create',
  operations: ['remove'],
  call: ['face', { rows: 'rows', pitch: 'pitch' /* , … */ }],
  // layout: ['face', { row: ['rows', 'pitch'] }, …], width: 'wide'   — only when the design calls for one
});

Every value the class declares must appear in call (and in the layout, when there is one). A complete module with every control and a layout is the screw hole in api/feature-params; complete modules with named buckets are the gear (api/feature-example-gear) and the bearing seat (api/feature-example-bearing-seat).

The rules that keep it right:

  • Export the builder by name. A default export is skipped by the editor's scan.
  • No constructor, no module-level state, no geometry at module level. The module is evaluated anew on every render and by the editor's scan, so the class is new each time: never instanceof it. The engine compares features by id and values.
  • Read references only through the helpers: facesOf, edgesOf, shapesOf, axisOf, planeOf, frameOf, pointOf, isLocation. The preview hands the feature stand-ins, not the scene's objects.
  • Validate the picks and values the metadata can't, and throw a message that names the feature and the fix (vent grid: the holes (6) must be narrower than the pitch (5)): surface: 'planar' only limits the dialog's picks, never a hand-written call.
  • Build tools on the XY plane (start at z = 0), sort their faces into buckets there, then place them with ShapeOps.transformTracking and name the images it returns.
  • Dispose every intermediate (a cylinder a cut consumed, a shape you moved); never dispose a shape buildTool() returns or one read from a reference.
  • A loop inside buildTool() is fine: the instances come from one statement and one row. The no-loops rule is for models.
  • Raw OpenCascade only inside this.occ(({ oc, track }) => …): construct through the scope's oc, track() every object a method returns, return wrappers made with ShapeFactory.fromShape(raw). Never construct through getOC(), never free a shape the scene holds.
  • Fill every named bucket you declare in setBuckets(), except an xEdges meant to be the edges of xFaces. A misspelt name, a non-list, a face in an edge bucket or a face of a shape you don't return fails the feature's row (gear: setBuckets() 'tipFace' is not a bucket of gear — did you mean tipFaces?).

Describe each named bucket in the feature's docs/ page. A bucket declaration takes no description (one is refused): what a bucket holds belongs in docs/<feature>.md at the workspace root (the folder a package ships), which other authors and the LLM read. Write it with write_file (any file that is not a model or a module renders nothing): for each named bucket, what it holds, in what order (g.tipFaces(i) is tooth i's top land, counting from the face's X direction), and what a user does with it (fillet(0.3, g.tipEdges())). A line comment beside each declaration is for the code's reader; the page is the documentation.

Writing it with the MCP. write_file on a *.feature.js (or any module, or fluidcad.json) never renders the module itself: it re-renders the open model in full, and render carries openModel: true with that model's state and objectErrors. So write the module, then write the test part (which renders and becomes the open model); from then on, every module write reports on the test part. render.state of no-open-model means no model is open yet; render-failed carries the first lines of the error the model hit loading the module (a refused metadata field, a syntax error), and get_compile_error has the whole message with the module's line a moment later.

5. Write a test part that uses it the way a user would

A recognisable part (a panel, a bracket, a PCB plate), built by the FluidCAD skill's rules: imports from every entry it uses (import { ventGrid } from './vent-grid.feature.js'), named dimensions, fully constrained sketches. Exercise what a user will do:

  • every argument as the dialog writes it: a select, radio or text as a plain literal, a multiple: true select as an array literal (finishes: ['deburr'], [] for none);
  • the feature on a picked face written as an accessor (panel.endFaces()), as the dialog would write it;
  • each operation it offers, and .scope(…) when it matters;
  • a repeat() or copy() of the feature, when its use calls for patterns;
  • a fillet or chamfer through one of its named buckets (fillet(0.3, g.tipEdges()), chamfer(0.5, post.boreEdges())), a standard one where it fits (post.endEdges()), and a downstream feature on one of its faces (sketch(p.floorFaces(), …));
  • values at their limits (the smallest count, a value left to its default).

6. Render and check

  1. render.state and objectErrors. Where each failure shows:
    • a refused metadata field, a syntax error in the module, or a call the builder can't read (ventGrid(): 'rows' must be at least 1, got 0) fails the whole model to compile: compile-error on the model's write, render-failed on the module's;
    • buildTool() throwing, returning nothing, or an operation the feature doesn't offer fails its row only: build-error, with the message under objectErrors.
  2. validate every solid the feature made, then screenshot it (a section through a cut feature) and measure the dimensions its values drive: a hole's diameter, a boss's height, a pitch between two instances.
  3. The buckets resolve. Find the feature's scene-object id and index with get_scene_summary, then resolve_selection the expression $obj["<id>"].startEdges() and each named bucket ($obj["<id>"].holeFaces(), ….holeEdges()), scoped to its part, with before set to the index right after the feature: a later fillet or chamfer replaces the edges and faces it touches, so at the model's end those buckets resolve to nothing. The count must be what the design says (a 3 × 5 vent grid: 15 start edges, 15 end edges, 15 hole faces), and the summaries' centres and diameters must sit where the values put them. Zero means the fusion or the cut removed them, or the bucket was left unfilled (a misspelt or wrong-kind name fails the row instead). The synthesized source of a whole named bucket is the bucket itself (g.holeFaces()), which shows the editor will write picks through it.
  4. A value change rebuilds. Change one value in the test part and confirm the geometry follows; render.changes.rebuilt lists the feature's row.
  5. It typechecks under the workspace's jsconfig.json (fluidcad init writes one with checkJs): when you have a shell, npx -p typescript tsc --noEmit -p jsconfig.json in the workspace, expecting no errors. this.values and the builder's arguments are typed by inference; a misspelled option in the test part is an error.
  6. The editor offers it. When you have a shell, GET http://localhost:<port>/api/features/catalog (the port from list_workspaces) lists the feature with no error; an error is what the Custom dropdown's greyed cell says.

7. Iterate

Saving the module's code rebuilds its statements in every model that read it, with no engine restart; with the MCP, the module write re-renders the open model in full and reports on it. Change one thing per write. When a value change misbehaves but a fresh write is right, suspect state kept between renders.

8. Package it, when it should travel

Do this only when the user wants the feature in other projects or for other people; a feature used in its own workspace needs no package. A package is the workspace's own fluidcad.json with a package block; fluidcad publish packs it into one .fluidpkg file and uploads it to the hub (read_doc concepts/packages). Packages reach other projects only through the hub: the archive itself never installs.

  1. The layout. The folders decide what a package exports: every *.feature.js in features/, every *.part.js (or *.fluid.js) in parts/ and every *.assembly.js in assemblies/, nested folders allowed. Move each feature module into features/ with its images (they resolve next to the module, so ./vent-grid.svg keeps working), and a part or assembly that should travel into parts/ or assemblies/; its imports become relative to the folders (import { ventGrid } from '../features/vent-grid.feature.js'). Plain .js helpers can sit in any of the three, never at the root: pack refuses an import that leaves them (outside-layout) and a module in the wrong folder for its suffix (wrong-folder). A test part that should not travel stays outside the three folders, at the root, and imports ./features/vent-grid.feature.js. A package needs at least one part or assembly to be published on the hub; a features-only package still packs, but can't be published.
  2. The block. The name is @<handle>/<name>, where the scope is the user's hub handle: ask them, or run npx fluidcad whoami. With a shell, npx fluidcad package init --name @<handle>/vent-hardware in the workspace writes it: the name and version 0.1.0, and it says what the folders hold (signed in, --name vent-hardware takes their handle and says so). Without one, add it to fluidcad.json with write_file, keeping every other key (engine, unit, materials):
    "package": {
      "name": "@acme/vent-hardware",
      "version": "0.1.0",
      "description": "A vent grid for enclosure panels"
    }
    
    Packages are named @handle/name, each part in lowercase letters, digits and single dashes, starting with a letter. A name without the scope (vent-hardware) is refused, and the scope must be the handle they publish under: fluidcad publish refuses another one. Feature ids stay plain. There is no exports key: a block that has one is refused. Files the package reads. A load() or .font() written in the package's files reads the package's own file once installed (imports/<name>.brep, fonts/Brand.ttf), which pack ships because a part read it; it never reads a file of that name in the project using the package, and a missing one fails naming the package. A file name that comes from that project — a part's Font or STEP-name parameter, a value a user types — must say so: text(label).font(font, { from: 'project' }), load(name, { from: 'project' }). In this workspace both read the same files, so the mistake only shows after install: check every load() and .font() whose name comes from a parameter before you pack.
  3. pack, to check the package without publishing it, with saveAsPath set to an absolute path named as the result's fileName (acme-vent-hardware-0.1.0.fluidpkg), outside the workspace unless the user asked for it there. The engine evaluates every export and builds every part and assembly first; pack-refused carries one sentence naming the file and a details.code (wrong-folder, outside-layout, no-exports, or refused for a name without its scope, two features sharing an id, a missing image, an import from node_modules or another package, a file a part reads from node_modules, outside the workspace or an installed package, a part that fails to build, unsaved editor changes; for a generated definition also an image its schema declares that is missing or outside the workspace, and a minEngine below 0.0.49). Fix that file and pack again.
  4. Report the package name, version, savedTo and what it holds (the result's contents: the features, parts and assemblies by folder). Tell the user how it reaches other projects: only through the hub. npx fluidcad publish, run in the workspace, packs it again and uploads it (it needs a hub handle and publishing rights, and an admin reviews it before it is public); the saved archive is for looking at, not a step before publishing; then, in another project, npx fluidcad install @acme/vent-hardware installs it and a model imports it by that name (import { ventGrid } from '@acme/vent-hardware'). The archive itself doesn't install. To try the package, use its features and models in this workspace. Never publish or install on the user's behalf.
  5. A new version: edit the module, raise package.version (npx fluidcad version minor, or edit the block), and check it with pack again; npx fluidcad publish releases it. An installed version never changes, so a fix to a released version is always a new version.

9. Generated parts and assemblies

The values a feature declares are also the interface of an insertable part and, through Generator.with(), of a sub-assembly made by code. Both are inserted into assemblies with their values by id and edited in the assembly toolbar's Generate Parts dropdown with the feature-style dialog and a live preview of the real result. Read references/generators.md in this skill before writing either; it has the rules, the MCP checks and the traps.

  • Generated part — export const gearPart = definePart(Gear, { label: 'Gear', icon: '../features/icons/gear.png' }) in a *.part.js (a package's parts/). The class is a tool whose every pick is optional: true (the part leaves picks out and builds at its origin). Each frame the class declares (Feature.with(params, { frames: { axis: {} } }), set with this.setFrames({ axis: plane })) becomes a connector of its name: insert(gearPart, { teeth: 18 }).connectors.axis.
  • Generated assembly — a class that extends Generator.with({ … }) with a static id, a synchronous layout(g) (plain JavaScript: g.part(type, { name, inputs, connectors, appearance, material }), .grounded(), .pose(), g.mate(…).flip().limits(…).name(…), g.relation(); it returns occurrence.parts) and a static build(type, inputs, ctx) that reads only its plain-JSON inputs and returns the part's shapes (ctx.detail 'preview' skips drilling and small hardware). export const wardrobe = defineAssembly(WardrobeUnit, { label: 'Wardrobe' }) in an *.assembly.js (a package's assemblies/); the class beside its images in features/.
  • Rules that bite: values only, no picks; inputs and frames plain JSON ([x, y, z], never a Plane); everything a part's geometry depends on in its inputs; rounded numbers so equal parts share a template; a frame on both sides of a joint plus .flip(), so 0 is closed; never keep shapes in module state; generated parts and their joints are read-only rows — change them through the insert's values; no configurations.
  • Verify with a test assembly at the workspace root that inserts the definition the way a user would: render.state and objectErrors (a bad value or a layout throw is a row error at the insert's line; a build throw is on that part's row), get_scene_summary (occurrences, instances by owner, one part row per template with params.generatedBy and its connector rows, the layout's mates and relations — engine-owned, under the occurrence's path — with their sides, limits and flips), screenshot, interfere and measure at the starting poses, a value change that leaves untouched templates fromCache, and pack (images, minEngine 0.0.49 or later). The 'preview' tier runs only in the editor's dialog: say it was not checked unless a browser drove it.

10. Report only what was checked

Report the design (section 2), what you rendered, validated, measured and resolved, and the typecheck and catalog results. Name what you did not check: the dialog and its preview are only seen in the FluidCAD UI, so unless a browser drove them, say "not checked in the dialog" rather than implying it. Tell the user where the feature appears (the toolbar's Custom dropdown, last on the part toolbar) and that a model imports it from the module; a generated part or assembly appears in the assembly toolbar's Generate Parts dropdown and the Insert dialog, and an assembly imports it from its *.part.js / *.assembly.js.

Quick reference: the custom-feature loop

  1. Decide that a feature is warranted, or say what to use instead (section 1).
  2. Design it in CAD terms: tool or modifier, operations, each value as a dialog row, the call, the standard buckets and the named buckets a user will fillet, chamfer or sketch on, kernel or raw OpenCascade (section 2). Show it.
  3. read_doc the custom-feature docs; read references/traps.md.
  4. write_file the *.feature.js module, and docs/<feature>.md describing each named bucket (what it holds, its order).
  5. write_file a recognisable test part that uses it as a user would, with a fillet or chamfer through a named bucket.
  6. render.state, objectErrors, validate, screenshot, measure, resolve_selection on its buckets, named ones included; typecheck and the catalog when a shell is available.
  7. Iterate on the module: each write re-renders the open model (render.openModel).
  8. When it should travel: the modules into features/, parts/ and assemblies/, the package block in fluidcad.json, then pack with saveAsPath (section 8).
  9. For a generated part or assembly: references/generators.md, the defining *.part.js / *.assembly.js, a test assembly that inserts it by id, and its checks (section 9).
  10. Report what was checked, and what was not.

Version History

  • 5b8e897 Current 2026-11-07 13:50

Same Skill Collection

mcp/skills/fluidcad-from-drawing/SKILL.md
mcp/skills/fluidcad-assembly/SKILL.md
mcp/skills/fluidcad/SKILL.md

Metadata

Files
0
Version
5b8e897
Hash
add584a6
Indexed
2026-11-07 13:50

Accueil - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-17 06:38
浙ICP备14020137号-1