Skill instructions
duc6 KB
View saved version →
---
name: duc
description: "Use this skill whenever a DUC drawing (`.duc` file) needs to be read, written, searched, created, inspected, or manipulated programmatically with the Python `ducpy` library. This includes constructing elements, styles, layers, blocks, and states with fluent builders; querying the relational schema through `DucSQL`; streaming external-file or version payloads; and validating coordinate placement or drawing relationships."
metadata:
version: "1.3.0"
---
# DUC Core Canvas Library Skill
The `ducpy` Python library provides a fast, developer-friendly interface to read, write, search, and manipulate `.duc` project-state files. Under the hood, a current `.duc` file is a **gzip-compressed SQLite database**.
This skill deliberately stays compact. Detailed API signatures, concepts, schema tables, and worked examples are bundled directly inside the relative `./docs/`, `./docs-ducpy/`, and `./docs-sql/` folders of this skill.
---
### Source-of-Truth Hierarchy
Agents must adhere strictly to this priority order:
1. **Runtime introspection of the installed `ducpy` package**
2. **Bundled `ducpy` API reference** (`./docs-ducpy/llms.txt`, `./docs-ducpy/*.md`)
3. **Bundled SQLite schema reference** (`./docs-sql/schema.md`, `./docs-sql/llms.txt`)
4. **Bundled DUC concept guides** (`./docs/llms.txt`, `./docs/*.md`)
5. **Existing worked examples** (`./docs-ducpy/examples.md`)
> [!IMPORTANT]
> **Runtime Introspection & Verification Rule**
> Runtime introspection remains #1 because the installed package version might differ.
> **Rule**: *Never invent a `ducpy` method, parameter, return type, schema column, or builder stage. Retrieve the version-matched reference from the local docs or runtime introspection before generating implementation code.*
> [!TIP]
> **Runtime Environment for Testing & Introspection**
> Use `scopture run-python <file.duc>` via the CLI (or `run_python_code` via MCP) to test code and introspect `ducpy` against a real drawing. It has the full engineering stack pre-installed and is read-only unless `update_drawing(...)` is called. Don't set up a local Python environment.
---
## Key Design & Code Standards
* **Coordinate System & Units**: `x` and `y` are the element's top-left canvas position. Positive X extends rightward and positive Y extends downward. Linear, arrow, and freedraw points are local to that element origin. Angles are radians, and coordinates and dimensions use the element's declared scope.
* **Current File I/O Contract**: `parse_duc()` accepts a filesystem path and returns recursively wrapped `DucData` dictionaries with flattened snake_case fields. `serialize_duc()` writes a `.duc` file and returns its path; it does not return drawing bytes.
* **In-Place Mutation**: Use `duc.mutate_element()` for builder-created `ElementWrapper` or dataclass objects. Parsed `DucData` elements are dictionaries and should be edited through their existing fields. Never destroy and recreate an element merely to update it, because doing so can lose IDs, memberships, bindings, and other relationships.
* **Binding Preservation**: Preserve existing element IDs, `bound_elements`, group/region/block memberships, `frame_id`, `layer_id`, and instance relationships during edits.
* **Strict Builder Methods**: Methods are stage-specific. Confirm the active builder class and installed-version signature before invocation.
* **Modular Model Elements (Components & Assemblies)**: When creating complex 3D models or assemblies, do not write a single monolithic script. Break the design into modular Model Elements:
- **Parameters**: Elements defining dimensions, configuration values, or domain rules.
- **Component Geometry**: Elements providing reusable geometric parts or helper functions without calling `emit_output(...)`.
- **Assembly Root**: A top-level Model Element that imports components using `from duc_model.<element_id> import ...`, combines them into an assembly, and calls `emit_output(..., kind="parame
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 86 — file references are metadata, not package contents.
scopture14.9 KB
View saved version →
---
name: scopture
description: "Use this skill whenever the user wants to inspect, search, create, edit, query, render, or update a live Scopture canvas or remote `.duc` drawing through the Scopture MCP server. This includes 2D geometry, parametric 3D models, IFC/BIM, DXF/DWG, Typst documents, PDFs, whole-drawing python runtime, SQLite operations, active-canvas context, screenshots, and visual QA. Trigger for Scopture, an active canvas, a remote drawing, or Scopture MCP drawing tools; do not trigger for an unrelated generic PDF, image, or database task."
metadata:
version: "1.3.0"
---
# Scopture Canvas Creation, Search, and Manipulation
Scopture is an interactive, multi-agent CAD pipeline that turns natural-language requests into validated operations synchronized with a live canvas. Scopture is the application; DUC (`.duc`) is its **gzip-compressed SQLite** project-state format.
This skill focuses strictly on **live canvas synchronization**, using the **Scopture MCP server tools**, writing scripts within the current sandbox environment, applying **premium canvas design standards**, and executing the **Visual QA verification loop**.
> For reference: Scopture is the app; Duc (.duc) is the data format and core library used by the app.
> [!IMPORTANT]
> **Code Writing API Reference**
> To handle the .duc file or related syntax, refer to the **duc skill** (and its bundled `./docs/` folder).
---
## Drawing-Level Python Runtime Environment
Scopture provides a full Python runtime environment that operates against the **drawing as a whole**. It is **not bound or scoped to any individual element**.
* **Whole-Drawing Operations**: The runtime is not limited to an isolated element or an embedded script container. Code executes with holistic visibility over the entire drawing, able to inspect elements, compute canvas-wide layouts, coordinate alignments, manage layers and groups, and orchestrate complex multi-element assemblies (e.g., schematics, floor plans, structural grids, or multi-view mechanical drawings).
* **Engineering & Scientific Stack**: Use the maintained [Python Sandbox reference](./docs/automation/python-sandbox) for the shared Python 3.12 capability map, output types and embedded helpers. Desktop prefers its managed sandbox even for remote drawings; browser/mobile require an authorized cloud worker. Installed packages do not bypass network/process guards or establish physical validation. Keep reusable geometry in one Model Element and import it into individual studies.
* **Unified Batch Generation**: A single Python execution can generate, reposition, or update dozens of elements, create layers, instantiate blocks, and update global states in one unified patch.
* **Execution Surfaces**: This drawing-level runtime environment can be invoked via the Scopture MCP server (`run_python_code`) against an active live canvas, or headlessly via the CLI (`scopture run-python`) against local or remote `.duc` drawings. Both surfaces are read-only by default and only modify drawing state if `update_drawing(patch)` is explicitly called; use them directly to test code against the drawing instead of setting up a local Python environment.
---
## Choosing a Geometry Engine
Choose by what the output is for, not only by the object's category. Use the live `run_python_code` tool description for the exact output contract and helper calls.
* **IFC (`ifcopenshell`)**: The result is a building or infrastructure element that needs BIM semantics: walls, slabs, structural frames, doors, windows, building MEP (ducts, pipes, conduit, panels).
* **`build123d` (default)**: Manufactured or discrete 3D geometry: parts, brackets, assemblies, enclosures, robotics, tooling, electrical hardware such as housings and mounts.
* **Mixed cases**: Equipment or fittings inside a building follow the deliverable. Use IFC if it must appear in the building model, `build123d` if it is a part to be made. If unclear, ask the user.
* **`ezdxf`**: Only when DXF its
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 15 — file references are metadata, not package contents.
scopture-cli9.65 KB
View saved version →
---
name: scopture-cli
description: "Inspect, query, test, mutate, diff, render, and export Scopture/DUC (`.duc`) drawings from the terminal with the `scopture` CLI. Use whenever the user has a local `.duc` file or remote drawing and wants to see what's in it, find or filter elements, run read-only or mutative SQL, test Python code or mutate drawing state/elements via the Python sandbox, compare two versions, render a preview image, extract embedded STEP/IFC files, export to STEP/DXF, review a drawing's charter or issues, or open it in the desktop app, even if they never mention the CLI. For understanding Scopture canvas standards specifically use the `scopture` skill; for writing `ducpy` code or adjacent logic to the `.duc` use the `duc` skill."
metadata:
version: "1.3.0"
---
# Scopture CLI
The `scopture` CLI ships with the Scopture desktop app. It works on local `.duc` files (gzip-compressed SQLite) and on remote drawings. It is built for shell pipelines: it inspects, queries, mutates, diffs, renders, and exports.
## Before you start
1. Run `scopture --version`. If it isn't found, tell the user to install the Scopture app via `https://site.scopture.com/download`, and offer the `duc` skill as a way to read the file without the CLI.
2. Run `scopture <command> --help` before using any flag not shown below. Flags change; `--help` is authoritative.
3. Pick an output mode: `--raw` for piping into `jq`/`grep`/`head`, `--json` when you need an explicit `{"success": true, "data": ...}` envelope.
## Side effects
- **Read-only:** `ls`, `cat`, `elements`, `run-sql` (default read-only), `run-python` (read-only by default; only mutates if `update_drawing(...)` is called), `diff`, `files list`, `charter get`, `issues list`, `drawing get`, `auth status`, `ps`, `desktop status`.
- **Mutates drawing state:**
- `charter rename <target> <name>`: changes the stored drawing name (charter title) locally or remotely. For a local `.duc`, the disk filename stays the same; remote renames require drawing edit access.
- `update-drawing <drawing-id> <patch.json|->`: submits complete records as an incremental remote patch. Existing IDs replace records, new IDs add records, and omitted records remain. Use `--no-wait` to return the job ID immediately.
- `run-python` (only when `update_drawing(patch)` is called): modifies drawing elements and atomically re-compresses local `.duc` files or commits remote drawing changes. Without calling `update_drawing(...)`, it is completely read-only and safe for testing scripts.
- `run-sql --mutate`: executes mutative SQL statements directly, persisting changes to local `.duc` files or remote drawings.
- **Writes a file:** `render`, `export`, `files extract`. Direct output with `-o` to a scratch or outputs directory, never over the user's source drawing.
- **Changes the user's screen:** `scopture <file>`, `open`, `desktop focus`. Run these only when the user asks to open or show something. For inspection and background scripts, use the headless commands.
## Inspect
Drawings can hold thousands of elements. Never print a full `cat` into the conversation; start with `ls` for the shape of the drawing, then narrow.
```bash
scopture ls model.duc # tabular overview
scopture cat model.duc | grep -i motor | head # NDJSON stream, one element per line
scopture elements list model.duc --element-type model --search "bracket"
scopture elements get model.duc <element-id> # full geometry and parametric code
```
## Query & Mutate SQL (`run-sql`)
Discover the schema before writing queries rather than guessing column names:
```bash
# Read-only query (default)
scopture run-sql model.duc "SELECT name FROM sqlite_master WHERE type='table'"
scopture run-sql model.duc "SELECT id, element_type, label FROM elements LIMIT 10"
cat query.sql | scopture run-sql model.duc - --raw | jq . # query from stdin
# Mutative SQL (--mutate flag)
scopture run-sql model.duc "UPDATE elements SET label = 'Front BracPreview of the first 4,000 characters. Read full instructions →