Agentic Commerce Audit Descriptions

Purpose

Drills into the description dimension of the Agentic Commerce Spec score. AI shopping agents do not parse marketing copy the way humans do — they extract structured facts: materials, dimensions, use cases, compatibility, target persona. Descriptions that read beautifully for humans can still be invisible to AI agents if they lack these structured signals.

This skill surfaces:

• Descriptions below the recommended word count (20+ words for AI parseability)
• Descriptions missing use-case language ("perfect for", "designed for", "works with")
• Descriptions missing measurement/dimension data
• Descriptions missing material/composition data
• Descriptions that are duplicate or near-duplicate across products

Prerequisites

• Authenticated Shopify CLI session: shopify auth login --store
• API scopes: read_products

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | store | string | yes | — | Store domain | | format | string | no | human | Output format: human or json | | limit | integer | no | 250 | Max products to audit | | minwords | integer | no | 20 | Minimum description word count to consider "AI-parseable" | | flagduplicates | bool | no | true | Flag products with near-duplicate descriptions |

Workflow Steps

1. OPERATION: products — query with description fields only (lighter than full audit)

1. For each product description:

• Strip HTML, count words
• Detect use-case language via keyword pattern matching (perfect for|designed for|ideal for|works with|compatible with|suitable for)
• Detect measurements via regex for dimensions (\d+(?:\.\d+)?\s*(?:cm|mm|in|inches|kg|lb|oz))
• Detect materials via vertical-specific keyword lists (e.g., apparel: cotton, wool, polyester; home: oak, stainless steel)

1. Flag duplicates if flag_duplicates: true: compute SHA-256 of description text → group products by hash. Surface groups of 2+ products sharing identical descriptions.

1. Output ranked report:

• Critical: descriptions Read-only operation. No mutations.

GraphQL Operations

# products:query — focused on description fields
query DescriptionAudit($first: Int!, $after: String) {
  products(first: $first, after: $after) {
    edges {
      node {
        id
        title
        descriptionHtml
        productType
        vendor
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Companion fix

After this audit, the [agentic-commerce-generate-ai-descriptions](../../catalog-fix/agentic-commerce-generate-ai-descriptions/SKILL.md) skill can auto-rewrite flagged descriptions, preserving brand voice while injecting the missing structured signals.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: commerce-agentic
• Source: commerce-agentic/agentic-commerce-skills
• License: MIT

Install and usage instructions live in the source repository linked above.