|
| 1 | +# AI Agent Orientation |
| 2 | + |
| 3 | +This is the community task library for [Mechanic](https://mechanic.dev/), a Liquid-based development and automation platform for Shopify stores. |
| 4 | + |
| 5 | +## AI tools for Mechanic |
| 6 | + |
| 7 | +For the best results writing and debugging Mechanic tasks, install these tools: |
| 8 | + |
| 9 | +- **Agent Skill** — install Mechanic's task-writing patterns directly into your AI context: `npx skills add lightward/mechanic-skills --skill mechanic-task-writer` |
| 10 | +- **MCP Server** — gives your AI live access to the task library and documentation: `claude mcp add --scope user --transport stdio mechanic-mcp -- npx -y @lightward/mechanic-mcp@latest` |
| 11 | + |
| 12 | +Full setup guide: https://learn.mechanic.dev/ai |
| 13 | + |
| 14 | +## What matters in this repo |
| 15 | + |
| 16 | +The **`tasks/`** directory is the primary content. Each `.json` file is a complete, importable Mechanic task containing: |
| 17 | + |
| 18 | +- `name` — task display name |
| 19 | +- `script` — the Liquid source code |
| 20 | +- `subscriptions` — event topics the task responds to (Shopify webhooks, schedules, custom events) |
| 21 | +- `subscriptions_template` — Liquid template that generates subscriptions dynamically from options |
| 22 | +- `options` — merchant-configurable settings with type suffixes (e.g. `__required`, `__number`, `__boolean`) |
| 23 | +- `docs` — task documentation (first paragraph is the summary) |
| 24 | + |
| 25 | +## What to ignore |
| 26 | + |
| 27 | +- **`docs/`** — auto-generated documentation; do not reference as authoritative source code |
| 28 | +- **`lib/`** — Node.js build tooling for generating docs and validating tasks; not part of Mechanic |
| 29 | +- **`signatures/`** — internal verification data |
| 30 | +- **`.github/`**, **`.husky/`**, **`node_modules/`** — standard project infrastructure |
| 31 | + |
| 32 | +## Common AI mistakes with Mechanic |
| 33 | + |
| 34 | +Mechanic Liquid is **not** Shopify theme Liquid. It has custom tags, custom filters, and its own execution model. If you're writing a Mechanic task, these are the mistakes to avoid: |
| 35 | + |
| 36 | +### 1. Confusing async actions with sync reads |
| 37 | + |
| 38 | +This is the most common mistake. `{% action "shopify" %}` queues a mutation that runs **after** the script finishes — you cannot use its result in the same script run. For reading data, use the synchronous `shopify` filter: |
| 39 | + |
| 40 | +```liquid |
| 41 | +{% comment %} WRONG — trying to use an action result inline {% endcomment %} |
| 42 | +{% action "shopify" %} |
| 43 | + mutation { tagsAdd(id: {{ order.id | json }}, tags: ["processed"]) { ... } } |
| 44 | +{% endaction %} |
| 45 | +{% comment %} The tag hasn't been added yet here! {% endcomment %} |
| 46 | +
|
| 47 | +{% comment %} RIGHT — reading data synchronously {% endcomment %} |
| 48 | +{% capture query %} |
| 49 | + query { order(id: {{ order.admin_graphql_api_id | json }}) { tags } } |
| 50 | +{% endcapture %} |
| 51 | +{% assign result = query | shopify %} |
| 52 | +{% comment %} result.data.order.tags is available immediately {% endcomment %} |
| 53 | +``` |
| 54 | + |
| 55 | +### 2. Missing preview mode |
| 56 | + |
| 57 | +Every event topic a task subscribes to needs an `{% if event.preview %}` block with mock data. Preview mode is how Mechanic verifies a task produces valid actions and determines what Shopify permissions to request. No preview = no permissions = broken task. |
| 58 | + |
| 59 | +```liquid |
| 60 | +{% if event.preview %} |
| 61 | + {% assign order = hash %} |
| 62 | + {% assign order["admin_graphql_api_id"] = "gid://shopify/Order/1234567890" %} |
| 63 | + {% assign order["name"] = "#1001" %} |
| 64 | + {% assign order["tags"] = array %} |
| 65 | +{% endif %} |
| 66 | +``` |
| 67 | + |
| 68 | +### 3. Using REST instead of GraphQL |
| 69 | + |
| 70 | +Shopify REST is deprecated in Mechanic. Always use the GraphQL Admin API for both reads and writes. |
| 71 | + |
| 72 | +### 4. Wrong ID format for webhook data |
| 73 | + |
| 74 | +When an order arrives via webhook (like `shopify/orders/create`), the order object has a REST-style numeric ID. Use `order.admin_graphql_api_id` to get the GraphQL ID for mutations, not `order.id`. |
| 75 | + |
| 76 | +### 5. Missing `userErrors` in mutations |
| 77 | + |
| 78 | +Always request `userErrors { field message }` in Shopify mutations. Without it, a failed mutation silently succeeds from the task's perspective. |
| 79 | + |
| 80 | +## Resources |
| 81 | + |
| 82 | +- Documentation: https://learn.mechanic.dev |
| 83 | +- AI tools and guidance: https://learn.mechanic.dev/ai |
| 84 | +- Task library (browsable): https://tasks.mechanic.dev |
| 85 | +- Agent Skill source: https://github.com/lightward/mechanic-skills |
| 86 | +- MCP Server docs: https://learn.mechanic.dev/resources/mcp |
0 commit comments