shopify-admin-customer-note-bulk-annotator

Name: shopify-admin-customer-note-bulk-annotator
Author: 40RTY-ai

168stars17forks

How to install shopify-admin-customer-note-bulk-annotator?

40rty-ai/shopify-admin-skills/shopify-admin-customer-note-bulk-annotator

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-customer-note-bulk-annotator

Installs into the current project.

Summary

Adds internal notes to customer records in bulk — useful for post-campaign flags, import annotations, or support context.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	Queries customers matching a filter (tag, email list, or spend threshold) and appends a note to each customer record. Internal notes are visible to staff in Shopify Admin but not to customers. Used for post-campaign annotation, import source tracking, VIP flags, or support context.
3
4	## Prerequisites
5	- Authenticated Shopify CLI session: `shopify store auth --store <domain> --scopes read_customers,write_customers`
6	- API scopes: `read_customers`, `write_customers`
7
8	## Parameters
9
10	\| Parameter \| Type \| Required \| Default \| Description \|
11	\|-----------\|------\|----------\|---------\|-------------\|
12	\| store \| string \| yes \| — \| Store domain (e.g., mystore.myshopify.com) \|
13	\| filter \| string \| yes \| — \| Customer filter query (e.g., `tag:vip`, `total_spent:>=500`) \|
14	\| note \| string \| yes \| — \| Note text to append to matching customers \|
15	\| append \| bool \| no \| true \| Append to existing note (true) or replace entirely (false) \|
16	\| dry_run \| bool \| no \| true \| Preview matching customers without executing mutations \|
17	\| format \| string \| no \| human \| Output format: `human` or `json` \|
18
19	## Safety
20
21	> ⚠️ If `append: false`, this overwrites the existing customer note entirely. Existing notes will be lost. Default is `append: true` which safely appends with a timestamp prefix. Run with `dry_run: true` to confirm the customer list before committing.
22
23	## Workflow Steps
24
25	1. OPERATION: `customers` — query
26	Inputs: `query: <filter>`, `first: 250`, select `id`, `displayName`, `note`, pagination cursor
27	Expected output: Matching customers with existing notes; paginate until `hasNextPage: false`
28
29	2. Construct new note: if `append: true`, prepend `[YYYY-MM-DD] <note>` to existing note (newline-separated); if `append: false`, replace with `<note>`
30
31	3. OPERATION: `customerUpdate` — mutation
32	Inputs: `id: <customer_id>`, `note: <new_note>`
33	Expected output: `customer { id, note }`, `userErrors`
34
35	## GraphQL Operations
36
37	```graphql
38	# customers:query — validated against api_version 2025-01
39	query CustomersByFilter($query: String!, $after: String) {
40	customers(first: 250, after: $after, query: $query) {
41	edges {
42	node {
43	id
44	displayName
45	defaultEmailAddress {
46	emailAddress
47	}
48	note
49	tags
50	}
51	}
52	pageInfo {
53	hasNextPage
54	endCursor
55	}
56	}
57	}
58	```
59
60	```graphql
61	# customerUpdate:mutation — validated against api_version 2025-01
62	mutation CustomerUpdateNote($input: CustomerInput!) {
63	customerUpdate(input: $input) {
64	customer {
65	id
66	displayName
67	note
68	}
69	userErrors {
70	field
71	message
72	}
73	}
74	}
75	```
76
77	## Session Tracking
78
79	Claude MUST emit the following output at each stage. This is mandatory.
80
81	On start, emit:
82	```
83	╔══════════════════════════════════════════════╗
84	║ SKILL: Customer Note Bulk Annotator ║
85	║ Store: <store domain> ║
86	║ Started: <YYYY-MM-DD HH:MM UTC> ║
87	╚══════════════════════════════════════════════╝
88	```
89
90	After each step, emit:
91	```
92	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
93	→ Params: <brief summary of key inputs>
94	→ Result: <count or outcome>
95	```
96
97	If `dry_run: true`, prefix every mutation step with `[DRY RUN]` and do not execute it.
98
99	On completion, emit:
100
101	For `format: human` (default):
102	```
103	══════════════════════════════════════════════
104	OUTCOME SUMMARY
105	Customers matched: <n>
106	Notes updated: <n>
107	Errors: <n>
108	Output: annotation_log_<date>.csv
109	══════════════════════════════════════════════
110	```
111
112	For `format: json`, emit:
113	```json
114	{
115	"skill": "customer-note-bulk-annotator",
116	"store": "<domain>",
117	"started_at": "<ISO8601>",
118	"dry_run": true,
119	"filter": "<query>",
120	"note": "<text>",
121	"append": true,
122	"outcome": {
123	"matched": 0,
124	"updated": 0,
125	"errors": 0,
126	"output_file": "annotation_log_<date>.csv"
127	}
128	}
129	```
130
131	## Output Format
132	CSV file `annotation_log_<YYYY-MM-DD>.csv` with columns:
133	`customer_id`, `name`, `email`, `previous_note`, `new_note`
134
135	## Error Handling
136	\| Error \| Cause \| Recovery \|
137	\|-------\|-------\|----------\|
138	\| `THROTTLED` \| API rate limit exceeded \| Wait 2 seconds, retry up to 3 times \|
139	\| `userErrors` on customerUpdate \| Invalid input or read-only customer \| Log error, skip customer, continue \|
140	\| No customers match filter \| Filter too narrow \| Exit with 0 matches \|
141
142	## Best Practices
143	- Always use `append: true` unless you explicitly intend to overwrite existing notes — staff notes may contain important history.
144	- Include a datestamp in the `note`

People who liked this also viewed

6 picks

Type

shopify-admin-customer-note-bulk-annotator

168stars17forks

View on GitHub

How to install shopify-admin-customer-note-bulk-annotator?

40rty-ai/shopify-admin-skills/shopify-admin-customer-note-bulk-annotator

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-customer-note-bulk-annotator

Installs into the current project.

Summary

Adds internal notes to customer records in bulk — useful for post-campaign flags, import annotations, or support context.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	Queries customers matching a filter (tag, email list, or spend threshold) and appends a note to each customer record. Internal notes are visible to staff in Shopify Admin but not to customers. Used for post-campaign annotation, import source tracking, VIP flags, or support context.
3
4	## Prerequisites
5	- Authenticated Shopify CLI session: `shopify store auth --store <domain> --scopes read_customers,write_customers`
6	- API scopes: `read_customers`, `write_customers`
7
8	## Parameters
9
10	\| Parameter \| Type \| Required \| Default \| Description \|
11	\|-----------\|------\|----------\|---------\|-------------\|
12	\| store \| string \| yes \| — \| Store domain (e.g., mystore.myshopify.com) \|
13	\| filter \| string \| yes \| — \| Customer filter query (e.g., `tag:vip`, `total_spent:>=500`) \|
14	\| note \| string \| yes \| — \| Note text to append to matching customers \|
15	\| append \| bool \| no \| true \| Append to existing note (true) or replace entirely (false) \|
16	\| dry_run \| bool \| no \| true \| Preview matching customers without executing mutations \|
17	\| format \| string \| no \| human \| Output format: `human` or `json` \|
18
19	## Safety
20
21	> ⚠️ If `append: false`, this overwrites the existing customer note entirely. Existing notes will be lost. Default is `append: true` which safely appends with a timestamp prefix. Run with `dry_run: true` to confirm the customer list before committing.
22
23	## Workflow Steps
24
25	1. OPERATION: `customers` — query
26	Inputs: `query: <filter>`, `first: 250`, select `id`, `displayName`, `note`, pagination cursor
27	Expected output: Matching customers with existing notes; paginate until `hasNextPage: false`
28
29	2. Construct new note: if `append: true`, prepend `[YYYY-MM-DD] <note>` to existing note (newline-separated); if `append: false`, replace with `<note>`
30
31	3. OPERATION: `customerUpdate` — mutation
32	Inputs: `id: <customer_id>`, `note: <new_note>`
33	Expected output: `customer { id, note }`, `userErrors`
34
35	## GraphQL Operations
36
37	```graphql
38	# customers:query — validated against api_version 2025-01
39	query CustomersByFilter($query: String!, $after: String) {
40	customers(first: 250, after: $after, query: $query) {
41	edges {
42	node {
43	id
44	displayName
45	defaultEmailAddress {
46	emailAddress
47	}
48	note
49	tags
50	}
51	}
52	pageInfo {
53	hasNextPage
54	endCursor
55	}
56	}
57	}
58	```
59
60	```graphql
61	# customerUpdate:mutation — validated against api_version 2025-01
62	mutation CustomerUpdateNote($input: CustomerInput!) {
63	customerUpdate(input: $input) {
64	customer {
65	id
66	displayName
67	note
68	}
69	userErrors {
70	field
71	message
72	}
73	}
74	}
75	```
76
77	## Session Tracking
78
79	Claude MUST emit the following output at each stage. This is mandatory.
80
81	On start, emit:
82	```
83	╔══════════════════════════════════════════════╗
84	║ SKILL: Customer Note Bulk Annotator ║
85	║ Store: <store domain> ║
86	║ Started: <YYYY-MM-DD HH:MM UTC> ║
87	╚══════════════════════════════════════════════╝
88	```
89
90	After each step, emit:
91	```
92	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
93	→ Params: <brief summary of key inputs>
94	→ Result: <count or outcome>
95	```
96
97	If `dry_run: true`, prefix every mutation step with `[DRY RUN]` and do not execute it.
98
99	On completion, emit:
100
101	For `format: human` (default):
102	```
103	══════════════════════════════════════════════
104	OUTCOME SUMMARY
105	Customers matched: <n>
106	Notes updated: <n>
107	Errors: <n>
108	Output: annotation_log_<date>.csv
109	══════════════════════════════════════════════
110	```
111
112	For `format: json`, emit:
113	```json
114	{
115	"skill": "customer-note-bulk-annotator",
116	"store": "<domain>",
117	"started_at": "<ISO8601>",
118	"dry_run": true,
119	"filter": "<query>",
120	"note": "<text>",
121	"append": true,
122	"outcome": {
123	"matched": 0,
124	"updated": 0,
125	"errors": 0,
126	"output_file": "annotation_log_<date>.csv"
127	}
128	}
129	```
130
131	## Output Format
132	CSV file `annotation_log_<YYYY-MM-DD>.csv` with columns:
133	`customer_id`, `name`, `email`, `previous_note`, `new_note`
134
135	## Error Handling
136	\| Error \| Cause \| Recovery \|
137	\|-------\|-------\|----------\|
138	\| `THROTTLED` \| API rate limit exceeded \| Wait 2 seconds, retry up to 3 times \|
139	\| `userErrors` on customerUpdate \| Invalid input or read-only customer \| Log error, skip customer, continue \|
140	\| No customers match filter \| Filter too narrow \| Exit with 0 matches \|
141
142	## Best Practices
143	- Always use `append: true` unless you explicitly intend to overwrite existing notes — staff notes may contain important history.
144	- Include a datestamp in the `note`

People who liked this also viewed

6 picks

Type