amazon-catalog-auditor

name	amazon-catalog-auditor
description	Audit Amazon Category Listing Reports (CLRs) for catalog health issues. Use when analyzing CLR files (.xlsx/.xlsm), checking for missing attributes, RUFUS bullet optimization, title validation, or generating catalog audit reports. Supports JSON/CSV/NDJSON export, field masks, pagination, and agent-native workflows.

Amazon Catalog Auditor

Deprecated wrapper skill as of April 20, 2026. The maintained implementation now lives in amazon-catalog-cli. Route fixes, features, and new pull requests to https://github.com/BWB03/amazon-catalog-cli.

Audit Amazon Category Listing Reports using the amazon-catalog-cli tool. Identifies missing attributes, RUFUS bullet issues, title problems, and other catalog health concerns.

Overview

This skill is a legacy wrapper around the amazon-catalog-cli PyPI package. When a user asks to audit a CLR, check catalog health, or analyze Amazon listings, prefer the CLI directly where possible:

1. Locates the CLR file (uploaded or path provided)
2. Runs appropriate catalog queries
3. Parses and presents results in human-readable format
4. Provides actionable recommendations
5. Detects marketplace and flags non-US CLRs

Note: v2.0 of amazon-catalog-cli now includes a built-in MCP server (catalog mcp) and SKILL.md. For MCP-compatible clients (Claude Desktop, CLR Pro), the CLI itself is a first-class agent surface. This OpenClaw skill remains useful for OpenClaw-specific workflows.

v2.0.0 (Agent-First Redesign):

• MCP server - catalog mcp exposes tools for Claude Desktop and MCP clients
• JSON/stdin input - --json and --stdin flags for structured agent input
• Schema introspection - catalog schema --format json for auto-discovery
• Field masks - --fields sku,severity,details to reduce output
• Pagination - --limit and --offset for large catalogs
• NDJSON streaming - --format ndjson for line-by-line output
• Input validation - Rejects path traversal, injection, malformed input

v1.3.0:

• Marketplace detection - Auto-detects US/CA/UK/DE/etc from CLR
• Bullet awareness checks - Soft violations (excessive caps, problematic chars)
• 12 total queries

v1.2.0:

• Comprehensive bullet point validation (prohibited content, formatting)

v1.1.0:

• RUFUS tier scoring (Good/Fair/Weak/Critical)
• Catalog-wide RUFUS summary stats
• Automatic FBM/MFN duplicate filtering

When to Use This Skill

Use when user asks for:

• "Audit this CLR"
• "What's wrong with my Amazon catalog?"
• "Check for missing attributes"
• "Score my RUFUS bullet points"
• "Analyze this Category Listing Report"
• "What catalog issues should I fix first?"

Quick Start

Installation Check

The tool should already be installed. Verify:

catalog --version

If not installed:

pip3 install amazon-catalog-cli

Basic Usage

# Full scan (all 12 queries)
catalog scan <clr-file>

# Specific query
catalog check missing-attributes <clr-file>

# JSON output for parsing
catalog scan <clr-file> --format json

Agent-Optimized Usage (v2.0)

# JSON with field mask and limit (recommended for agents)
catalog scan <clr-file> --format json --fields sku,severity,details --limit 20

# Structured JSON input
catalog scan --json '{"file": "<clr-file>", "queries": ["missing-attributes"], "limit": 10}'

# Piped input
echo '{"file": "<clr-file>"}' | catalog scan --stdin --format json

# NDJSON streaming for large results
catalog scan <clr-file> --format ndjson --limit 50

# Schema introspection (discover available queries and params)
catalog schema --format json

Available Queries

The tool provides 12 built-in queries:

Attribute Audits

1. missing-attributes - Required fields missing
2. missing-any-attributes - All missing fields (required + conditional)
3. new-attributes - Unused template fields

Content Quality

4. rufus-bullets - RUFUS AI optimization scoring
5. bullet-prohibited-content - Prohibited chars, emojis, claims, placeholders in bullets
6. bullet-formatting - Capitalization, length, punctuation rules
7. bullet-awareness - Soft violations (excessive caps, problematic special chars)
8. long-titles - Titles exceeding 200 characters
9. title-prohibited-chars - Prohibited characters in titles
10. prohibited-chars - Basic character validation (title/brand)

Catalog Structure

11. product-type-mismatch - Product type / item type keyword mismatches
12. missing-variations - Products that should be variations

Workflow

1. Get CLR File Path

# User uploaded file
clr_path = "/path/to/uploaded/file.xlsx"

# Or user provides path
"Audit this: /Users/username/Downloads/my-clr.xlsx"

2. Run Appropriate Analysis

Full Audit (Most Common):

catalog scan <clr-path> --format json --fields sku,severity,details --limit 50

Specific Issue:

catalog check rufus-bullets <clr-path> --format json --limit 20

Quick Summary:

catalog scan <clr-path>

Structured Input (v2.0):

catalog scan --json '{"file": "<clr-path>", "queries": ["missing-attributes", "rufus-bullets"], "fields": ["sku", "severity", "details"], "limit": 20}'

3. Parse JSON Output

Use scripts/parse_audit.py to process JSON results into human-readable insights.

4. Present Findings

Format response as:

**CLR Audit Results**

**Summary:**
- Total Issues: X
- Affected SKUs: Y
- Queries Run: 12

**Top Priorities:**
1. [Most critical issue with count]
2. [Second critical issue]
3. [Third critical issue]

**Recommendations:**
- [Actionable fix #1]
- [Actionable fix #2]

**Export:** [mention JSON/CSV option if needed]

Common Use Cases

Use Case 1: General Audit

User: "Audit this CLR for me"

Action:

1. Run full scan: catalog scan <file> --format json --fields sku,severity,details --limit 50
2. Parse results with scripts/parse_audit.py
3. Present prioritized findings
4. Offer to export or dive deeper

Use Case 2: Specific Check

User: "Check if my bullet points are RUFUS optimized"

Action:

1. Run: catalog check rufus-bullets <file> --format json --limit 20
2. Parse RUFUS scores
3. Present bullets scoring below 4/5 with suggestions
4. Highlight position-specific issues (Hero Benefit, Audience, Differentiators)

Use Case 3: Export for Client

User: "Generate a report I can send to my client"

Action:

1. Run: catalog scan <file> --format csv --output client-audit.csv
2. Confirm CSV created
3. Optionally create summary document

Use Case 4: Compare Multiple CLRs

User: "Compare these two CLRs"

Action:

1. Run both: catalog scan file1.xlsx --format json + catalog scan file2.xlsx --format json
2. Compare issue counts, affected SKUs
3. Highlight improvements or new issues

Use Case 5: Multi-Marketplace Detection

User: "Audit this CLR - is it for Canada or US?"

Action:

1. Run: catalog scan <file> --format json
2. Check marketplace field in output
3. If not US, flag any US-specific issues that may not apply
4. Present findings with marketplace context

Use Case 6: Agent-Optimized Large Catalog (v2.0)

User: "Audit this large CLR but just show me the worst issues"

Action:

1. Run: catalog scan <file> --format json --queries missing-attributes,rufus-bullets --fields sku,severity,details --limit 10
2. Present top 10 most critical issues
3. Offer to show more with increased limit or different queries

Output Interpretation

JSON Structure (v2.0)

{
  "timestamp": "2026-03-05T10:30:00Z",
  "marketplace": "US",
  "is_us_marketplace": true,
  "total_queries": 12,
  "total_issues": 5904,
  "total_affected_skus": 95,
  "results": [
    {
      "query_name": "missing-attributes",
      "description": "Find mandatory attributes missing from listings",
      "total_issues": 444,
      "affected_skus": 37,
      "issues": [
        {
          "row": 7,
          "sku": "ABC-123",
          "field": "brand",
          "severity": "required",
          "details": "Missing required field: brand",
          "product_type": "HAIR_STYLING_AGENT",
          "extra": {}
        }
      ],
      "metadata": {
        "total_listings": 150,
        "marketplace": "US",
        "is_us_marketplace": true,
        "params": {}
      }
    }
  ]
}

Severity Levels

• required - Must fix (Amazon rejects listings)
• conditional - Fix based on product type
• critical - Amazon can suppress listings (prohibited content)
• warning - Best practice issue (RUFUS, title length)
• awareness - Soft violations (worth reviewing but not critical)
• info - Suggestions (unused fields, variations)

Prioritization Logic

1. Critical (Fix First):

   • Missing required attributes
   • Prohibited characters / content
   • Title issues

2. Important (Fix Soon):

   • RUFUS scores < 3
   • Missing conditional attributes
   • Product type mismatches

3. Optimize (When Time Allows):

   • RUFUS scores 3-4
   • Variation opportunities
   • Unused attributes

Troubleshooting

Issue: Command not found

# Add Python bin to PATH
export PATH="$HOME/Library/Python/3.14/bin:$PATH"

# Or run directly
python3 -m catalog.surfaces.cli scan <file>

Issue: Permission denied

# Make sure CLI is executable
which catalog
pip3 show amazon-catalog-cli

Issue: Large CLR slow

For CLRs with 1000+ SKUs, expect 10-15 second processing time. Use --limit to cap results.

Resources

See references/queries.md for detailed documentation on each query type and scripts/parse_audit.py for JSON processing helper.

For maintained docs and active development, use https://github.com/BWB03/amazon-catalog-cli.

---

Quick Reference:

# Full audit (all 12 queries)
catalog scan file.xlsx

# Agent-optimized (v2.0 - recommended)
catalog scan file.xlsx --format json --fields sku,severity,details --limit 20

# Structured JSON input (v2.0)
catalog scan --json '{"file": "file.xlsx", "queries": ["missing-attributes"], "limit": 10}'

# Specific checks
catalog check missing-attributes file.xlsx
catalog check rufus-bullets file.xlsx --format json --limit 10

# Schema discovery (v2.0)
catalog schema --format json

# NDJSON streaming (v2.0)
catalog scan file.xlsx --format ndjson --limit 50

# JSON export
catalog scan file.xlsx --format json --output results.json

# List all queries
catalog list-queries --format json

Version: Requires amazon-catalog-cli v2.0.0+

Upgrade:

pip3 install --upgrade amazon-catalog-cli