# How to Bundle CAD Skills as Plugin Packages: A Complete Guide

> Learn to bundle CAD skills as plugin packages transforming skill sources into versioned artifacts with the bundle.sh automation script. Your complete guide to efficient CAD plugin development.

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

---

**Bundling CAD skills as plugin packages converts human-readable skill sources from the `skills/` directory into versioned, self-contained plugin artifacts under `plugins/cad/` using the [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh) automation script.**

The **text-to-cad** repository distributes CAD functionality to AI agents like Codex and Claude Code through an immutable plugin format. When you bundle CAD skills as plugin packages, you transform editable Python and JavaScript sources into installable, versioned distributions that agents can consume directly from the marketplace.

## Understanding the Plugin Architecture

The repository separates human-editable source code from machine-consumable plugin artifacts using a symlink-based layout defined in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md).

### Skill Sources vs Plugin Packages

**Skill sources** live under `skills/` and contain the raw implementation of CAD capabilities—such as URDF generation or G-code slicing. These files are human-readable and editable, exemplified by [[`skills/urdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md)](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md).

**Plugin packages** reside under `plugins/cad/` and represent the compiled, immutable distribution format. Each package contains:
- Copied skill code under `plugins/cad/skills/`
- Agent-specific manifests ([`.codex-plugin/plugin.json`](https://github.com/earthtojake/text-to-cad/blob/main/.codex-plugin/plugin.json) and [`.claude-plugin/plugin.json`](https://github.com/earthtojake/text-to-cad/blob/main/.claude-plugin/plugin.json))
- A canonical version file injected during bundling

### The Symlink-First Development Model

All runtime artifacts live under the `develop` branch and link to appropriate plugin locations. The bundling process must run **from the `develop` branch** to ensure symlinks resolve to the latest source. This separation preserves a clean boundary between editable source code and generated plugin artifacts.

## Key Files and Directory Structure

According to the text-to-cad source code, these files govern the bundling process:

- **[`skills/urdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md)** – Example skill source documentation and implementation
- **[`plugins/cad/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/plugins/cad/README.md)** – Plugin overview and installation instructions for agents
- **`plugins/cad/VERSION`** – Single source of truth for semantic versioning
- **[`plugins/cad/.codex-plugin/plugin.json`](https://github.com/earthtojake/text-to-cad/blob/main/plugins/cad/.codex-plugin/plugin.json)** – Codex agent manifest (name, version, entry points)
- **[`plugins/cad/.claude-plugin/plugin.json`](https://github.com/earthtojake/text-to-cad/blob/main/plugins/cad/.claude-plugin/plugin.json)** – Claude Code agent manifest
- **[`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh)** – The automation script that generates plugin artifacts
- **[`.github/workflows/test.yml`](https://github.com/earthtojake/text-to-cad/blob/main/.github/workflows/test.yml)** – CI pipeline that validates bundle integrity

## Step-by-Step Bundling Process

Follow these steps to bundle CAD skills as plugin packages for distribution:

1. **Prepare the branch environment**

   Checkout the `develop` branch and ensure the symlink layout is correct:

   ```bash
   git checkout develop
   ./scripts/dev/setup-symlinks.sh --check && ./scripts/dev/setup-symlinks.sh
   ```

2. **Update the version (optional)**

   Edit `plugins/cad/VERSION` if publishing a new release:

   ```bash
   echo "0.4.0" > plugins/cad/VERSION
   ```

3. **Execute the bundling script**

   Run the automation from the repository root:

   ```bash
   ./scripts/bundle/bundle.sh
   ```

   The script performs three critical operations:
   - Copies skill sources from `skills/…` into `plugins/cad/skills/…`
   - Injects the version from `plugins/cad/VERSION` into both Codex and Claude manifests
   - Validates the output layout

4. **Validate the generated plugin**

   Run the check command to verify integrity:

   ```bash
   ./scripts/bundle/bundle.sh --check
   ```

5. **Commit the artifacts**

   The script writes only to the `plugins/cad/` tree. Commit these generated files:

   ```bash
   git add plugins/cad/ && git commit -m "Bundle CAD plugin v$(cat plugins/cad/VERSION)"
   ```

## Version Management and Manifest Generation

The bundling system uses a **single version source** pattern to prevent version drift between agent types. The `plugins/cad/VERSION` file contains the canonical semver string read by [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh) and injected into both [`.codex-plugin/plugin.json`](https://github.com/earthtojake/text-to-cad/blob/main/.codex-plugin/plugin.json) and [`.claude-plugin/plugin.json`](https://github.com/earthtojake/text-to-cad/blob/main/.claude-plugin/plugin.json).

This guarantees that when you bundle CAD skills as plugin packages, the Codex and Claude Code manifests remain synchronized. The agent-agnostic design means the same plugin installs seamlessly in either environment without code duplication.

## CI Verification and Automated Checks

The repository enforces bundle integrity through GitHub Actions. The workflow defined in [`.github/workflows/test.yml`](https://github.com/earthtojake/text-to-cad/blob/main/.github/workflows/test.yml) automatically executes `scripts/bundle/bundle.sh --check` on every pull request, ensuring that:

- The plugin layout stays consistent with source changes
- Version stamps match the `VERSION` file
- No manual edits bypass the bundling script

## Summary

- **Bundle CAD skills as plugin packages** using [`./scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/./scripts/bundle/bundle.sh) to convert `skills/` sources into `plugins/cad/` artifacts
- Maintain the **single version source** in `plugins/cad/VERSION` to keep Codex and Claude manifests synchronized
- Always run bundling from the **`develop` branch** to ensure symlinks resolve correctly
- Validate bundles locally with `--check` before committing; CI enforces this automatically
- Generated plugins install via `codex plugin add cad@text-to-cad` or `claude plugin install cad@text-to-cad`

## Frequently Asked Questions

### What is the difference between a skill and a plugin package?

A **skill** is the editable source code under `skills/` that implements a specific CAD capability. A **plugin package** is the compiled, versioned distribution under `plugins/cad/` that agents install, containing immutable copies of the skill code plus agent-specific manifests.

### Why must I bundle from the `develop` branch?

The repository uses a symlink layout where runtime artifacts under `develop` point to source locations. Bundling from `develop` ensures [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh) resolves these symlinks to the latest source files, preventing stale code from entering the plugin package.

### How does the bundling script handle versioning?

The script reads `plugins/cad/VERSION` as the single source of truth and injects this value into both [`.codex-plugin/plugin.json`](https://github.com/earthtojake/text-to-cad/blob/main/.codex-plugin/plugin.json) and [`.claude-plugin/plugin.json`](https://github.com/earthtojake/text-to-cad/blob/main/.claude-plugin/plugin.json). This prevents version drift between different agent types and ensures consistent versioning across all distribution channels.

### Can I install the bundled plugin locally without publishing?

Yes. After running [`./scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/./scripts/bundle/bundle.sh), the generated files in `plugins/cad/` represent the complete plugin package. You can point your local Codex or Claude Code installation to this directory, or follow the installation commands in [`plugins/cad/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/plugins/cad/README.md) to load the plugin directly from the filesystem.