Skip to content

ai.md

Latest commit

 

History

History
57 lines (37 loc) · 5.17 KB

ai.md

File metadata and controls

57 lines (37 loc) · 5.17 KB
description Use AI tools to write and debug Shopify automation tasks in Mechanic — MCP server, Agent Skills, Sidekick, and ChatGPT.

🤖 Using AI with Mechanic

{% hint style="info" %} Ask Mechanic is Mechanic's built-in AI assistant, with access to Mechanic's docs and Shopify's GraphQL schema and API documentation. Use it right inside the app to ask questions, find tasks, and get help with task code — no setup required.

For developers writing tasks, Mechanic also offers dedicated AI tools:

{% hint style="warning" %} 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. {% endhint %}

AI tools for Mechanic

Ask Mechanic (in-app)

Ask Mechanic is Mechanic's built-in AI assistant, available directly inside the app. It has access to Mechanic's full documentation and the Shopify Dev MCP (Shopify's GraphQL schema and API documentation), so it can answer platform questions, help you find tasks, explain how features work, and assist with task code. Look for the Ask Mechanic button in the app to get started — no setup or external tools needed.

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.
  • Use native Shopify subscriptions by default. Most Shopify-triggered tasks should subscribe to regular shopify/... topics. Use custom Shopify webhooks only when the task needs Shopify-side filtering, include_fields, metafield filtering or delivery, or metaobject events; those webhooks deliver onto user/... topics.
  • 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 the Liquid code, 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 task code finishes. If the AI tries to use a mutation result in the same task 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.