Articraft Authoring

Use this skill when the user asks Codex to create, edit, fix, improve, check, or finalize an Articraft asset or record.

Core Rule

There are three supported Articraft authoring modes. Choose the mode from the user's request before creating a record.

• Use native Articraft generation when the user needs Articraft-managed run metadata, cost accounting, turn counts, or the full agent trajectory. This path requires the relevant provider API key.
• Use no-key Codex generation when the user wants Codex access without provider API keys. This path uses --provider codex-cli inside Articraft's internal harness, so Articraft still owns the loop, tools, compile feedback, turn counts, compile-attempt counts, record persistence, and trajectory.
• Use external Codex authoring only when the user explicitly asks Codex to manually edit model.py outside the internal harness. This path creates an external-agent record and intentionally has no Articraft internal trace.

Never manually create record directories, invent record metadata, copy record folders, write traces, or bypass the CLI.

Read the repository contract before external authoring:

sed -n '1,220p' EXTERNAL_AGENT_DATA.md

Also read the core quality requirements before writing geometry:

agent/prompts/sections/designer_common.md
agent/prompts/sections/link_naming.md

Use SDK docs and examples while authoring:

sdk/_docs/
sdk/_examples/

Setup

From the Articraft repo root:

uv sync --group dev
uv run articraft init

If the user wants a specific data folder, pass --data-dir or set ARTICRAFT_DATA_DIR.

Create A New Record

For a full Articraft run with cost, turn count, and trajectory, use native generation:

uv run articraft generate "<prompt>"

For no-key Codex generation with Articraft loop parity, use the Codex CLI provider:

uv run articraft generate --provider codex-cli --model <codex-model-id> "<prompt>"

For image-conditioned no-key Codex generation:

uv run articraft generate --provider codex-cli --model <codex-model-id> --image <reference-image> "<prompt>"

For external Codex drafting, create the record through the external CLI and identify Codex:

uv run articraft external init --agent codex "<prompt>"

The command prints record_id and record_dir. Edit only that generated record's active revision.

Edit An Existing Record

Fork an existing record; do not manually copy record folders:

uv run articraft fork <record-id> "<edit request>"

For no-key Codex edits with Articraft loop parity:

uv run articraft fork --provider codex-cli --model <codex-model-id> <record-id> "<edit request>"

Authoring Standard

Build a realistic articulated asset with:

• connected, non-floating structure
• meaningful user-facing articulation
• semantic link names
• visible mechanisms and realistic materials
• prompt-specific checks in run_tests()
• no unintentional intersections or disconnected parts

Prefer relevant SDK helpers, CadQuery geometry, lofts, sweeps, booleans, mesh helpers, colors, and materials over boxy placeholder geometry.

Validation Loop

For native/API and no-key Codex provider runs, the harness calls compile_model during generation. Recompile or inspect after generation when needed:

uv run articraft compile <record-id>

For external drafts, run the same one-record compile command during development, update the active model.py, and repeat until it passes.

Finalize

Finalize external records to upsert records_manifest.jsonl; pass a category only when the user asks for one:

uv run articraft external finalize <record-id>
uv run articraft external finalize <record-id> --category-slug <slug>

Preserve creator.mode=external_agent, creator.agent=codex, and creator.trace_available=false.

Articraft Local Library

Use this skill when the user asks about Articraft record authoring, categories, local data validation, manifest updates, or sharing a data folder.

Commands

From the repo root, prefer uv run articraft ... product commands and just shortcuts.

Check current state:

uv run articraft status
uv run articraft library status

Validate a local data folder:

uv run articraft library check --require-records

Rebuild the manifest:

uv run articraft library rebuild-manifest

List records:

uv run articraft library list

Assign a category:

uv run articraft library set-category <record-id> <category_slug>

Data Root

The default data root is the gitignored <repo-root>/data. To use another local/exportable folder, pass --data-dir or set:

export ARTICRAFT_DATA_DIR=/path/to/articraft-data

The data root contains top-level records/, categories/, records_manifest.jsonl, system_prompts/, and cache/.

Contribution Rules

Data authoring work should follow CONTRIBUTING.md and EXTERNAL_AGENT_DATA.md.

Before sharing a data folder, run the relevant checks and report exact commands:

uv run articraft library check --require-records
just smoke-tests

If viewer behavior or asset quality is part of the change, inspect records with the local viewer and include screenshots or notes when useful.

Articraft Viewer

Use this skill when the user asks to compile records, browse generated objects, inspect articulation, start the viewer, or work on viewer/api or viewer/web.

Compile Records

For one record:

uv run articraft compile <record_id>

Start The Viewer

Built viewer flow:

just viewer

Development viewer flow with API and Vite:

just viewer-dev

API only:

uv run uvicorn viewer.api.app:app --reload --host 127.0.0.1 --port 8765

Frontend-only commands:

npm --prefix viewer/web run dev
npm --prefix viewer/web run typecheck
npm --prefix viewer/web run lint
npm --prefix viewer/web run build

Visual QA

When inspecting an asset, verify:

• all primary parts are visible and connected
• articulations move the intended parts
• no major unintended overlap or floating geometry is visible
• link names and controls are semantic
• materials and colors match the object prompt
• history/lineage is preserved for forked records

If the viewer or frontend code changed, run the relevant frontend checks:

npm --prefix viewer/web run typecheck
npm --prefix viewer/web run lint

If API behavior changed, run focused viewer/API tests:

uv run --group dev pytest -q tests/viewer