Skip to content

sidekick.md

Latest commit

 

History

History
153 lines (106 loc) · 6.83 KB

sidekick.md

File metadata and controls

153 lines (106 loc) · 6.83 KB
description Write Mechanic tasks with Shopify's built-in Sidekick AI assistant.

🤖 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.

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/mutation strings with `{{ value | json }}`. For query results, include `__typename` on every node and use `__parentId` on children. Subscribe to `mechanic/shopify/bulk_operation`. Use `bulkOperation.type` to distinguish `QUERY` from `MUTATION`; for mutation results, inspect per-line `errors` and `userErrors`.

**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 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 in real time. For task discovery and reference, use the MCP server 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