Files
make-cad/docs/skill/references

Skill Documentation Structure

This directory is the task-routed skill layer. It sits between the SDK's generated

docs/skill/
  domains/       stable, reusable capability modules
  workflows/     goal-oriented compositions of domains
  discipline/    mechanical modeling knowledge and invariants

Layering

SKILL.md (router: load order, routing, execution discipline)
→ workflows/<scenario>.md        what to run, in what order
→ domains/<capability>.md        capability boundaries and API groups
→ discipline/<topic>.md          why: modeling reasoning and invariants
→ docs/api|stdlib|core/          exact signatures (auto-generated)

Load top-down and only what the current task triggers. No task reads the whole API index up front.

Domains

Domain Owns
requirement-refinement request → brief (dimensions, units, datums, validation targets)
part-modeling single-solid parts: primitives, profiles, features, booleans, transforms
sketch-and-features declarative constrained sketches and promotion
assembly-and-product parts, placements, connectors, constraints, @part/@assemble, cache, .scadpkg
standard-parts stdlib gears, ring gears, racks, cycloidal discs, bearings
step-inspection STEP/BREP evidence, comparison, reconstruction evaluation
drawing-inspection vector-PDF coordinates and dimensions, model-section measurements, independent evidence validation
export-and-translation STEP/STL/OBJ/MJCF export, FreeCAD/Fusion/SolidWorks translation
addon-development third-party addon authoring and management: sca CLI, sca-addon.toml descriptor, runtime probes, addon SKILL.md requirements

Cross-cutting capabilities — QL grounding, semantic tags, GraphSession replay, units/tolerances, incremental validation — are not routing targets; each workflow pulls them in as conditions require. Verified QL selection patterns for operation outputs (extrude-family slots, boolean seam curves, seam fillets) live in ql-playbook.md. The .scadpkg consumer-facing format spec (member layout, interface.* tag channel, minimal readers for addon exporters) lives in scadpkg-format.md.

Workflows

Workflow Scenario
single-part-modeling one physical part from brief to validated solid — sketch tier by default, std parts first
assembly-product-build multi-part product or mechanism with connectors/constraints and package capture; stdlib gears/bearings live here
step-reconstruction editable rebuild from a target STEP with tiered acceptance
drawing-reconstruction editable rebuild from vector-PDF dimensions with stage checks and independent drawing/model/output acceptance
export-and-translation downstream formats from a validated package

Each workflow states: goal/scope, task decomposition (required/optional domains, artifacts, validation gates, repair routes), ordered steps with the domain/discipline/API references to load, failure routes, and deliverables. single-part-modeling is additionally role-structured: five roles (requirement confirmer → master planner → verifier planner ⇄ detail modeling planner & builder → exporter), with Roles 3 and 4 looping per stage before the next stage is allowed. Each role owns a disk artifact and an exit gate; per-harness host bindings (interactive ask, TODO/plan tool, REPL-or-script hypothesis loop, mandatory isolated image review) are declared inside the workflow file as conditional blocks compiled per target by tools/skillbuild.py (targets declared in skillproj.toml).

Discipline

Modeling reasoning and invariants, independent of any single API: mechanical-modeling (construction strategy), requirement-and-cad-brief (input precedence, drawings), datums-and-coordinate-systems, feature-ordering (operation order and boolean tool geometry), assembly-positioning (mating/motion intent), geometric-validation (validity vs volume, incremental grounding, spec-driven measurement), failure-and-repair (failure classes and the repair loop), manufacturing-boundaries (defaults and what geometry never proves).

Authoring rules

  • Domain files say what a capability owns, when to use it, when to route elsewhere, and which API pages to read — they do not restate signatures.
  • Workflow files compose domains; they never duplicate discipline content.
  • Discipline files state reasoning and invariants; they avoid CLI- or tool-specific detail that belongs in domains/workflows.
  • Every references/... path written here must exist in the packaged skill.
  • Reading an API page is an action with an output: before the first call of any API, note its signature, return type, and documented failure modes — one line each in the working notes. A method name absent from the page does not exist, however plausible it looks. Non-SDK dependencies (Gmsh, CalculiX, VTK, FreeCAD scripting) are not covered by SDK pages: check their own documentation before the first call.