# How Agent Instruction Sets Are Organized in text-to-cad

> Discover how text-to-cad organizes agent instruction sets as self-contained skills in the skills directory. Learn about SKILL.md files and the cadgen runtime.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: internals
- Published: 2026-09-11

---

**The text-to-cad repository structures agent instruction sets as self-contained skills within the `skills/` directory, where each skill encapsulates its logic in a declarative [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) file and local reference documentation, operating as thin entry points over the shared `cadgen` runtime.**

The earthtojake/text-to-cad project implements a modular architecture for CAD automation that treats each capability—whether URDF generation, G-code production, or CAD visualization—as an isolated agent instruction set. This organization ensures that skills remain independent, discoverable, and reproducible by enforcing strict boundaries around dependencies and documentation. Understanding the layout of these instruction sets reveals a design pattern that separates declarative intent from runtime execution.

## Repository-Wide Architecture and AGENTS.md

The foundation of the agent instruction set organization lives in **[`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md)** at the repository root. This file serves as the canonical map that defines the repository structure, versioning policies, and enforcement rules for all skills.

At the top level, the **`skills/`** directory contains one folder per agent capability. Each subdirectory represents a distinct domain—such as `urdf`, `gcode`, or `cad-viewer`—and functions as a standalone instruction set. This flat structure under `skills/` ensures that agents can locate and invoke specific capabilities without navigating complex nested hierarchies.

## Anatomy of a Skill Instruction Set

Every agent skill follows a standardized internal layout defined by [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md). Inside each skill folder, you will find:

- **[`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md)** – The declarative instruction set that specifies the skill’s purpose, required setup steps, core operational rules, workflow descriptions, and concrete CLI commands. For example, the URDF agent instructions live in [[`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).
- **`references/`** – A dedicated folder containing supporting documentation such as design ledgers, validation guides, and frame-semantics documentation. The URDF skill references [[`skills/urdf/references/validation.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/references/validation.md)](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/references/validation.md) for constraint checking rules.

This structure ensures that each agent instruction set is **self-describing** and **locally documented**, providing a complete knowledge base within the skill boundary.

## The Shared Runtime and Thin Wrapper Pattern

Agent instruction sets in text-to-cad are intentionally **thin entry points** that delegate heavy lifting to the shared **`cadgen` distribution**. The actual runtime implementation—Python CLI parsers, JavaScript viewers, and build daemons—resides in **`packages/cadgen`** and **`packages/cadgen-js`**.

Skills never vendor the runtime internally. Instead, they declare a dependency on the exact version pinned in their [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt), matching the repository’s canonical `VERSION` file as enforced by the version-check script referenced in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md). This separation ensures that:

- Skills remain lightweight and focused on domain-specific logic
- Updates to the core runtime propagate consistently across all agent instruction sets
- CLI commands like `cadgen urdf validate` or `cadgen urdf snapshot` function as standardized wrappers over the `cadgen` package

## Organizational Rules for Instruction Sets

The [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) file enforces five critical structural rules that govern how agent instruction sets interact:

**No cross-skill imports** – A skill must not import code from another skill or modify global paths like `PYTHONPATH` or `NODE_PATH`. This isolation prevents dependency entanglement and ensures each instruction set remains independently testable.

**Source-of-truth files** – The primary artifact produced by a skill (such as a `.urdf` or `.gcode` file) serves as the immutable source of truth. Helper scripts within the skill act only as scaffolding around these core files.

**References are local** – All auxiliary documentation must live under the skill’s own `references/` folder. This policy guarantees that the instruction set contains a self-contained knowledge base without external dependencies.

**Thin CLI wrappers** – Commands exposed in [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) (such as `cadgen urdf validate …`) delegate execution to the shared runtime. The instruction set defines the interface while `packages/cadgen` handles implementation.

**Version pinning** – Each skill’s [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt) must pin `cadgen==<VERSION>` to match the repository’s canonical version. This ensures reproducibility and prevents runtime version mismatches across different agent instruction sets.

## Working with Agent Instruction Sets

To install and execute a specific skill, you interact with the thin entry points defined in its [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md):

```bash

# Install the skill dependencies (includes the pinned cadgen version)

python -m pip install -r requirements.txt

# Validate a URDF file using the instruction set's defined CLI

cadgen urdf validate path/to/robot.urdf --strict

# Generate documentation snapshot as specified in the skill workflow

cadgen urdf snapshot path/to/robot.urdf robot.png --theme snapshot

```

These commands illustrate how the declarative [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) maps directly to executable operations, with the `cadgen` package handling the underlying CAD processing.

## Summary

- Agent instruction sets reside as isolated folders under `skills/`, with [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) serving as the repository-wide map and rule enforcement mechanism.
- Each skill contains a [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) file defining its purpose and CLI interface, plus a `references/` folder for localized documentation.
- Skills operate as **thin wrappers** over the shared `cadgen` runtime located in `packages/cadgen` and `packages/cadgen-js`, preventing code duplication.
- Strict organizational rules—including no cross-skill imports, local reference requirements, and mandatory version pinning—ensure modular, testable, and reproducible agent behavior.
- The architecture separates declarative instruction sets from runtime execution, enabling consistent CAD workflows across the earthtojake/text-to-cad repository.

## Frequently Asked Questions

### What is the role of AGENTS.md in text-to-cad?

[`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) functions as the central registry and governance document for all agent instruction sets in the repository. It defines the directory structure, versioning policies, and critical rules—such as the prohibition on cross-skill imports—that maintain isolation between different capabilities. This file ensures that every skill adheres to the thin-wrapper pattern and correctly pins its dependency on the shared `cadgen` runtime.

### How are skill-specific dependencies managed across different agent instruction sets?

Each agent skill maintains its own [`requirements.txt`](https://github.com/earthtojake/text-to-cad/blob/main/requirements.txt) file that explicitly pins `cadgen==<VERSION>` to match the repository’s canonical `VERSION` file. According to the rules in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md), skills must not vendor the runtime or modify system paths; they simply declare the dependency and rely on the shared packages in `packages/cadgen`. This approach guarantees that all skills use a consistent runtime version while remaining independently installable.

### Where should validation rules and design documentation be stored for a specific skill?

All supporting documentation must live within the skill’s `references/` subdirectory, as mandated by the organizational rules in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md). For example, URDF validation guidelines reside in [`skills/urdf/references/validation.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/references/validation.md). This local storage requirement ensures that each agent instruction set contains a complete, self-contained knowledge base that does not depend on external documentation or other skills.

### Why does text-to-cad use a thin-wrapper architecture for agent skills?

The thin-wrapper design prevents skills from duplicating runtime logic by centralizing heavy processing in the `cadgen` and `cadgen-js` packages. This architecture allows agent instruction sets to focus solely on domain-specific declarations in [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) while delegating execution to the shared runtime. Consequently, updates to core CAD functionality propagate automatically to all skills without requiring modifications to individual instruction sets.