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

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 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.

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).

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 and .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 – Example skill source documentation and implementation
• 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 – Codex agent manifest (name, version, entry points)
• plugins/cad/.claude-plugin/plugin.json – Claude Code agent manifest
• scripts/bundle/bundle.sh – The automation script that generates plugin artifacts
• .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:

   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:

   echo "0.4.0" > plugins/cad/VERSION

3. Execute the bundling script

   Run the automation from the repository root:

   ./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:

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

5. Commit the artifacts

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

   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 and injected into both .codex-plugin/plugin.json and .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 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 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 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 and .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, 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 to load the plugin directly from the filesystem.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}