How to Install Text-to-CAD Skills Locally for AI Agents: Complete Setup Guide

You can install text-to-cad skills locally for AI agents using either the Skills CLI (npx skills install earthtojake/text-to-cad) for production environments or the scripts/install/install-skills.sh symlink installer for development workflows.

The earthtojake/text-to-cad repository provides self-contained skills (e.g., cad, urdf, gcode) under the skills/ directory that enable AI agents to generate 3D models and robot description files. To integrate these capabilities into your local agent runtime, you must expose these packages to the agent's plugin system. This guide covers both the npm-based installation method and the symlink-based approach for local development.

Installation Methods Overview

The repository supports two distinct pathways for making skills available to AI agents:

• Skills CLI (npm) – Installs a pre-built plugin package into node_modules/@text-to-cad/... via the agent's own plugin manager. Ideal for production deployments where you want version-locked dependencies.
• Local Symlink Installer – Creates per-skill symlinks from the repository's skills/ folder into the agent's personal skill directory. This method reflects code changes instantly without rebuilding packages, making it optimal for development and testing.

Installing via Skills CLI (Production)

For agents that support npm-based plugins, use the Skills CLI to install the pre-built package directly from the repository.

npx skills install earthtojake/text-to-cad

This command downloads and registers the plugin with the agent's runtime, placing files in node_modules/@text-to-cad/.... This approach requires no local repository clone and handles dependency resolution automatically.

Installing via Local Symlinks (Development)

The symlink installer is implemented in scripts/install/install-skills.sh. This Bash script discovers available skills, resolves agent-specific destination directories, and creates symbolic links for each skill package.

How the Symlink Installer Works

The script executes a five-step workflow defined in scripts/install/install-skills.sh:

1. Discover skills – Executes scripts/utils/list-skills.sh to collect all SKILL_IDS from the skills/ directory.
2. Resolve target directories – The agent_destination function maps logical agent names (codex, claude, gemini, universal, project) to concrete filesystem paths.
3. Prepare the destination – If a whole-directory symlink exists pointing at the repository's skills/ folder, it is safely replaced with per-skill directories to avoid conflicts.
4. Create per-skill symlinks – For every skill in SKILL_IDS, creates a symlink at <destination>/<skill> pointing to <repo-root>/skills/<skill>. Existing correct symlinks remain untouched; mismatched symlinks are replaced.
5. Dry-run support – With --dry-run, the script prints intended ln -s commands without modifying the filesystem.

Supported Agent Destinations

The installer recognizes the following agent directory mappings:

• codex → ~/.codex/skills
• claude → ~/.claude/skills
• gemini → $HOME/.gemini/skills
• universal → ${XDG_CONFIG_HOME}/agents/skills
• project → .agents/skills (repository-local)

Using the Symlink Installer Script

Navigate to the repository root before executing installation commands.

Install for the Default Agent (Codex)

scripts/install/install-skills.sh

This creates symlinks in ~/.codex/skills/ for every package found in skills/.

Install for Specific Agents

Use the --agent flag (repeatable) to target specific runtimes:

scripts/install/install-skills.sh --agent claude --agent gemini

Preview Changes with Dry-Run

Verify what the script will do before execution:

scripts/install/install-skills.sh --dry-run --agent claude --agent universal

This outputs the intended symlink commands without creating them.

Install for All Supported Agents

scripts/install/install-skills.sh --all

This populates skill directories for Codex, Claude, Gemini, Universal, and the project-local agent simultaneously.

List Resolved Destinations

To verify where each agent expects skill files:

scripts/install/install-skills.sh --list-agents

Output format:

codex       /home/user/.codex/skills
claude      /home/user/.claude/skills
gemini      /home/user/.gemini/skills
universal   /home/user/.config/agents/skills
project     /path/to/repo/.agents/skills

Key Implementation Files

Understanding these source files helps troubleshoot installation issues:

File	Purpose
scripts/install/install-skills.sh	Core installation logic handling symlink creation and agent directory resolution.
scripts/utils/list-skills.sh	Utility script that enumerates skill identifiers by scanning the skills/ directory.
skills/	Directory containing standalone skill packages (e.g., cad/, urdf/, gcode/).
AGENTS.md	Repository documentation covering branching strategies, symlink behaviors, and agent-specific workflows.

Summary

• Two installation methods exist: The npx skills install CLI for production stability, and install-skills.sh for local development.
• The symlink installer (scripts/install/install-skills.sh) creates per-skill symlinks in agent-specific directories, enabling instant reflection of code changes.
• Supported agents include Codex, Claude, Gemini, Universal, and a project-local option, with destinations resolving to ~/.codex/skills, ~/.claude/skills, ~/.gemini/skills, ${XDG_CONFIG_HOME}/agents/skills, and .agents/skills respectively.
• Use --dry-run to preview symlink operations before execution, and --list-agents to verify destination paths.

Frequently Asked Questions

Can I install text-to-cad skills for multiple agents simultaneously?

Yes. Run scripts/install/install-skills.sh --agent codex --agent claude --agent gemini to create symlinks for specific agents, or use scripts/install/install-skills.sh --all to install for every supported agent at once. The script safely handles existing symlinks and only modifies incorrect or missing links.

What is the difference between the Skills CLI and symlink installation methods?

The Skills CLI (npx skills install earthtojake/text-to-cad) installs a pre-built npm package into node_modules, ideal for production where you want stable, version-controlled dependencies. The symlink method points the agent directly at your local repository's skills/ directory, allowing immediate testing of code changes without repackaging. Use symlinks for development and the CLI for deployment.

How do I verify where my agent expects skill files?

Execute scripts/install/install-skills.sh --list-agents to display the resolved filesystem paths for each supported agent. This outputs the absolute paths (e.g., /home/user/.codex/skills, /home/user/.claude/skills) where the installer will create symlinks, confirming the agent's configuration matches your expectations.

Will modifying the repository affect installed skills?

When using the symlink installer, yes. Changes to files in the repository's skills/ directory are immediately visible to the agent because the installation creates symbolic links rather than copies. This live-reload behavior accelerates development but requires caution; use the Skills CLI method instead if you need immutable, version-locked skill packages.

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