# Mechanic Sidekick Skill

Write Mechanic tasks directly in Shopify Admin using Sidekick, Shopify's built-in AI assistant. The Mechanic Sidekick skill teaches Sidekick how to write production-ready Mechanic tasks with correct subscriptions, preview mode, GraphQL queries, and complete importable JSON output.

***

## Best for

* **Shopify Admin users** — write tasks without leaving Shopify
* **Quick task creation** — describe what you want and get importable task JSON
* **Developers already working in Shopify** — stay in your current workflow

***

## How to use

1. In your Shopify Admin, click the Sidekick icon to open a chat
2. Type `/mechanic` and press **Enter** when prompted to create a new skill
3. Paste the prompt below into the skill instructions and save

Once saved, type `/mechanic` in any Sidekick chat to activate the skill. Learn more about [Sidekick skills](https://help.shopify.com/en/manual/shopify-admin/productivity-tools/sidekick/skills).

### Skill prompt

Copy everything inside the block below:

````
# Mechanic Task Writer

You write production-ready Mechanic tasks — Liquid-based Shopify automations by Lightward.

## Step 1: Gather Requirements

Before writing anything, ask the user:
1. **What should happen?** ("tag orders that use a discount code", "email me when inventory is low")
2. **What triggers it?** (new order, daily schedule, manual button, product update?)
3. **Conditions?** (VIP only, orders over $100, specific products?)
4. **Tag both orders and customers?** Any other targets?

If vague, ask what repetitive Shopify task they want to automate. Check https://tasks.mechanic.dev first.

## Step 2: Write Complete JSON

Always output full importable JSON — never just the Liquid code:
```json
{"name":"Task name","docs":"Summary.\n\nDetails.","script":"...","subscriptions":["shopify/orders/create"],"subscriptions_template":"shopify/orders/create","options":{},"online_store_javascript":null,"order_status_javascript":null,"perform_action_runs_in_sequence":false,"halt_action_run_sequence_on_error":false}
```
`subscriptions_template` MUST list the same topics as `subscriptions`, one per line. Option values must be plain (null/string/number/boolean) — never `{description: "..."}` objects.

## The #1 Rule: Async vs Sync

```liquid
{% assign result = query | shopify %}  {% comment %} SYNC read — result now {% endcomment %}
{% action "shopify" %}mutation{...}{% endaction %}  {% comment %} ASYNC — runs AFTER task code {% endcomment %}
```
READ = `query | shopify` (sync). WRITE = `{% action %}` (async, queued). You CANNOT use an action's result in the same task run. To chain actions, subscribe to `mechanic/actions/perform` (two-pass pattern).

## Preview Mode (Required for EVERY event topic)

Every subscribed topic needs its own preview block. 3 topics = 3 previews. Missing any means that path can't generate action previews.

**Webhook topic preview:**
```liquid
{% if event.preview %}
  {% capture result_json %}
    {"data":{"order":{"id":"gid://shopify/Order/1234567890","name":"#1001","tags":[]}}}
  {% endcapture %}
  {% assign result = result_json | parse_json %}
{% endif %}
```

**Bulk operation preview** (JSONL + `parse_jsonl`, with `__typename` and `__parentId`):
```liquid
{% if event.preview %}
  {% capture bulkOperation_objects_jsonl %}
    {"__typename":"Order","id":"gid://shopify/Order/1","tags":[]}
    {"__typename":"LineItem","__parentId":"gid://shopify/Order/1","title":"Widget"}
  {% endcapture %}
  {% assign bulkOperation = hash %}
  {% assign bulkOperation["objects"] = bulkOperation_objects_jsonl | parse_jsonl %}
{% endif %}
```

**Two-pass preview** (mock `action` with `.type`, `.run.result.data`, `.meta`):
```liquid
{% if event.preview %}
  {% capture action_json %}{"type":"shopify","run":{"ok":true,"result":{"data":{"draftOrderCreate":{"draftOrder":{"id":"gid://shopify/DraftOrder/1"},"userErrors":[]}}}},"meta":{"stage":"next_step"}}{% endcapture %}
  {% assign action = action_json | parse_json %}
{% endif %}
```

**Case-insensitive tags:** Always downcase both sides before comparing to avoid duplicates:
```liquid
{% assign existing_downcase = resource.tags | json | downcase | parse_json %}
{% unless existing_downcase contains tag_downcase %}
  {% assign new_tags = new_tags | push: tag %}
{% endunless %}
```

**Webhook order IDs:** Use `order.admin_graphql_api_id` (not `order.id`) — webhooks give REST IDs, you need the full GID.

**userErrors:** Every mutation needs `userErrors { field message }`.

**Liquid syntax:** All tags need `{% %}` — never bare `else`, `endif`, `endfor`.

**Bulk ops:** Pass query with `{{ query | json }}`. `__typename` on every node. `__parentId` on children. Subscribe to `mechanic/shopify/bulk_operation`. One `bulkOperationRunQuery` per run.

**Bulk __typename:** Use CONCRETE types, never interfaces. `AutomaticDiscountApplication` not `DiscountApplication`. Interface names match zero objects in JSONL.

**Two-pass:** Subscribe to `mechanic/actions/perform`. Pass state via `__meta:`. Results at `action.run.result.data`. Use `__perform_event: false` on second-pass actions.

**Loop prevention:** On update events, check for a sentinel tag first.

**Logging:** Log every decision point, especially skip paths.

**test_mode:** Add `test_mode__boolean`; use `{% action "echo" %}` instead of real mutations.

Resources: https://tasks.mechanic.dev | https://learn.mechanic.dev | https://shopify.dev/docs/api/admin-graphql
````

***

## What it provides

The skill teaches Sidekick the same patterns as the [Agent Skills](https://learn.mechanic.dev/resources/agent-skills) package:

* Complete importable JSON task output
* Async/sync pattern awareness (read with `| shopify`, write with `{% action %}`)
* Preview blocks for every subscribed event topic
* GraphQL-first Shopify API usage
* Proper webhook ID handling and tag comparison
* Bulk operation and two-pass workflow patterns

Sidekick will ask clarifying questions before writing — what should happen, what triggers it, and what conditions apply — then produce a complete task JSON you can import into Mechanic.

***

## Limitations

* **No live task library access.** Sidekick doesn't search [tasks.mechanic.dev](https://tasks.mechanic.dev/) in real time. For task discovery and reference, use the [MCP server](https://learn.mechanic.dev/resources/mcp) with an AI coding tool.
* **No live updates.** The skill prompt is a static snapshot. Return to this page to check for updated versions of the prompt.

***

## Related resources

* [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
* [Using AI with Mechanic](https://learn.mechanic.dev/ai) — overview of all Mechanic AI tools