Skill: hussainpatan9/seo-product-auditor (version 1.0.0)

# SEO Product Auditor ## Overview Scan a Shopify or WooCommerce store's product listings and score each one against 10 SEO criteria. Identify the weakest listings, generate a prioritised fix list, and optionally rewrite poor titles, descriptions, and tags in place — in UK English. Designed as a companion to the Shopify Product Uploader skill. Run the audit first to find what needs fixing, then use the Uploader skill to push the rewrites. --- ## Trigger Phrases Activate this skill when the user says any of the following (or similar): Audit triggers: - "audit my store" / "audit my products" - "check my listings" / "check my SEO" - "find weak listings" / "which products have bad SEO" - "SEO report" / "product SEO score" - "audit [product name]" — single product audit - "what's wrong with my listings" - "find products with no description" - "find products with missing images" Fix triggers (after audit): - "fix the top 10" / "rewrite the worst listings" - "fix [product name]" - "apply all suggested fixes" - "rewrite description for [product]" - "improve the title on [product]" --- ## Configuration (ask on first use if not set) Check memory for the following before running any workflow. If missing, ask the user once and store under `seo_audit_config`: ``` STORE_PLATFORM # shopify | woocommerce SHOPIFY_STORE_HANDLE # e.g. my-store (Shopify only) SHOPIFY_ACCESS_TOKEN # starts with shpat_ (Shopify only) WC_DOMAIN # e.g. mystore.co.uk (WooCommerce only) WC_CONSUMER_KEY # ck_xxx (WooCommerce only) WC_CONSUMER_SECRET # cs_xxx (WooCommerce only) SHOPIFY_API_VERSION # Default: 2025-01 STORE_NAME # Used in SEO meta title suffix LANGUAGE # Default: en-GB (UK English) CURRENCY # Default: GBP ``` Reuse credentials already stored in memory from the Shopify Product Uploader or Order & Returns Manager skills — do not ask again if already set. Store under `seo_audit_config` separately so audits are tracked independently. --- ## SEO Scoring Criteria Score each product out of 100. Each criterion has a maximum point value. Apply these consistently across every workflow. | # | Criterion | Max points | How to score | |---|-----------|-----------|-------------| | 1 | Title length | 15 | 40–70 chars = 15 · 30–39 or 71–80 = 8 · <30 or >80 = 0 | | 2 | Title contains primary keyword | 10 | Keyword in first 40 chars = 10 · keyword present but not first = 5 · missing = 0 | | 3 | Description length | 15 | 150–300 words = 15 · 80–149 words = 8 · 50–79 = 4 · <50 or none = 0 | | 4 | Description contains keyword | 10 | Keyword in first sentence = 10 · keyword present but not first = 5 · missing = 0 | | 5 | Tags present | 10 | 5–10 tags = 10 · 2–4 tags = 5 · 0–1 tags = 0 | | 6 | Images present | 15 | 3+ images = 15 · 2 images = 10 · 1 image = 5 · 0 = 0 | | 7 | SEO meta title set | 10 | Present and 30–60 chars = 10 · present but wrong length = 5 · missing = 0 | | 8 | SEO meta description set | 10 | Present and 120–155 chars = 10 · present but wrong length = 5 · missing = 0 | | 9 | Alt text on images | 5 | All images have alt text = 5 · some = 3 · none = 0 | | 10 | UK English spelling | 0 (flag only) | Flag if US spellings detected: color, gray, aluminum, center, organize | Score bands: - 85–100 = ✅ Good — no action needed - 65–84 = 🟡 Fair — worth improving - 40–64 = 🟠 Weak — should be fixed soon - 0–39 = 🔴 Poor — fix immediately Primary keyword inference: if no keyword is explicitly provided by the user, infer it from the product's `product_type` field first, then from the most specific tag (prefer multi-word descriptive tags over single generic ones), then fall back to the first 1–2 meaningful nouns in the title. Do NOT infer the keyword from the full title and then check if the title contains it — this always scores 10/10 and defeats the purpose of criterion 2. Examples: - `product_type: "Scarves"`, tags: `["merino-wool", "winter"]` → keyword: "merino wool scarf" - `product_type: ""`, tags: `["leather-wallet", "bifold"]` → keyword: "leather wallet" - `product_type: ""`, tags: `["pot"]`, title: "Blue Ceramic Plant Pot" → keyword: "ceramic plant pot" --- ## Workflow A — Full Store Audit Use when user says "audit my store", "SEO report", or similar. ### Step 1 — Fetch all products Shopify — paginate through all products: ``` GET https://{store}.myshopify.com/admin/api/{version}/products.json?limit=250&status=active&fields=id,title,body_html,tags,images,product_type,handle ``` `status=active` returns only published products. This is the correct default for an SEO audit — archived and draft products are excluded. - To include drafts (e.g. to fix SEO before publishing): add `&status=draft` as a second request and merge results, or use `status=any` if the user asks. - Archived products are intentionally excluded — they are not indexed by search engines. If the response `Link` header contains `rel="next"`, continue paginating until all pages are retrieved. Store total product count. **Important:** `metafields` cannot be included in the `fields` parameter of the products bulk endpoint — Shopify silently ignores it. Metafields must be fetched separately per product after the bulk fetch: ``` GET .../products/{id}/metafields.json?namespace=global&key=title_tag GET .../products/{id}/metafields.json?namespace=global&key=description_tag ``` For large stores (250+ products), batch these metafield fetches with a 0.5s delay between requests to stay within Shopify's rate limits. Show progress to the user: `Fetching SEO data... 47/84 products` **HTML stripping for word count:** `body_html` contains HTML markup. Before counting words for criterion 3, strip all HTML tags: - Remove all content between `<` and `>` characters - Collapse whitespace - Count remaining space-separated tokens Example: `<p>Great scarf</p>` → `"Great scarf"` → 2 words (not 3) WooCommerce: ``` GET https://{WC_DOMAIN}/wp-json/wc/v3/products?per_page=100&page={n}&status=publish Authorization: Basic {base64(key:secret)} ``` Paginate using both response headers: - `X-WP-Total` — total number of products - `X-WP-TotalPages` — total number of pages Continue fetching until page number exceeds `X-WP-TotalPages`. WooCommerce stores Yoast SEO data in `yoast_head_json.title` and `yoast_head_json.description` if Yoast SEO is installed — check these fields. ### Step 2 — Score every product Apply the 10-criterion scoring table to each product. Calculate total score out of 100. Track which specific criteria each product fails. ### Step 3 — Aggregate and report Sort products by score ascending (worst first). ``` 📊 SEO Audit — {store_name} {date} Total products scanned: {n} Average SEO score: {avg}/100 Score distribution: ✅ Good (85–100): {n} products ({pct}%) 🟡 Fair (65–84): {n} products ({pct}%) 🟠 Weak (40–64): {n} products ({pct}%) 🔴 Poor (0–39): {n} products ({pct}%) Top issues across store: · Missing SEO meta description: {n} products · Description under 50 words: {n} products · Missing or too few images: {n} products · No tags: {n} products · Title too short or too long: {n} products Bottom 10 — worst scoring products: 1. {title} {score}/100 🔴 2. {title} {score}/100 🔴 3. {title} {score}/100 🔴 ... Reply: "fix top 10" — rewrite and push the 10 worst listings "fix [name]" — fix a specific product "full list" — see every product with its score "export" — get a CSV of all scores ``` ### Step 4 — Store audit results in memory Store the full scored product list in memory under `last_audit_{store_handle}`: ```json { "date": "{ISO date}", "product_count": {n}, "average_score": {avg}, "products": [ { "id": {id}, "title": "{title}", "score": {n}, "tags": "{comma_separated_tags_string}", "failures": ["{criterion_name}", ...] }, ... ] } ``` Include `tags` in each product entry so Workflow C can read current tags from memory without an extra API call. The `failures` array uses criterion names matching the scoring table (e.g. `"title_length"`, `"meta_description"`, `"images"`) so Workflow E can filter without re-fetching. --- ## Workflow B — Single Product Audit Use when user says "audit [product name]" or "check the SEO on [product]". ### Step 1 — Find the product Search by title: ``` GET .../products.json?title={search_term}&limit=5&fields=id,title,body_html,tags,images,product_type,handle,status ``` If multiple matches, show compact list and ask user to confirm. ### Step 2 — Fetch metafields (two separate calls) ``` GET .../products/{id}/metafields.json?namespace=global&key=title_tag GET .../products/{id}/metafields.json?namespace=global&key=description_tag ``` Check `response.metafields[0].value` in each response for the current SEO values. ### Step 3 — Score and report in detail ``` 🔍 SEO audit — "{product title}" Score: {score}/100 {band_emoji} Criterion breakdown: Title length ({n} chars) {pts}/15 {status} Keyword in title {pts}/10 {status} Description length ({n} words) {pts}/15 {status} Keyword in description {pts}/10 {status} Tags ({n} tags) {pts}/10 {status} Images ({n} images) {pts}/15 {status} SEO meta title {pts}/10 {status} SEO meta description {pts}/10 {status} Image alt text {pts}/5 {status} UK English — {✅ or ⚠️ US spellings found} ──────────────────────────────────────────── Total {score}/100 {band_emoji} Issues found: 🔴 No SEO meta description set 🟠 Description is only {n} words — aim for 150–300 🟡 Only {n} tags — add {n} more for better discoverability Suggested fixes: · Rewrite title: "{suggested_title}" · Add tags: {suggested_tags} Reply "fix it" to apply all changes, or tell me which to apply first. ``` Status labels: ✅ = full points · 🟡 = partial · 🔴 = zero --- ## Workflow C — Fix a Product (Rewrite and Push) Triggered by: "fix it", "fix [product name]", "fix top 10", "apply all fixes" ### Step 1 — Determine scope - "fix [product]" → single product (Workflow B result or search) - "fix top 10" → top 10 from last audit in memory - "apply all fixes" → all products scored 🔴 or 🟠 from last audit If no recent audit in memory, run Workflow A first. ### Step 2 — Generate improvements in batches For bulk fixes (top 10 or more), generate content in batches of 3 products at a time to manage token usage and allow incremental review. Do not generate all 10 descriptions before showing any output — the user should see progress. For single-product fixes, generate all fields at once before the preview. For each product being fixed, only generate the fields that are actually failing: - Criterion 1 or 2 failing → rewrite title - Criterion 3 or 4 failing → rewrite description - Criterion 5 failing → generate additional tags - Criterion 7 failing → generate SEO meta title - Criterion 8 failing → generate SEO meta description - Criterion 9 failing → generate alt text for each image missing it Do not rewrite fields that are already scoring full marks. **Title** (if score < full marks on criteria 1 or 2): - 40–70 characters - Primary keyword in first 40 characters - Sentence case — no ALL CAPS - Format: [Primary Keyword] | [Secondary Descriptor] | [Material/Brand if relevant] - UK English: colour not color, grey not gray **Description** (if score < full marks on criteria 3 or 4): - 150–300 words - HTML formatted: `<p>` for paragraphs, `<ul><li>` for specs - Open with primary benefit — not "This product is..." or "Introducing..." - Include primary keyword naturally in first sentence - Second paragraph: materials, dimensions, specs - Third paragraph: variants, care instructions - Close with subtle call to action - UK English throughout **Tags** (if score < full marks on criterion 5): - Generate 5–10 tags if fewer than 5 exist - Mix: product type, material, use case, audience, season/occasion - Lowercase, hyphenated for multi-word: wool-scarf, gift-ideas - Do not duplicate existing good tags — only add missing ones **SEO meta title** (if criterion 7 = 0): - 30–60 characters - Format: {primary keyword} — {store name} - If store name would push over 60 chars, use keyword only **SEO meta description** (if criterion 8 = 0): - 120–155 characters exactly - Benefit-led: start with what the product does, not what it is - Include a soft call to action: "Free UK delivery on orders over £X" - No keyword stuffing ### Step 3 — Preview before pushing Show a before/after summary. Never push without user confirmation. For single product: ``` ✏️ Proposed fixes — "{current title}" TITLE Before: {current_title} ({n} chars) After: {new_title} ({n} chars) ✅ DESCRIPTION Before: {n} words — {first 80 chars of current}... After: {n} words — {first 80 chars of new}... TAGS Adding: {new_tags_list} Keeping: {existing_good_tags} SEO META TITLE Before: {current or "not set"} After: {new} ({n} chars) ✅ SEO META DESCRIPTION Before: {current or "not set"} After: {new} ({n} chars) ✅ Apply these changes? YES / adjust / skip ``` For bulk (top 10 or all): ``` ✏️ Bulk fixes ready — {n} products Products to be updated: 1. "{title}" {old_score}→{projected_score} (+{gain} pts) 2. "{title}" {old_score}→{projected_score} ... Estimated score improvement: avg +{gain} points across {n} products Apply all? YES / review each one first / skip ``` ### Step 4 — Push to Shopify For each product, update in sequence with 0.5s delay between requests. Update title and description: ``` PUT https://{store}.myshopify.com/admin/api/{version}/products/{id}.json { "product": { "id": {id}, "title": "{new_title}", "body_html": "{new_description_html}" } } ``` Update tags (use audit memory first; only re-fetch if audit data is stale or missing): If `last_audit_{store_handle}` memory has the product's current tags (and the audit is from this session), use those directly — no extra GET needed. If audit data is missing or stale, fetch current tags: ``` GET .../products/{id}.json?fields=id,tags ``` Parse the `tags` field as a comma-separated string. Split on `", "` (comma followed by a space) — not just `","` — to handle tags correctly: ``` "merino-wool, wool-scarf, gift-ideas" → ["merino-wool", "wool-scarf", "gift-ideas"] ``` Deduplicate: compare new tags against existing (case-insensitive). Only add tags not already present. Then write the merged list back: ``` PUT .../products/{id}.json { "product": { "id": {id}, "tags": "{merged_comma_space_separated_tags}" } } ``` If existing tags is empty string, write new tags only (no leading comma or space). Update image alt text (for each image missing alt text): ``` PUT .../products/{product_id}/images/{image_id}.json { "image": { "id": {image_id}, "alt": "{descriptive alt text}" } } ``` Generate alt text as: `"{short product name} in {colour} — {view}"` Example: `"Merino wool scarf in Navy — front draped view"` Keep under 125 characters. Never start with "Image of" or "Photo of". Fetch current image IDs from the product data already retrieved in Step 1. Update SEO meta title and description via metafields: ``` GET .../products/{id}/metafields.json?namespace=global&key=title_tag ``` If exists — update (use the product-scoped path): ``` PUT https://{store}.myshopify.com/admin/api/{version}/products/{product_id}/metafields/{metafield_id}.json { "metafield": { "id": {metafield_id}, "value": "{seo_title}", "type": "single_line_text_field" } } ``` If not exists — create: ``` POST .../products/{id}/metafields.json { "metafield": { "namespace": "global", "key": "title_tag", "value": "{seo_title}", "type": "single_line_text_field" } } ``` Repeat for `description_tag`. ### Step 5 — Confirm results and update memory Write to memory under `last_fixed_{store_handle}`: ```json { "date": "{ISO date}", "product_ids": [{id1}, {id2}, ...], "old_scores": { "{id}": {score}, ... }, "new_scores": { "{id}": {score}, ... } } ``` This enables Workflow F (re-audit) to rescore only the changed products. Single product confirm: ``` ✅ {product title} — updated Score: {old}/100 → {new}/100 (+{gain} pts) {new_band} Admin: https://{store}.myshopify.com/admin/products/{id} ``` Bulk confirm: ``` ✅ Bulk fix complete — {n} products updated Before avg: {old_avg}/100 After avg: {new_avg}/100 (+{gain} pts) Updated: {n} ✅ Failed: {n} ❌ (if any — list title and error) Run "re-audit" to rescore these products. ``` Also update `last_audit_{store_handle}` in memory to reflect new scores for any products that were fixed, so future targeted scans use current data. --- ## Workflow D — Export Audit as CSV Triggered by: "export", "download scores", "give me a CSV of all scores" Generate a CSV from the last stored audit in memory. **CSV escaping rules — apply to every cell:** - Wrap all string values in double-quotes: `"Merino Wool Scarf"` - Escape any double-quote within a value by doubling it: `"Scarf, ""Red"" Edition"` - Numbers (scores, point values) do not need quoting Header row: ``` ID,Title,Score,Band,Title Score,Desc Score,Tags Score,Images Score,Meta Title Score,Meta Desc Score,Alt Text Score,US Spellings,Admin URL ``` Data rows (one per product): ``` {id},"{escaped_title}",{total},"{band}",{pts},{pts},{pts},{pts},{pts},{pts},{pts},{true/false},"https://{store}.myshopify.com/admin/products/{id}" ``` Save to workspace as `seo_audit_{store_handle}_{YYYY-MM-DD}.csv` and confirm path. If no recent audit in memory: ``` No audit found in memory. Run "audit my store" first, then I can export the results. ``` --- ## Workflow E — Targeted Issue Scan Use when user asks about a specific problem rather than a full audit. Triggered by: - "find products with no description" → filter score criterion 3 = 0 - "find products with no images" → filter criterion 6 = 0 - "find products with no SEO meta" → filter criteria 7 or 8 = 0 - "find products with no tags" → filter criterion 5 = 0 - "find products with US spellings" → filter criterion 10 = flagged - "find products with short titles" → filter criterion 1 = 0 - "find products with titles over 70 characters" → filter criterion 1 partial Pull from last audit in memory if available (no re-fetch needed). If no audit in memory, fetch products first (Workflow A Step 1). Report format: ``` 🔍 Products with no SEO meta description — {n} found 1. "{title}" {score}/100 https://{store}.myshopify.com/admin/products/{id} 2. "{title}" {score}/100 https://{store}.myshopify.com/admin/products/{id} ... Reply "fix these" to generate and push meta descriptions for all {n}. ``` --- ## Workflow F — Re-audit After Fixes Triggered by: "re-audit", "check scores again", "what's my SEO score now" Read `last_fixed_{store_handle}` from memory to get the list of product IDs changed in the last fix session, plus their `old_scores`. Re-fetch those products from the API to get their current state: ``` GET .../products/{id}.json?fields=id,title,body_html,tags,images,product_type,handle GET .../products/{id}/metafields.json?namespace=global&key=title_tag GET .../products/{id}/metafields.json?namespace=global&key=description_tag ``` Apply the full scoring rubric to the freshly fetched data. Compare new scores against `last_fixed.old_scores` for the before/after view. Update `last_audit_{store_handle}` in memory with the new scores. ``` 📊 Re-audit — {n} products rescored "{title short}" {old_score} → {new_score} +{gain} {band} "{title short}" {old_score} → {new_score} +{gain} {band} "{title short}" {old_score} → {new_score} +{gain} {band} Store average: {old_avg}/100 → {new_avg}/100 (+{gain} pts) {If any product didn't improve as expected} ⚠️ "{title}" only gained {gain} pts — images score is still capped at 5/15 because only 1 image is present. Add 2 more images to reach full marks. ``` --- ## UK English Enforcement When generating or rewriting any content, always apply: | ✅ Use | ❌ Never use | |--------|------------| | colour | color | | grey | gray | | aluminium | aluminum | | centre | center | | organise | organize | | practise (verb) | practice (verb) | | fibre | fiber | | licence (noun) | license (noun) | | metres / centimetres | meters / centimeters | | £ GBP | $ USD | When scanning existing descriptions for US spellings (criterion 10), check for all of the above. Flag the specific words found, e.g.: `⚠️ US spellings: "color" (×2), "aluminum" (×1) — will fix on rewrite` --- ## SEO Content Quality Rules Apply when generating titles, descriptions, and meta content: **Titles:** - 40–70 characters — hard limit - Primary keyword in first 40 characters - Sentence case — never ALL CAPS - No special characters except pipes `|` and ampersands `&` - No filler: "best", "amazing", "premium", "high quality" - Include material, size range, or colour set if space allows **Descriptions:** - 150–300 words — this range is optimal for both SEO and conversion - Open with a benefit statement, not a product definition - Include primary keyword naturally in the first sentence - Use HTML: `<p>` for paragraphs, `<ul><li>` for bullet specs - Metric dimensions first (cm/mm/kg), imperial in brackets if relevant - End with a single, low-pressure call to action - Never invent specifications not provided — flag gaps to user **Tags:** - 5–10 tags per product - Mix: product type, material, use case, occasion, target audience - All lowercase, multi-word tags hyphenated - Never duplicate words already in the title - Never use single-letter or generic tags like "new", "sale" **SEO meta title:** - 30–60 characters (Google typically displays ~60) - Format: {Primary Keyword} — {Store Name} - If brand name pushes over 60, use keyword + separator only **SEO meta description:** - 120–155 characters (Google truncates at ~155) - Benefit-led first half, soft CTA second half - Include one keyword naturally - Example (140 chars): "Pure Merino wool scarf in Navy and Forest Green — 180cm long, warm without bulk. Free UK delivery on orders over £40. Shop now." --- ## Error Handling | Error | Cause | Action | |-------|-------|--------| | 401 Unauthorized | Invalid/expired token | Ask user to regenerate in Shopify Admin → Apps | | 403 Forbidden | Missing scope | State missing scope: `read_products` or `write_products` | | 404 Product not found | Wrong ID or deleted product | Skip and note in report | | 429 Rate limited | Too many requests | Auto-retry after 2s, up to 3× — for bulk audits add 0.5s delay between fetches | | 503 Shopify outage | Service down | Wait 30s, retry once, then report | Required Shopify API scopes: - `read_products` — fetch product data, images, and tags for auditing - `write_products` — push rewritten titles, descriptions, tags, image alt text, and product metafields (sufficient for `global.title_tag` and `global.description_tag` on API versions 2023-04+) - `write_metafields` — explicit metafield write access; add this if you receive a 403 when updating SEO meta title or description Note: `read_metaobjects` and `write_metaobjects` are for Shopify Metaobjects (a different feature). Do not use them here — they will not grant access to product metafields. Use `write_products` first; add `write_metafields` only if needed. --- ## WooCommerce Support When STORE_PLATFORM = woocommerce: Base URL: `https://{WC_DOMAIN}/wp-json/wc/v3` Auth: `Authorization: Basic {base64(WC_CONSUMER_KEY:WC_CONSUMER_SECRET)}` **Fetch products:** ``` GET /products?per_page=100&page={n}&status=publish ``` **Update product:** ``` PUT /products/{id} { "name": "{new_title}", "description": "{new_description_html}", "tags": [{ "name": "{tag}" }, ...] } ``` **WooCommerce SEO meta fields** (Yoast SEO plugin): Yoast stores meta in post meta — not directly accessible via WooCommerce REST API. If the user has Yoast installed, advise them to update SEO title/description directly in the Yoast panel in wp-admin, or via the Yoast REST API if enabled. Flag this limitation clearly rather than silently skipping. **WooCommerce images (alt text update):** ⚠️ The WooCommerce `PUT /products/{id}` endpoint **replaces** the entire `images` array. Sending only the image you want to update will delete all other images. Always fetch the full current images array first: ``` GET /products/{id}?_fields=id,images ``` Then update the specific image's alt text within the full array and PUT the complete array back: ``` PUT /products/{id} { "images": [ { "id": {image_1_id}, "src": "{url_1}", "alt": "{updated_alt}" }, { "id": {image_2_id}, "src": "{url_2}", "alt": "{existing_alt_2}" }, { "id": {image_3_id}, "src": "{url_3}", "alt": "{existing_alt_3}" } ] } ``` Include every image in the product, not just the one being updated. --- ## Memory Instructions Store after each audit session: - `last_audit_{store_handle}`: full scored product list with date, scores, failures - `last_fixed_{store_handle}`: list of product IDs updated in the last fix session - `store_avg_score_{store_handle}`: running average score — compare across audits to show progress over time - `common_issues_{store_handle}`: the most frequent failure criteria — surface these proactively ("your store's biggest SEO gap is still missing meta descriptions on 34 products") --- ## Tone & Communication - 📊 full audit · 🔍 single product · ✏️ fix preview · ✅ applied · 🔴 poor · 🟠 weak · 🟡 fair · 🟢 good - Keep score reports scannable — use consistent column alignment - For bulk operations: always show count and projected improvement before pushing - Never push changes without explicit user confirmation (YES or equivalent) - When a product is already scoring well (85+), acknowledge it: "This one is already strong — no changes needed" - When suggesting tag additions, explain briefly why each tag helps: don't just list them - If user is clearly experienced, skip explanations and lead with data - Dates in DD MMM YYYY format — never MM/DD/YYYY

path: CONFIG.md
content: # SEO Product Auditor — Setup Guide

## Step 1 — API scopes needed

If you already have the Shopify Product Uploader or Order & Returns Manager installed,
you likely have these already. Check and add any missing ones:

Go to Shopify Admin → Settings → Apps → your custom app → Configure Admin API scopes.

| Scope | Why it's needed |
|-------|----------------|
| `read_products` | Fetch product titles, descriptions, tags, images for auditing |
| `write_products` | Push rewritten titles, descriptions, tags, image alt text, and product metafields |
| `write_metafields` | Explicit metafield write access — add only if you receive a 403 when updating SEO meta title or description |

Note: `read_content`, `write_content`, `read_metaobjects`, and `write_metaobjects`
are not the correct scopes for product metafields. Use `write_products` as the
primary scope — it covers `global.title_tag` and `global.description_tag` on
API versions 2023-04 and later. Add `write_metafields` only if needed.

---

## Step 2 — Configure the skill

If you've already set up the Shopify Product Uploader, the skill will reuse your
existing store credentials automatically.

If this is your first skill, send your OpenClaw bot:
```
Set my store for SEO audit:
Store: my-store-name
[REDACTED_SECRET]
Store name: The Wool House
```

---

## Step 3 — Run your first audit

```
audit my store
```

The skill will scan all products, score them against 10 SEO criteria, and show you
the worst-performing listings with a prioritised fix list.

For large stores (500+ products), allow 3–5 minutes for the initial scan.

---

## Step 4 — Fix the worst listings

```
fix top 10
```

Reviews proposed changes before pushing. Nothing is updated without your confirmation.

---

## WooCommerce setup

Send:
```
Set my WooCommerce for SEO audit:
Platform: woocommerce
Domain: mystore.co.uk
Consumer key: ck_xxxxxxxxxxxxxxxxxxxx
Consumer [REDACTED_SECRET]
Store name: My Store Name
```

Note: WooCommerce SEO metafields (title, description) require the Yoast SEO plugin.
If Yoast is installed, meta updates will be flagged but must be applied via the Yoast
REST API or wp-admin — not directly via the WooCommerce REST API.

---

## Scoring explained

Each product is scored out of 100 across 10 criteria:

| Criterion | Max | Quick guide |
|-----------|-----|-------------|
| Title length | 15 | Aim for 40–70 characters |
| Keyword in title | 10 | Primary keyword in first 40 chars |
| Description length | 15 | 150–300 words is the sweet spot |
| Keyword in description | 10 | Keyword in the first sentence |
| Tags | 10 | 5–10 tags, not 0–2 |
| Images | 15 | 3+ images per product |
| SEO meta title | 10 | Set it — most stores haven't |
| SEO meta description | 10 | Set it — most stores haven't |
| Image alt text | 5 | Helps accessibility and image search |
| UK English | — | Flag only — fixed on rewrite |

**Score bands:**
- 85–100 ✅ Good
- 65–84  🟡 Fair
- 40–64  🟠 Weak
- 0–39   🔴 Poor — fix immediately

---

## Troubleshooting

**"Products not loading"**
→ Check `read_products` scope is enabled on your Shopify custom app.

**"SEO meta title/description shows as not set even though I set it in Shopify"**
→ Some themes store SEO data in theme metafields rather than the global namespace.
The skill looks in `global.title_tag` and `global.description_tag` — if your
theme uses different keys, the skill may not detect them. Run a manual check
in Shopify Admin → Products → [product] → Search engine listing preview.

**"Tags are being replaced instead of added"**
→ This should not happen — the skill reads existing tags before writing and
merges them. If it occurs, reply "undo tags on [product]" and the skill will
restore the previous tags from the audit memory.

**"Audit is taking a long time"**
→ Shopify rate limits to 2 API requests/second on Basic plan. A store with 500
products and individual metafield fetches will take approximately 8–10 minutes.
This is normal. The skill will report progress as it goes.

**"WooCommerce SEO meta not updating"**
→ WooCommerce REST API does not natively support Yoast SEO fields. Update these
directly in wp-admin → Products → [product] → Yoast SEO panel.


path: EXAMPLES.md
content: # SEO Product Auditor — Examples

These examples show expected input/output for each workflow.
The agent should match or exceed this quality and consistency.

---

## Example 1 — Full store audit

**User:** "audit my store"

**Agent:**
```
📊 SEO Audit — The Wool House
12 Apr 2026

Total products scanned:  84
Average SEO score:       58/100

Score distribution:
  ✅ Good  (85–100):   9 products  (11%)
  🟡 Fair  (65–84):   22 products  (26%)
  🟠 Weak  (40–64):   31 products  (37%)
  🔴 Poor  (0–39):    22 products  (26%)

Top issues across store:
  · Missing SEO meta description:  61 products
  · Description under 50 words:    28 products
  · Fewer than 5 tags:             34 products
  · Missing or too few images:     19 products
  · Title too short (<30 chars):    8 products

Bottom 10 — worst scoring:
  1. "Scarf"                           12/100  🔴
  2. "Blue pot"                         18/100  🔴
  3. "Leather wallet brown"             19/100  🔴
  4. "Set of 3 tea towels"              28/100  🔴
  5. "Organic Cotton Throw Blanket"     31/100  🔴
  6. "Bamboo Board"                     34/100  🔴
  7. "Glass cafetiere"                  38/100  🔴
  8. "Silver necklace"                  39/100  🔴
  9. "Kids wooden toy"                  41/100  🟠
  10. "Merino Hat - Grey"               44/100  🟠

Reply:
  "fix top 10"   — rewrite and push the 10 worst listings
  "fix [name]"   — fix a specific product
  "full list"    — see all 84 products with scores
  "export"       — download scores as CSV
```

---

## Example 2 — Single product audit

**User:** "audit the leather wallet"

**Agent:**
```
🔍 SEO audit — "Leather wallet brown"
Score: 19/100 🔴

Criterion breakdown:
  Title length (20 chars)            0/15  🔴 Too short — aim for 40–70
  Keyword in title                   5/10  🟡 "leather wallet" present but not leading
  Description length (38 words)      4/15  🟠 Too short — aim for 150–300 words
  Keyword in description             5/10  🟡 Present but not in first sentence
  Tags (1 tag)                       0/10  🔴 Only 1 tag — add at least 4 more
  Images (1 image)                   5/15  🟡 Only 1 image — add 2+ more
  SEO meta title                     0/10  🔴 Not set
  SEO meta description               0/10  🔴 Not set
  Image alt text                     0/5   🔴 No alt text on any image
  UK English                         —     ✅ No US spellings found
  ──────────────────────────────────────────
  Total                             19/100  🔴

Issues found:
  🔴 Title is only 20 chars and doesn't lead with the primary keyword
  🔴 No SEO meta title or description set
  🔴 No image alt text
  🔴 Only 1 tag — nearly invisible in search and collections
  🟠 Description at 38 words is too thin — need 150+ for SEO value

Suggested title: "Slim Leather Bifold Wallet | 6 Card Slots | Brown, Black & Tan"

Reply "fix it" to apply all changes, or tell me which to apply first.
```

---

## Example 3 — Fix single product

**User:** "fix it"

**Agent:**
```
✏️ Proposed fixes — "Leather wallet brown"

TITLE
  Before: "Leather wallet brown" (20 chars) 🔴
  After:  "Slim Leather Bifold Wallet | 6 Card Slots | Brown, Black & Tan" (63 chars) ✅

DESCRIPTION
  Before: 38 words — "A genuine leather bifold wallet available in brown, black and tan..."
  After:  187 words — "Carry everything you need without the bulk. This slim bifold wallet
          is crafted from genuine full-grain leather that softens with use..."

TAGS
  Keeping:  leather-wallet
  Adding:   bifold-wallet, mens-wallet, slim-wallet, genuine-leather,
            card-holder, brown-leather, gift-for-him, fathers-day

SEO META TITLE
  Before: not set
  After:  "Slim Leather Bifold Wallet | Brown, Black & Tan" (48 chars) ✅

SEO META DESCRIPTION
  Before: not set
  After:  "Genuine leather bifold wallet with 6 card slots in Brown, Black
           & Tan. Slim profile, softens with use. Free UK delivery over £40." (140 chars) ✅

IMAGE ALT TEXT
  Image 1: adding alt "Slim leather bifold wallet in brown — front view"

Apply these changes? YES / adjust / skip
```

**User:** "yes"

**Agent:**
```
✅ "Leather wallet brown" — updated

Score:  19/100 → 92/100 (+73 pts) ✅ Good
Admin:  https://the-wool-house.myshopify.com/admin/products/7823456789
```

---

## Example 4 — Bulk fix top 10

**User:** "fix top 10"

**Agent:**
```
✏️ Bulk fixes ready — 10 products

Products to be updated:
  1. "Scarf"                           12 → 89 (+77 pts) ✅
  2. "Blue pot"                         18 → 84 (+66 pts) 🟡
  3. "Leather wallet brown"             19 → 92 (+73 pts) ✅
  4. "Set of 3 tea towels"              28 → 86 (+58 pts) ✅
  5. "Organic Cotton Throw Blanket"     31 → 81 (+50 pts) 🟡
  6. "Bamboo Board"                     34 → 88 (+54 pts) ✅
  7. "Glass cafetiere"                  38 → 85 (+47 pts) ✅
  8. "Silver necklace"                  39 → 79 (+40 pts) 🟡
  9. "Kids wooden toy"                  41 → 87 (+46 pts) ✅
  10. "Merino Hat - Grey"               44 → 90 (+46 pts) ✅

Estimated score improvement: store average 58 → 74/100 (+16 pts)

Apply all? YES / review each one first / skip
```

**User:** "yes"

**Agent:**
```
✅ Bulk fix complete — 10 products updated

Store average: 58/100 → 74/100 (+16 pts)

Updated:  10 ✅
Failed:    0

Run "re-audit" to rescore these products, or "full audit" to rescan the whole store.
```

---

## Example 5 — Targeted issue scan

**User:** "find products with no SEO meta description"

**Agent:**
```
🔍 Products with no SEO meta description — 61 found

Worst scoring first:
  1.  "Scarf"                      12/100  admin/products/78234...
  2.  "Blue pot"                    18/100  admin/products/78235...
  3.  "Leather wallet brown"        19/100  admin/products/78236...
  4.  "Set of 3 tea towels"         28/100  admin/products/78237...
  5.  "Organic Cotton Throw"        31/100  admin/products/78238...
  ...and 56 more

Reply "fix these" to generate and push meta descriptions for all 61.
Or "fix top 20" to start with the worst-scoring ones first.
```

---

## Example 6 — Export audit as CSV

**User:** "export"

**Agent:**
```
✅ Audit export ready

seo_audit_the-wool-house_12-Apr-2026.csv
84 products · saved to workspace

Columns: ID, Title, Score, Band, Title Score, Description Score,
Tags Score, Images Score, Meta Title Score, Meta Description Score,
Alt Text Score, US Spellings Found, Admin URL

File path: ~/.openclaw/workspace/seo_audit_the-wool-house_12-Apr-2026.csv
```

---

## Example 7 — Re-audit after fixes

**User:** "re-audit"

**Agent:**
```
📊 Re-audit — 10 products rescored

  "Slim Leather Bifold Wallet..."       19 → 92  +73 ✅
  "Merino Wool Scarf | Soft..."         12 → 89  +77 ✅
  "Ceramic Plant Pot | Matte..."        18 → 84  +66 🟡
  "Linen Tea Towel Set | Natural..."    28 → 86  +58 ✅
  "Organic Cotton Throw Blanket..."     31 → 81  +50 🟡
  "Bamboo Cutting Board | Small..."     34 → 88  +54 ✅
  "Glass Cafetiere 600ml..."            38 → 85  +47 ✅
  "Sterling Silver Bar Necklace..."     39 → 79  +40 🟡
  "Wooden Shape Sorter | Kids..."       41 → 87  +46 ✅
  "Merino Wool Hat | Charcoal Grey..."  44 → 90  +46 ✅

Store average: 58/100 → 74/100 (+16 pts) 🟡 Fair

9 of 10 products now scoring ✅ Good or 🟡 Fair.
Biggest remaining gap: 3 products still missing extra images (images score capped at 5/15).
```

---

## Example 8 — Product already scoring well

**User:** "audit the merino scarf"

**Agent:**
```
🔍 SEO audit — "Merino Wool Scarf | Soft Knit Winter Scarf | Navy & Green"
Score: 91/100 ✅ Good

Criterion breakdown:
  Title length (62 chars)            15/15  ✅
  Keyword in title                   10/10  ✅
  Description length (203 words)     15/15  ✅
  Keyword in description             10/10  ✅
  Tags (9 tags)                      10/10  ✅
  Images (3 images)                  15/15  ✅
  SEO meta title (52 chars)          10/10  ✅
  SEO meta description (138 chars)   10/10  ✅
  Image alt text                      4/5   🟡 1 of 3 images missing alt text
  UK English                          —     ✅ No US spellings
  ──────────────────────────────────────────
  Total                              91/100  ✅ Good

Only issue: 1 image is missing alt text.
Reply "fix it" to add the missing alt text (quick update — no content changes needed).
```

---

## Quality Benchmarks — Generated Content

When fixing products, always aim for this quality level:

| ✅ Good title | ❌ Bad title |
|-------------|------------|
| "Merino Wool Scarf \| Soft Knit Winter Scarf \| Navy & Green" (62 chars) | "Scarf" (5 chars) |
| "Slim Leather Bifold Wallet \| 6 Card Slots \| Brown, Black & Tan" (63 chars) | "Leather wallet brown" (20 chars) |
| "Bamboo Cutting Board \| Small, Medium & Large \| FSC Certified" (62 chars) | "Bamboo Board" (12 chars) |

| ✅ Good description opening | ❌ Bad description opening |
|--------------------------|--------------------------|
| "Wrap up in effortless warmth with this Merino wool scarf." | "This is a scarf made from Merino wool." |
| "Carry everything you need without the bulk." | "This product is a leather wallet." |
| "A clean, minimal plant pot that lets your greenery take centre stage." | "Introducing our new ceramic plant pot!" |

| ✅ Good tags | ❌ Bad tags |
|------------|-----------|
| merino-wool, wool-scarf, winter-accessories, unisex, navy, gift-ideas | scarf, blue, new |
| leather-wallet, bifold-wallet, mens-wallet, genuine-leather, gift-for-him | wallet, brown |


path: README.md
content: # 🔍 SEO Product Auditor — OpenClaw Skill

Scan your entire Shopify or WooCommerce store, score every product listing against
10 SEO criteria, and fix the worst offenders — all from a WhatsApp or Telegram message.

Companion to the Shopify Product Uploader skill. Run the audit to find what's broken,
then push the fixes without touching your browser.

## What it does

- **Full store audit** — scans all products, scores each one out of 100 across 10 criteria, identifies your top issues in seconds
- **Single product audit** — detailed breakdown of every criterion with specific suggestions
- **Auto-fix** — rewrites titles, descriptions, tags, SEO meta title, and meta description in UK English and pushes them directly to Shopify
- **Bulk fix** — fix your worst 10, 20, or all weak listings in one command
- **Targeted scans** — "find products with no SEO meta" · "find products with missing images" · "find products with US spellings"
- **Re-audit** — rescore updated products to confirm improvement
- **CSV export** — download all scores for reporting or client handoff

## Example usage

```
You:  audit my store
Bot:  📊 84 products scanned · avg score 58/100
      🔴 22 products scoring Poor · biggest issue: 61 missing meta descriptions
      Bottom 10: "Scarf" (12/100), "Blue pot" (18/100)...
      Reply "fix top 10" to start

You:  fix top 10
Bot:  ✏️ 10 products ready · avg score projected 58→74/100
      Apply all? YES / review each first

You:  yes
Bot:  ✅ 10 products updated · store avg now 74/100
```

## Scoring criteria

| Criterion | Max |
|-----------|-----|
| Title length (40–70 chars) | 15 |
| Keyword in title | 10 |
| Description length (150–300 words) | 15 |
| Keyword in description | 10 |
| Tags (5–10) | 10 |
| Images (3+) | 15 |
| SEO meta title | 10 |
| SEO meta description | 10 |
| Image alt text | 5 |
| UK English check | flag |

## Setup

Reuses credentials from the Shopify Product Uploader if already installed.
Otherwise: add `read_products`, `write_products`, `read_content`, `write_content` scopes
to your Shopify custom app. Full guide in `CONFIG.md`.

## Files

| File | Purpose |
|------|---------|
| `SKILL.md` | Full skill — 6 workflows, scoring rubric, fix logic, UK English rules |
| `EXAMPLES.md` | 8 real examples covering audit, fix, bulk fix, targeted scan, export |
| `CONFIG.md` | Setup guide, API scopes, scoring explained, troubleshooting |

## Platforms

- Shopify (all plans) — full support including SEO metafields
- WooCommerce — full audit support · meta updates require Yoast SEO plugin

## Works best with

- **Shopify Product Uploader** — upload new products with good SEO from day one
- **Order & Returns Manager** — complete e-commerce operations suite

## Notes

- Nothing is pushed without your explicit confirmation
- All generated content is in UK English (colour, grey, aluminium, etc.)
- Audit results stored in memory — ask follow-up questions without re-scanning
- Large stores (500+ products) take 8–10 minutes to scan fully


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)