🤖Using AI with Mechanic

Mechanic offers dedicated AI tools that understand the platform's patterns, task library, and documentation:

• Mechanic MCP Server — connect your AI coding tool to the task library and docs

• Mechanic Agent Skills — install task-writing expertise into your AI coding tool

• Mechanic Sidekick Skill — write tasks with Shopify's built-in AI assistant

• Mechanic GPT — get help and write tasks in ChatGPT

Mechanic support covers the platform and tasks from the task library. AI-generated tasks are custom tasks, and our support for custom tasks is limited to platform-level issues. For help with custom task logic, ask in the Mechanic Slack community or hire a developer through partners.mechanic.dev.

---

AI tools for Mechanic

For developers

The MCP server and Agent Skills are designed to work together. The MCP server gives your AI assistant access to Mechanic's task library and documentation at query time. Agent Skills install Mechanic's task-writing patterns directly into your AI's context, so it knows how to structure subscriptions, handle preview mode, use GraphQL, and produce complete importable task JSON.

For the best results, use both: the MCP server for research and reference, and Agent Skills for writing code.

The Shopify Dev MCP Server is also worth adding — it gives your AI assistant direct access to Shopify's GraphQL schema and query validation.

If you're working in Shopify Admin, the Sidekick skill brings Mechanic task-writing expertise directly into Shopify's built-in AI assistant.

For ChatGPT users

The Mechanic GPT has access to Mechanic's full documentation and can answer questions about the platform, explain concepts, and write or debug task code — all within ChatGPT. For agentic coding workflows, the MCP server and Agent Skills produce better results — but the GPT is a convenient option if ChatGPT is your primary tool.

---

Tips for working with AI

These apply regardless of which AI tool you're using:

• Start from the task library. Search tasks.mechanic.dev for an existing task that's close to what you need. Modifying a working task is faster and more reliable than starting from scratch.

• Check subscriptions. Make sure the task subscribes to the right event topics. A task that listens to shopify/orders/create won't fire on order updates.

• Prefer GraphQL. Shopify REST is deprecated in Mechanic. Use the GraphQL Admin API for reading and writing Shopify data.

• Verify the output format. A complete Mechanic task is a JSON object with name, script, subscriptions, subscriptions_template, options, and other fields. If your AI produces only a Liquid script, it's missing the structure needed for import.

• Watch for async vs sync confusion. This is the most common AI mistake. query | shopify returns data immediately. {% action "shopify" %} queues a mutation that runs after the script finishes. If the AI tries to use a mutation result in the same script run, the task will silently fail.

• Check for preview mode. Every event topic the task subscribes to needs an {% if event.preview %} block with mock data. If the task subscribes to 3 topics, there should be 3 preview blocks. Missing previews mean Mechanic can't verify the task will produce valid actions.

• Webhook orders need admin_graphql_api_id. When an order arrives via webhook (like shopify/orders/create), the order ID is REST-style. The task needs to use order.admin_graphql_api_id to get the full GraphQL ID for mutations. Using order.id directly will fail.