# How to Contribute to text-to-CAD: A Complete Guide for Developers

> Learn how to contribute to text-to-CAD. Follow our guide to set up your environment, link skills, and submit pull requests to this exciting open-source project.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-08-02

---

**Contributing to text-to-CAD requires branching from the `develop` branch, setting up a Python 3.12 virtual environment, linking skills to your local agent via [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh), and opening pull requests against `develop` rather than `main`.**

The text-to-CAD repository by earthtojake is organized as a workbench for CAD-related agent skills. Contributions follow a strict workflow that keeps the `develop` branch as the active development line while reserving `main` for publish-only releases. This guide covers the repository architecture, setup procedures, and validation steps needed to submit successful contributions.

## Repository Architecture

The codebase is divided into distinct areas, each serving a specific purpose in the agent skill ecosystem.

**Skills** house individual agent capabilities for CAD generation, URDF, SDF, and more. Each skill lives under `skills/<skill>/` and contains a [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) instruction file plus a `references/` folder for documentation.

**Packages** contain shared Python and JavaScript helpers used by multiple skills, such as `cadpy` and `cadpy_metadata`. These live in `packages/` and are built into each skill's runtime.

**Viewer** powers the `$cad-viewer` skill through an editable CAD Viewer application located in `viewer/`.

**Models** store fixture and generated CAD/robot artifacts (STEP, STL, GLB, etc.) under `models/`, with access enforced by a file-policy.

**Scripts** provide repo-wide utilities for installation, testing, bundling, and release in `scripts/`.

**Docs** contain the public documentation site source at `docs/`.

**Tests** include unit and integration tests for skills, packages, and the viewer in `tests/`.

## Branch Strategy and Policies

According to [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md), all feature work branches from `develop` and targets `develop` in pull requests. The `main` branch contains only generated production outputs with no symlinks and is never the target of direct commits. Contributors must never bump the `VERSION` file directly, as releases are performed via the GitHub Release workflow by maintainers only.

## Contribution Workflow

Follow these steps to set up your environment and submit changes.

### 1. Create a Local Checkout on `develop`

Start by cloning the repository and creating a feature branch from `develop`:

```bash
git clone --branch develop https://github.com/earthtojake/text-to-cad.git
cd text-to-cad
git switch -c my-feature

```

### 2. Set Up the Python Environment

The project requires Python 3.12. Create a virtual environment and install development dependencies:

```bash
python3.12 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install -r requirements-dev.txt

```

The dev requirements automatically pull source packages from `packages/`.

### 3. Install Viewer Dependencies (Optional)

If you are working on the CAD Viewer, install Node.js dependencies:

```bash
npm --prefix viewer install

```

### 4. Link Skills Into Your Agent

Run the install script to create symlinks that allow your local agent to see skills without copying files:

```bash
scripts/install/install-skills.sh --agent codex

```

This creates one symlink per skill. Supported agents include `codex` and other compatible platforms.

### 5. Run Skills and Tests

Execute a specific skill CLI:

```bash
.venv/skills/cad/bin/python skills/cad/scripts/step --help

```

Run Python unit tests:

```bash
./.venv/bin/python -m unittest tests/python/skills/urdf/test_cli.py

```

### 6. Validate Your Changes

Use the smallest applicable check before running the full suite:

```bash

# Verify symlink layout

scripts/dev/setup-symlinks.sh --check

# Run all repository tests

scripts/test/test.sh

# Run viewer unit tests

npm --prefix viewer run test

```

### 7. Open a Pull Request

Target the `develop` branch. The CI pipeline performs the following checks:

- Verifies symlink layout integrity
- Bundles generated outputs via `scripts/bundle/bundle.sh --check`
- Runs the complete test suite
- Validates the file-policy for `models/`

When all checks pass, a maintainer will merge into `develop`.

## Adding a New CAD Skill

To create a new skill, establish the directory structure and required files:

```bash

# Create skill directory

mkdir -p skills/my-new-cad

# Add the instruction file

cat > skills/my-new-cad/SKILL.md <<'EOF'
---
name: my-new-cad
description: Example skill that demonstrates contribution steps.
---

# My New CAD Skill

...
EOF

# Add reference documentation

mkdir -p skills/my-new-cad/references
touch skills/my-new-cad/references/overview.md

```

Each skill must include a [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) with YAML frontmatter defining the name and description, plus a `references/` folder for supporting documentation.

## Running Full CI Checks Locally

Before submitting, replicate the CI validation:

```bash

# Verify symlink layout matches AGENTS.md requirements

scripts/dev/setup-symlinks.sh --check

# Run all repository tests

scripts/test/test.sh

# Check generated outputs and bundling

scripts/bundle/bundle.sh --clean
scripts/bundle/bundle.sh --check

```

## Key Files for Contributors

- **[`README.md`](https://github.com/earthtojake/text-to-cad/blob/main/README.md)** - High-level project overview, skill table, and install commands
- **[`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md)** - Full contributor guide covering checkout, environment setup, linking, and testing
- **[`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md)** - Repository-wide rules about branch policies and symlink layout requirements
- **`skills/<skill>/SKILL.md`** - Canonical instruction file for each skill (e.g., [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md))
- **`packages/*/README.md`** - Documentation for shared packages (e.g., [`packages/cadpy/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/README.md))
- **[`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh)** - Installer that creates symlinks for local agents
- **[`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh)** - Bundles generated production outputs and validates them
- **`tests/python/`** - Unit tests for skills and packages

## Summary

- **Branch from `develop`** - Never target `main` directly; it contains only generated production outputs
- **Use Python 3.12** - Create a virtual environment and install [`requirements-dev.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements-dev.txt) for dependencies
- **Link skills locally** - Run [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh) to create symlinks for agent testing
- **Validate before PRs** - Check symlinks, run [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh), and verify bundling
- **Follow the file structure** - Place new skills in `skills/<name>/` with [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) and `references/` folder
- **Don't modify VERSION** - Releases are handled automatically by maintainers via GitHub workflows

## Frequently Asked Questions

### What Python version does text-to-CAD require?

The repository requires **Python 3.12** specifically. Set up your environment using `python3.12 -m venv .venv` before installing dependencies from [`requirements-dev.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements-dev.txt). The development requirements pull source packages from the `packages/` directory automatically.

### Why can't I commit directly to the `main` branch?

The `main` branch contains only generated production outputs with no symlinks and is reserved for publish-only releases. As specified in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md), all development work must branch from and target the `develop` branch. This separation ensures the `main` branch always represents stable, bundled artifacts while `develop` remains the active integration line.

### How do I test my skill changes without copying files?

Use the [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh) script with the `--agent` flag (e.g., `--agent codex`) to create symlinks between the repository skills and your local agent environment. This allows the agent to reference the latest code directly from `skills/` without file duplication, enabling real-time testing of modifications.

### What checks run in the CI pipeline?

The CI pipeline validates symlink layout via `scripts/dev/setup-symlinks.sh --check`, bundles generated outputs using `scripts/bundle/bundle.sh --check`, runs the full test suite with [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh), and enforces the file-policy for the `models/` directory. These checks ensure repository integrity before merging into `develop`.