How to Find Off-the-Shelf STEP Parts with the step-parts Skill

The step-parts skill in the earthtojake/text-to-cad repository enables you to search the public step.parts catalog and download manufacturer-verified STEP files directly into your CAD workflow using natural language commands.

The step-parts skill is a specialized component of the text-to-cad open-source project that bridges natural language processing with hardware component procurement. By leveraging the public step.parts API, this skill transforms descriptive queries like "M8 hex socket head screw" into downloadable, production-ready 3D models without manual modeling.

How the step-parts Skill Works

Core Architecture

The skill operates as a self-contained module under skills/step-parts/, following the repository's rule that skills must remain independent at runtime. It consists of four primary components:

• Skill Definition (skills/step-parts/SKILL.md): Declares the skill metadata, description, and usage patterns.
• LLM Prompt Template (skills/step-parts/agents/openai.yaml): Configures how the language model invokes the skill using the $step-parts placeholder.
• Implementation Script (skills/step-parts/scripts/download_step_part.py): Handles HTTP requests to the step.parts API, parses JSON responses, and streams STEP files to local storage.
• API Reference (skills/step-parts/references/step-parts-api.md): Documents endpoint specifications, query parameters, and response schemas.

The $step-parts Placeholder Convention

Like other skills in the repository, step-parts uses a $step-parts token to signal handoff. When the LLM encounters this placeholder in a prompt, it extracts the natural language query and routes execution to download_step_part.py. The script constructs an HTTP GET request against the step.parts search endpoint, attaches the custom User-Agent: step-parts-skill/1.0 header, and processes the results to identify the optimal part match.

Searching and Downloading STEP Parts

Command Line Interface

The repository provides a unified CLI entry point that dispatches commands to specific skills. To search for and download a component:

text-to-cad step-parts "M8 hex socket head screw"

This command prints part metadata (manufacturer, part number, specifications) and writes the .step file to your current working directory. To specify a custom output location:

text-to-cad step-parts "20 mm deep groove bearing" --output ./models/bearings/

Python API Integration

For programmatic access within custom pipelines or other skills, import the download function directly:

from skills.step_parts.scripts.download_step_part import download_step_part

# Define your search query

query = "M8 hex socket head screw"

# Optional: specify target directory

target_dir = "./components/fasteners/"

# Execute download

step_file_path = download_step_part(query, output_dir=target_dir)
print(f"STEP file saved to: {step_file_path}")

The function returns the absolute path to the downloaded file or raises an exception if no suitable match exists in the catalog.

Embedding in Multi-Part Workflows

When using higher-level CAD generation skills, you can request automatic part procurement by including the placeholder in your assembly description:

Create a mounting bracket assembly using an aluminum plate, 
$step-parts "M8x20mm hex socket cap screw" (quantity 4), 
and $step-parts "608ZZ ball bearing" (quantity 2).

The LLM processes each $step-parts invocation separately, downloading all referenced components before proceeding with the assembly generation.

Implementation Details

API Interaction Logic

In skills/step-parts/scripts/download_step_part.py, the core logic performs the following operations:

1. Constructs a sanitized query string from natural language input
2. Issues an HTTP GET to the step.parts search endpoint documented in step-parts-api.md
3. Validates the JSON response against expected schemas
4. Selects the highest-confidence match based on metadata relevance
5. Streams the binary STEP file content to disk using the part's original filename or a sanitized derivative

Skill Independence

Per repository architecture requirements, the step-parts skill maintains zero runtime dependencies on other skill modules. Shared utilities from packages/cadpy are vendored during the bundle process, ensuring the skill functions as a standalone unit when deployed.

Summary

• The step-parts skill enables natural language search against the public step.parts catalog from within the text-to-cad ecosystem
• Key files include SKILL.md for metadata, download_step_part.py for API interaction, and openai.yaml for LLM prompt configuration
• Invoke the skill via text-to-cad step-parts "<query>" CLI command or import download_step_part directly in Python
• The $step-parts placeholder allows seamless integration into complex CAD generation workflows
• All API requests use the custom User-Agent step-parts-skill/1.0 for identification and rate limiting purposes

Frequently Asked Questions

What is the step.parts catalog?

The step.parts catalog is a public database of manufacturer-verified mechanical components available in STEP format. The step-parts skill queries this database via REST API to retrieve geometric data for standard hardware like screws, bearings, and brackets, eliminating the need to model common components manually.

Can I use the step-parts skill without the full text-to-cad CLI?

Yes. While designed for integration with the text-to-cad framework, the download_step_part function in skills/step-parts/scripts/download_step_part.py operates independently. You can import and call this function from any Python environment, provided you have network access to the step.parts API endpoints.

How does the skill handle multiple matching parts?

When the step.parts API returns multiple candidates for a query like "M8 screw," the implementation script in download_step_part.py applies heuristics based on popularity ratings and metadata completeness to select the single best match. Currently, the skill returns one file per query; for bulk downloads, invoke the skill multiple times with specific manufacturer part numbers.

Where are downloaded STEP files stored?

By default, the CLI writes files to the current working directory, while the Python API uses the specified output_dir parameter. If no directory is provided, the skill creates a ./step_parts_downloads/ folder to prevent cluttering project roots. All filenames are sanitized to remove spaces and special characters incompatible with common CAD import workflows.

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