# Using AI with Mechanic

{% hint style="info" %}
[**Ask Mechanic**](https://learn.mechanic.dev/app/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:

* [**Mechanic MCP Server**](https://learn.mechanic.dev/resources/mcp) — connect your AI coding tool to the task library and docs
* [**Mechanic Agent Skills**](https://learn.mechanic.dev/resources/agent-skills) — install task-writing expertise into your AI coding tool
* [**Mechanic Sidekick Skill**](https://learn.mechanic.dev/resources/sidekick) — write tasks with Shopify's built-in AI assistant
* [**Mechanic GPT**](https://learn.mechanic.dev/resources/chatgpt) — get help and write tasks in ChatGPT
  {% endhint %}

{% hint style="warning" %}
Mechanic support covers the platform and tasks from the [task library](https://learn.mechanic.dev/resources/task-library). AI-generated tasks are [custom tasks](https://learn.mechanic.dev/custom), and our support for custom tasks is limited to platform-level issues. For help with custom task logic, ask in the [Mechanic Slack community](https://learn.mechanic.dev/resources/slack) or hire a developer through [partners.mechanic.dev](https://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](https://learn.mechanic.dev/resources/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**](https://learn.mechanic.dev/resources/mcp) and [**Agent Skills**](https://learn.mechanic.dev/resources/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**](https://learn.mechanic.dev/resources/shopify-dev-mcp) 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**](https://learn.mechanic.dev/resources/sidekick) brings Mechanic task-writing expertise directly into Shopify's built-in AI assistant.

### For ChatGPT users

The [**Mechanic GPT**](https://learn.mechanic.dev/resources/chatgpt) 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](https://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 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.