cx-listing-playbook 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +64 -2
- package/package.json +48 -4
- package/prompts/listing-create.md +5 -0
- package/prompts/listing-review.md +5 -0
- package/prompts/listing-watch.md +7 -0
- package/research/README.md +648 -0
- package/research/angles/account-health.md +482 -0
- package/research/angles/ai-shopping-surfaces.md +438 -0
- package/research/angles/brand-protection-and-catalog-contribution.md +489 -0
- package/research/angles/competitor-discovery.md +369 -0
- package/research/angles/competitor-set.md +589 -0
- package/research/angles/inventory-and-fulfillment.md +927 -0
- package/research/angles/listing-content-and-health.md +935 -0
- package/research/angles/marketplaces-and-languages.md +386 -0
- package/research/angles/off-listing-traffic.md +290 -0
- package/research/angles/offer-competition-and-hijackers.md +543 -0
- package/research/angles/own-traffic-funnel.md +607 -0
- package/research/angles/paid-keywords.md +689 -0
- package/research/angles/price-position.md +875 -0
- package/research/angles/returns.md +508 -0
- package/research/angles/reviews-and-qa.md +637 -0
- package/research/angles/search-query-performance.md +544 -0
- package/research/angles/search-rank-and-volume.md +463 -0
- package/research/angles/seasonality-and-events.md +647 -0
- package/research/angles/vendor-and-hybrid.md +831 -0
- package/research/elements/a-plus-content.md +642 -0
- package/research/elements/attributes-and-browse-nodes.md +901 -0
- package/research/elements/badges-and-placements.md +443 -0
- package/research/elements/brand-story-and-store.md +605 -0
- package/research/elements/bullet-points.md +664 -0
- package/research/elements/description.md +460 -0
- package/research/elements/images-and-video.md +720 -0
- package/research/elements/search-terms.md +688 -0
- package/research/elements/title.md +841 -0
- package/research/elements/variations.md +710 -0
- package/research/method/amazon-change-calendar.md +354 -0
- package/research/method/effect-measurement.md +878 -0
- package/research/method/funnel-and-search.md +662 -0
- package/research/method/help-page-access.md +432 -0
- package/research/method/listing-create.md +389 -0
- package/research/method/listing-policies.md +913 -0
- package/research/method/listing-writes.md +1099 -0
- package/research/method/report-lifecycle.md +586 -0
- package/research/method/seller-central-only-tools.md +545 -0
- package/research/method/sp-api-access.md +400 -0
- package/research/method/triggers.md +844 -0
- package/skills/effect-review/SKILL.md +34 -0
- package/skills/effect-review/references/confounders.md +114 -0
- package/skills/effect-review/references/design.md +73 -0
- package/skills/effect-review/references/verdicts.md +91 -0
- package/skills/listing-change-log/SKILL.md +24 -0
- package/skills/listing-change-log/references/record.md +97 -0
- package/skills/listing-create/SKILL.md +68 -0
- package/skills/listing-create/references/answers.md +18 -0
- package/skills/listing-create/references/family.md +10 -0
- package/skills/listing-create/references/request.md +44 -0
- package/skills/listing-review/SKILL.md +43 -0
- package/skills/listing-review/references/figures.md +94 -0
- package/skills/listing-review/references/funnel.md +96 -0
- package/skills/listing-review/references/good-listing.md +117 -0
- package/skills/listing-review/references/policy.md +98 -0
- package/skills/listing-review/references/reports.md +87 -0
- package/skills/listing-review/references/signals.md +80 -0
- package/skills/listing-review/references/watch.md +84 -0
- package/skills/listing-review/references/write-path.md +101 -0
- package/skills/listing-review/references/writing.md +39 -0
- package/skills/listing-review/scripts/report.sh +170 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ComChatX
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,65 @@
|
|
|
1
|
-
#
|
|
1
|
+
# cx-listing-playbook
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A [pi](https://pi.dev) package for the work on an Amazon listing: creating it, how it performs and why, a log of each change, and how to judge whether a change worked. It is written for the assistant in a [ComChatX](https://comchatx.com) seller's box, and reads the seller's Amazon account through the box's `cx` command.
|
|
4
|
+
|
|
5
|
+
It is text and one script. Its changes are in [CHANGELOG.md](CHANGELOG.md). Every sentence of the skills ends with the research item it rests on, and the research is in [`research/`](research/README.md).
|
|
6
|
+
|
|
7
|
+
## What it holds
|
|
8
|
+
|
|
9
|
+
| | What the model reads |
|
|
10
|
+
|---|---|
|
|
11
|
+
| `skills/listing-review` | The funnel and which element serves each stage, what Amazon's own answers show about a listing, the signals that something changed, which file carries each figure, how a write is validated (`references/writing.md`), and `scripts/report.sh` |
|
|
12
|
+
| `skills/listing-change-log` | One file per listing change: before, after, what was expected and from which file, the words bet on, the seller's decision, the request as it would be sent, Amazon's receipt id and the observation window |
|
|
13
|
+
| `skills/listing-create` | Creating a listing in the stores the seller names: new item or existing ASIN, the product type and each store's schema, identity, the request built from the seller's data, the preview (sent as a read, since it persists nothing), the write on the seller's word, the read-back until buyable and discoverable, and variation families |
|
|
14
|
+
| `skills/effect-review` | Experiments, baseline and observation windows, controls, confounders, and the three verdicts: held, not held, cannot tell |
|
|
15
|
+
| `prompts/listing-create.md` | `/listing-create <marketplaces> <your words, and where the product's data is>`: hands the seller's words to cx, e.g. `/listing-create US,DE 新品上架,数据在 /tenant/products/new-router/,FBA 发货` |
|
|
16
|
+
| `prompts/listing-review.md` | `/listing-review <ASIN>`: the listing and its issues, the market since last time, a proposal with its reasons |
|
|
17
|
+
| `prompts/listing-watch.md` | `/listing-watch <ASIN> <your words>`: writes the standing instruction for that listing from the seller's words, e.g. `/listing-watch <ASIN> 以后每天帮我盯着这个 listing,有要改的告诉我,没事别吵` |
|
|
18
|
+
|
|
19
|
+
Each skill's detail is under its `references/`.
|
|
20
|
+
|
|
21
|
+
## Files in the seller's tree
|
|
22
|
+
|
|
23
|
+
| Place | Holds |
|
|
24
|
+
|---|---|
|
|
25
|
+
| `/tenant/listings/<ASIN>/watch.md` | The standing instruction `/listing-watch` writes |
|
|
26
|
+
| `/tenant/listings/<ASIN>/changes/` | One file per listing change; changes made together are one change |
|
|
27
|
+
| `/tenant/reports/<reportType>/<ask>/<n>/` | One report of that ask: `receipt.json` with the report id, Amazon's status and `createdTime`, each reply as Amazon gave it, and the document |
|
|
28
|
+
|
|
29
|
+
## The report script
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
scripts/report.sh <reportType> --origin <origin> --marketplace <id>[,<id>...] [--start <ISO 8601>] [--end <ISO 8601>] \
|
|
33
|
+
[--option <name>=<value>]... --wait <seconds> [--every <seconds>]
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
It asks Amazon's Reports API through `cx raw amazon-sp-api`: `createReport`, `getReport` until a terminal status or the `--wait` ceiling, `getReportDocument` and the document, decompressed, landed beside the receipt. Each run asks for a report of its own, except that it carries on the ask's report not yet landed: one still queued at the ceiling ends the run with its id and status (exit 3) for the next run to carry on. Earlier reports stay as they landed. It has no rate limiter and no retry of its own. Report types, their options and their periods are the `amazon-sp-api` skill's (`references/door.md`). It needs `bash`, `jq`, `curl` and `gzip`, which the box has.
|
|
37
|
+
|
|
38
|
+
## What it needs
|
|
39
|
+
|
|
40
|
+
pi, and in the box the `cx` command with the Amazon SP-API source; Keepa where a skill names a Keepa field. It reaches no network itself except the one document link Amazon hands the script.
|
|
41
|
+
|
|
42
|
+
## Install
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pi install npm:cx-listing-playbook # for you, in ~/.pi/agent/settings.json
|
|
46
|
+
pi install -l npm:cx-listing-playbook # for one project, in .pi/settings.json
|
|
47
|
+
pi remove npm:cx-listing-playbook
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
On ComChatX, a seller installs it from the Plugins page.
|
|
51
|
+
|
|
52
|
+
## Develop
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
npm ci
|
|
56
|
+
npm run typecheck
|
|
57
|
+
npm test # pi at the pin loads the package and expands every template; every text line cites a research item;
|
|
58
|
+
# the script runs against a stub cx
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`TENANT_TREE` moves the script's tree from `/tenant` for a run outside the box, as the tests do.
|
|
62
|
+
|
|
63
|
+
## Licence
|
|
64
|
+
|
|
65
|
+
MIT. See [LICENSE](LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,50 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cx-listing-playbook",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "A pi package for the work on an Amazon listing: how it performs and why, a log of each change, and how to judge one.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "ComChatX",
|
|
7
|
+
"homepage": "https://github.com/comchatx/cx-listing-playbook#readme",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/comchatx/cx-listing-playbook.git"
|
|
11
|
+
},
|
|
12
|
+
"bugs": "https://github.com/comchatx/cx-listing-playbook/issues",
|
|
13
|
+
"keywords": [
|
|
14
|
+
"pi-package"
|
|
15
|
+
],
|
|
16
|
+
"type": "module",
|
|
17
|
+
"pi": {
|
|
18
|
+
"skills": [
|
|
19
|
+
"./skills"
|
|
20
|
+
],
|
|
21
|
+
"prompts": [
|
|
22
|
+
"./prompts"
|
|
23
|
+
]
|
|
24
|
+
},
|
|
25
|
+
"files": [
|
|
26
|
+
"skills",
|
|
27
|
+
"prompts",
|
|
28
|
+
"research"
|
|
29
|
+
],
|
|
30
|
+
"scripts": {
|
|
31
|
+
"typecheck": "tsc --noEmit",
|
|
32
|
+
"test": "vitest run"
|
|
33
|
+
},
|
|
34
|
+
"devDependencies": {
|
|
35
|
+
"@earendil-works/pi-ai": "1.1.0",
|
|
36
|
+
"@earendil-works/pi-coding-agent": "1.1.0",
|
|
37
|
+
"@types/node": "26.2.0",
|
|
38
|
+
"typescript": "7.0.2",
|
|
39
|
+
"vitest": "4.1.11"
|
|
40
|
+
},
|
|
41
|
+
"overrides": {
|
|
42
|
+
"@earendil-works/chord": "1.1.0",
|
|
43
|
+
"@earendil-works/pi-ai": "1.1.0",
|
|
44
|
+
"@earendil-works/pi-mcp": "1.1.0",
|
|
45
|
+
"@earendil-works/pi-tui": "1.1.0",
|
|
46
|
+
"@earendil-works/pi-codemode": "1.1.0",
|
|
47
|
+
"@earendil-works/pi-agent-core": "1.1.0",
|
|
48
|
+
"@earendil-works/pi-telemetry": "1.1.0"
|
|
49
|
+
}
|
|
50
|
+
}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Create Amazon listings from your own words and your product's data — e.g. /listing-create US,DE 新品上架,数据在 /tenant/products/new-router/,FBA 发货
|
|
3
|
+
argument-hint: "<marketplaces> <your words, and where the product's data is>"
|
|
4
|
+
---
|
|
5
|
+
Create my listing in $1 from my words: ${@:2}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Write the standing instruction for watching one listing, from your own words — e.g. /listing-watch <ASIN> 以后每天帮我盯着这个 listing,有要改的告诉我,没事别吵
|
|
3
|
+
argument-hint: "<ASIN> <what you want, in your words>"
|
|
4
|
+
---
|
|
5
|
+
Write the standing instruction for my listing $1 from my words: ${@:2}
|
|
6
|
+
|
|
7
|
+
It says what to watch, how often, when to tell me and when to stay quiet, where to tell me, and whether you may change anything without asking me.
|