amazon-catalog-auditor

7 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

• SKILL.md10 KBc7782def55d9upstream ↗

  ---
  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:
  
  ```bash
  catalog --version
  ```
  
  If not installed:
  
  ```bash
  pip3 install amazon-catalog-cli
  ```
  
  ### Basic Usage
  
  ```bash
  # 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)
  
  ```bash
  # 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
  
  ```python
  # 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):**
  ```bash
  catalog scan <clr-path> --format json --fields sku,severity,details --limit 50
  ```
  
  **Specific Issue:**
  ```bash
  catalog check rufus-bullets <clr-path> --format json --limit 20
  ```
  
  **Quick Summary:**
  ```bash
  catalog scan <clr-path>
  ```
  
  **Structured Input (v2.0):**
  ```bash
  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)
  
  ```json
  {
    "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
  
  ```bash
  # 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
  
  ```bash
  # 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:**
  
  ```bash
  # 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:**
  ```bash
  pip3 install --upgrade amazon-catalog-cli
  ```
  

• README.md9.9 KB4ae67da8223bupstream ↗

  # Amazon Catalog Auditor - OpenClaw Skill
  
  > [!WARNING]
  > Deprecated wrapper repo as of April 20, 2026.
  > Active development now lives in [amazon-catalog-cli](https://github.com/BWB03/amazon-catalog-cli).
  > Please open issues and pull requests there instead of this repository.
  
  **OpenClaw skill for auditing Amazon Category Listing Reports**
  
  This skill wraps the [amazon-catalog-cli](https://github.com/BWB03/amazon-catalog-cli) tool to provide automated CLR analysis within OpenClaw workflows.
  
  ## What It Does
  
  Enables OpenClaw agents to audit Amazon CLRs with natural language commands:
  
  - "Audit this CLR"
  - "Check for missing attributes"
  - "What RUFUS issues do I have?"
  - "Analyze my catalog health"
  
  The skill automatically:
  - Runs catalog queries
  - Parses results
  - Presents prioritized insights
  - Provides actionable recommendations
  
  **New in CLI v2.0.0 — Agent-First Redesign:**
  
  > **Note:** v2.0 of amazon-catalog-cli now ships with a built-in `SKILL.md` and an MCP server (`catalog mcp`). For MCP-compatible clients (Claude Desktop, CLR Pro, etc.), the CLI itself is now a first-class agent surface — no separate skill wrapper needed. This OpenClaw skill remains useful for OpenClaw-specific workflows.
  
  - **MCP server** - `catalog mcp` exposes `catalog_scan`, `catalog_check`, `catalog_list_queries`, `catalog_schema` as MCP tools
  - **JSON/stdin input** - `catalog scan --json '{...}'` or piped via `--stdin`
  - **Schema introspection** - `catalog schema --format json` for auto-discovery
  - **Field masks** - `--fields sku,severity,details` to reduce output size
  - **Pagination** - `--limit` and `--offset` for large catalogs
  - **NDJSON streaming** - `--format ndjson` for line-by-line output
  - **Input validation** - Rejects path traversal, injection, malformed input
  - **Backward compatible** - All v1.x commands work unchanged
  
  **v1.3.0:**
  - Marketplace detection - Auto-detects US/CA/UK/DE/etc from CLR metadata
  - Bullet awareness checks - Flags soft violations (excessive caps, problematic chars)
  - 12 total queries
  
  **v1.2.0:**
  - Bullet point compliance - Comprehensive validation against Amazon's official requirements
  - Prohibited content detection - Finds banned chars, emojis, placeholder text, prohibited claims
  - Formatting validation - Checks capitalization, length, punctuation rules
  
  **v1.1.0:**
  - RUFUS tier scoring - Each SKU gets a health rating (Good/Fair/Weak/Critical)
  - Catalog-wide summary - Overall score + distribution stats
  - FBM duplicate filtering - Auto-skips redundant FBM/MFN SKUs (cleaner reports)
  
  ## Installation
  
  This wrapper is no longer the primary distribution target. Install and use `amazon-catalog-cli` directly for the maintained implementation.
  
  ### Prerequisites
  
  1. **OpenClaw** installed and running
  2. **amazon-catalog-cli** installed:
     ```bash
     pip install amazon-catalog-cli
     ```
  
  ### Install Skill
  
  1. Download `amazon-catalog-auditor.skill`
  2. Add to your OpenClaw skills directory
  3. Restart OpenClaw
  
  **Or via OpenClaw CLI:**
  ```bash
  # Coming soon: OpenClaw skill install command
  ```
  
  ## Usage
  
  ### Basic Audit
  
  ```
  You: Audit this CLR
  [attach CLR file]
  
  Agent: 🔍 CLR Audit Results
  
  📊 Summary:
  - 47 issues found
  - 23 SKUs affected
  
  🔥 Top Priorities:
  1. Missing Brand (12 SKUs)
  2. RUFUS Bullets scoring low (8 SKUs)
  3. Titles exceeding 200 chars (3 SKUs)
  
  💡 Recommendations:
  - Add brand to 12 SKUs
  - Rewrite Bullet 1 for 8 products
  - Trim 3 titles under 200 characters
  ```
  
  ### Specific Checks
  
  ```
  You: Check my RUFUS bullet optimization
  
  Agent: 📝 RUFUS Bullet Analysis
  
  15 SKUs scoring below 4/5
  
  Common Issues:
  1. Bullet 1 missing Hero Benefit (8 SKUs)
  2. Bullet 2 missing target audience (5 SKUs)
  3. No specific data points (12 SKUs)
  
  Top 3 to fix:
  - ABC-123: Score 2/5 (no benefits)
  - XYZ-456: Score 2.5/5 (vague language)
  - DEF-789: Score 3/5 (needs specifics)
  ```
  
  ### Export for Clients
  
  ```
  You: Generate a report I can send to my client
  
  Agent: Created client-audit.csv with all 47 issues.
  Summary report ready to share.
  ```
  
  ## Features
  
  ### 12 Built-in Checks
  
  1. **Missing Attributes** - Required fields
  2. **Missing Any Attributes** - Required + conditional
  3. **Long Titles** - Over 200 characters
  4. **Title Prohibited Chars** - Invalid characters
  5. **RUFUS Bullets** - AI optimization scoring
  6. **Prohibited Chars** - Invalid characters in title/brand
  7. **Bullet Prohibited Content** - Detects banned chars, emojis, claims, placeholders (v1.2.0)
  8. **Bullet Formatting** - Validates capitalization, length, punctuation (v1.2.0)
  9. **Bullet Awareness** - Soft violations: excessive caps, problematic special chars (NEW v1.3.0)
  10. **Product Type Mismatch** - Type/keyword alignment
  11. **Missing Variations** - Variation opportunities
  12. **New Attributes** - Unused template fields
  
  ### Intelligent Analysis
  
  - **Prioritization** - Critical issues first
  - **Context-aware** - Understands Amazon requirements
  - **Actionable** - Specific fix recommendations
  - **Export options** - JSON, CSV, or human-readable
  
  ## Examples
  
  ### Example 1: Full Audit
  
  **User:** "Audit this CLR and prioritize what needs fixing"
  
  **Agent analyzes and responds:**
  ```
  🔍 PlantFusion CLR Audit
  
  📊 Summary: 47 issues, 23 SKUs
  
  🔥 Critical (Fix Now):
  • Missing Brand (12 SKUs) - Required field
  • Prohibited characters (3 SKUs) - Blocks listing
  
  ⚡ Important (Fix Soon):
  • RUFUS scores <3 (8 SKUs) - Poor conversion
  • Missing conditional fields (15 SKUs) - Product type specific
  
  💡 Optimize (When Time Allows):
  • RUFUS scores 3-4 (12 SKUs) - Good, can be great
  • Variation opportunities (4 SKUs) - Bundle related products
  
  Quick wins: Fix brand + prohibited chars = 15 issues resolved
  ```
  
  ### Example 2: RUFUS Deep Dive
  
  **User:** "Why are my bullet points scoring low?"
  
  **Agent explains:**
  ```
  📝 RUFUS Analysis for 8 low-scoring SKUs
  
  Position-specific issues:
  
  Bullet 1 (Hero Benefit):
  ❌ "Premium quality hair gel with amazing hold"
  ✅ "Reduce frizz by 80% and add lasting shine"
  
  Bullet 2 (Target Audience):
  ❌ "Great for styling"
  ✅ "Ideal for curly or wavy hair, perfect for all-day hold"
  
  Common problems:
  • Vague marketing (5 SKUs) - "premium", "amazing", "best"
  • Missing data points (7 SKUs) - Add %, oz, count, time
  • Too short (3 SKUs) - Expand with specifics
  
  Want me to rewrite examples for your top 3 SKUs?
  ```
  
  ## Requirements
  
  - **OpenClaw** 2024.2+
  - **amazon-catalog-cli** 2.0.0+ (recommended — includes MCP server, schema introspection, field masks)
  - **Python** 3.10+
  
  ## How It Works
  
  1. User uploads CLR or provides file path
  2. Skill runs `catalog scan` command
  3. Parses JSON output (now includes marketplace metadata)
  4. Analyzes by severity and priority
  5. Presents human-readable insights
  6. Offers export options if needed
  
  The skill uses the CLI tool under the hood, so all 12 queries stay up-to-date automatically when the CLI is updated.
  
  ## Security & Safety
  
  **This skill is designed with security in mind:**
  
  ### What It Does ✅
  - **Read-only operations** - Only reads CLR files from your workspace
  - **Deterministic parsing** - Pure Python logic, no AI model calls
  - **Local execution** - All processing happens on your machine
  - **Output files only** - Creates reports in workspace, nothing else
  - **Open source** - Full code transparency
  
  ### What It Doesn't Do ❌
  - **No network calls** - Doesn't phone home or transmit data
  - **No credential storage** - Doesn't ask for or store API keys
  - **No system modifications** - Doesn't touch files outside workspace
  - **No external dependencies** - Only uses `amazon-catalog-cli` (also open source)
  - **No telemetry** - Zero tracking or analytics
  
  ### Skill Safety Best Practices
  
  When evaluating **any** OpenClaw skill (including this one):
  
  1. **Review the code** - Check `SKILL.md` and `scripts/` folder
  2. **Verify dependencies** - Fewer is better, inspect what gets installed
  3. **Check the source** - Install from trusted developers/official repos
  4. **Understand permissions** - Know what file access the skill needs
  5. **Monitor behavior** - Watch what commands it runs
  
  ### Worst-Case Scenario
  
  If this skill had a bug or was compromised:
  - ❌ **NOT possible:** System compromise, data theft, malicious execution
  - ✅ **Possible:** Incorrect audit results, file path errors, skill crashes
  
  **Why it's safe:** The skill is a thin wrapper around a deterministic CLI tool. It doesn't make decisions, doesn't connect to external services, and operates entirely within your workspace sandbox.
  
  ### Trust Chain
  
  1. **amazon-catalog-cli** - Open source Python package on PyPI
  2. **This skill** - Wraps the CLI with OpenClaw-friendly interface
  3. **Your OpenClaw instance** - Executes within your configured sandbox
  
  All three layers are auditable, transparent, and under your control.
  
  ### Questions or Concerns?
  
  Open an issue on GitHub or review the code yourself. Security through transparency.
  
  ## Related Projects
  
  - **[amazon-catalog-cli](https://github.com/BWB03/amazon-catalog-cli)** - Standalone CLI tool (required)
  - **[clr-auditor](https://github.com/BWB03/clr-auditor)** - Original Python auditor
  - **[amazon-tool](https://github.com/BWB03/amazon-tool)** - Variation creator
  
  ## Contributing
  
  This repository is maintenance-only.
  
  For fixes, features, and current documentation, contribute to [amazon-catalog-cli](https://github.com/BWB03/amazon-catalog-cli) instead.
  
  ## Updates
  
  When the CLI tool adds new features:
  - The skill automatically uses them (no update needed)
  
  When the skill documentation improves:
  - Download the latest `.skill` file
  - Replace in your skills directory
  
  ## Support
  
  - **Issues and feature requests:** [amazon-catalog-cli Issues](https://github.com/BWB03/amazon-catalog-cli/issues)
  - **OpenClaw:** [OpenClaw Discord](https://discord.com/invite/clawd)
  
  ## License
  
  MIT License - Free to use, modify, and distribute.
  
  ## Author
  
  Built by Brett Bohannon ([@BWB03](https://github.com/BWB03))
  
  Amazon consulting veteran, AI automation enthusiast, OpenClaw power user.
  
  ---
  
  **First OpenClaw skill for Amazon catalog management.** Built for consultants automating client work.
  

• scripts/parse_audit.py4.1 KBa9f7defa13e5upstream ↗

  #!/usr/bin/env python3
  """
  Parse amazon-catalog-cli JSON output into human-readable insights
  """
  
  import json
  import sys
  from collections import defaultdict
  
  
  def parse_audit_json(json_path):
      """Parse audit JSON and extract key insights"""
      
      with open(json_path, 'r') as f:
          data = json.load(f)
      
      insights = {
          'total_issues': data.get('total_issues', 0),
          'total_skus': data.get('total_affected_skus', 0),
          'by_query': {},
          'by_severity': defaultdict(int),
          'top_skus': defaultdict(int),
          'critical_issues': []
      }
      
      # Process each query
      for query in data.get('queries', []):
          query_name = query['query_name']
          total = query['total_issues']
          
          insights['by_query'][query_name] = {
              'total': total,
              'affected_skus': query['affected_skus']
          }
          
          # Count by severity
          for issue in query.get('issues', []):
              severity = issue.get('severity', 'unknown')
              insights['by_severity'][severity] += 1
              
              # Track problematic SKUs
              sku = issue.get('sku', 'N/A')
              insights['top_skus'][sku] += 1
              
              # Flag critical issues
              if severity == 'required':
                  insights['critical_issues'].append({
                      'sku': sku,
                      'field': issue.get('field', ''),
                      'details': issue.get('details', '')
                  })
      
      return insights
  
  
  def format_insights(insights):
      """Format insights into human-readable text"""
      
      output = []
      
      # Header
      output.append("🔍 CLR AUDIT INSIGHTS\n")
      output.append("=" * 50)
      
      # Summary
      output.append(f"\n📊 SUMMARY:")
      output.append(f"  Total Issues: {insights['total_issues']}")
      output.append(f"  Affected SKUs: {insights['total_skus']}")
      
      # By severity
      output.append(f"\n⚠️  BY SEVERITY:")
      for severity, count in sorted(insights['by_severity'].items()):
          icon = {
              'required': '🔴',
              'conditional': '🟡',
              'warning': '🟠',
              'info': '🔵'
          }.get(severity, '⚪')
          output.append(f"  {icon} {severity.title()}: {count}")
      
      # Top queries
      output.append(f"\n🔍 TOP ISSUES:")
      sorted_queries = sorted(
          insights['by_query'].items(),
          key=lambda x: x[1]['total'],
          reverse=True
      )[:5]
      
      for query_name, data in sorted_queries:
          if data['total'] > 0:
              output.append(f"  • {query_name}: {data['total']} issues ({data['affected_skus']} SKUs)")
      
      # Top problematic SKUs
      if insights['top_skus']:
          output.append(f"\n🎯 TOP PROBLEMATIC SKUs:")
          sorted_skus = sorted(
              insights['top_skus'].items(),
              key=lambda x: x[1],
              reverse=True
          )[:5]
          
          for sku, count in sorted_skus:
              output.append(f"  • {sku}: {count} issues")
      
      # Critical issues sample
      if insights['critical_issues']:
          output.append(f"\n🚨 CRITICAL ISSUES (Sample):")
          for issue in insights['critical_issues'][:5]:
              output.append(f"  • {issue['sku']}: {issue['field']} - {issue['details'][:60]}")
          
          if len(insights['critical_issues']) > 5:
              output.append(f"  ... and {len(insights['critical_issues']) - 5} more")
      
      output.append("\n" + "=" * 50)
      
      return "\n".join(output)
  
  
  def main():
      if len(sys.argv) < 2:
          print("Usage: parse_audit.py <json-file>")
          print("\nExample:")
          print("  parse_audit.py results.json")
          sys.exit(1)
      
      json_path = sys.argv[1]
      
      try:
          insights = parse_audit_json(json_path)
          output = format_insights(insights)
          print(output)
      
      except FileNotFoundError:
          print(f"Error: File not found: {json_path}")
          sys.exit(1)
      except json.JSONDecodeError:
          print(f"Error: Invalid JSON file: {json_path}")
          sys.exit(1)
      except Exception as e:
          print(f"Error: {e}")
          sys.exit(1)
  
  
  if __name__ == '__main__':
      main()
  

• references/queries.md3.8 KB7966718d2f19upstream ↗

  # Query Reference
  
  Detailed documentation for all 9 catalog queries.
  
  ## 1. missing-attributes
  
  **What it checks:** Required attributes missing from listings
  
  **Severity:** Critical (required)
  
  **Common issues:**
  - Brand
  - Item Type Keyword
  - Bullet Points
  - Product Description
  - Country of Origin
  
  **Fix:** Add missing required fields in Seller Central or bulk upload
  
  ---
  
  ## 2. missing-any-attributes
  
  **What it checks:** All missing attributes (required + conditional)
  
  **Severity:** Required or Conditional
  
  **When to use:** Comprehensive attribute audit
  
  **Fix:** Review conditional fields based on product type
  
  ---
  
  ## 3. long-titles
  
  **What it checks:** Titles exceeding 200 characters
  
  **Severity:** Warning
  
  **Impact:** Amazon truncates titles >200 chars, hurting SEO
  
  **Fix:** Trim to under 200 characters, front-load keywords
  
  ---
  
  ## 4. title-prohibited-chars
  
  **What it checks:** Prohibited characters in titles: `!$?_{}^¬¦`
  
  **Severity:** Warning
  
  **Impact:** Amazon may suppress or reject listings
  
  **Fix:** Remove prohibited characters, use allowed punctuation (- , .)
  
  ---
  
  ## 5. rufus-bullets
  
  **What it checks:** Bullet point optimization against Amazon's RUFUS AI framework
  
  **Severity:** Warning
  
  **Scoring:** 1-5 per bullet (5 = perfect)
  
  **Framework:**
  - **Bullet 1:** Hero Benefit (why buy this?)
  - **Bullet 2:** Target Audience (who is it for?)
  - **Bullet 3:** Differentiators (why this vs. competitors?)
  - **All bullets:** Specific data, no vague marketing, proper length
  
  **Issues flagged:**
  - Too short (<50 chars) or too long (>500 chars)
  - Vague marketing language ("premium quality", "best in class")
  - Excessive ALL CAPS
  - Missing specifics (numbers, measurements, data)
  - Position-specific issues (Bullet 1 lacks benefits, etc.)
  
  **Fix Examples:**
  
  **Bad Bullet 1:**
  > "Premium quality hair gel with amazing hold"
  
  **Good Bullet 1:**
  > "Reduce frizz by 80% and add lasting shine with our humidity-resistant formula"
  
  **Bad Bullet 2:**
  > "Great for styling"
  
  **Good Bullet 2:**
  > "Ideal for curly or wavy hair types, perfect for men and women seeking all-day hold"
  
  ---
  
  ## 6. prohibited-chars
  
  **What it checks:** Prohibited characters in any field (Title, Bullets, Description)
  
  **Severity:** Warning
  
  **Prohibited:** `!$?_{}^¬¦<>`
  
  **Fix:** Remove or replace with allowed characters
  
  ---
  
  ## 7. product-type-mismatch
  
  **What it checks:** Mismatches between Product Type and Item Type Keyword
  
  **Severity:** Warning
  
  **Example Issue:**
  - Product Type: `HAIR_STYLING_AGENT`
  - Item Type: `cleaning-wipes` ❌
  
  **Impact:** Incorrect categorization, poor search placement
  
  **Fix:** Ensure Item Type Keyword aligns with Product Type
  
  ---
  
  ## 8. missing-variations
  
  **What it checks:** Products that should be variations but aren't
  
  **Severity:** Info
  
  **Detection logic:**
  - Groups products by brand + normalized name
  - Flags standalone SKUs that look like size/color variants
  
  **Example:**
  - SKU-001: "Brand X Shampoo 8oz"
  - SKU-002: "Brand X Shampoo 16oz"
  - **Suggestion:** Create parent-child variation
  
  **Fix:** Create variation family in Seller Central
  
  ---
  
  ## 9. new-attributes
  
  **What it checks:** Template fields that exist but aren't being used
  
  **Severity:** Info
  
  **Use case:** Discover new attributes Amazon added to templates
  
  **Example:**
  - Template has "Sustainability Features" field (new)
  - No listings use it
  - **Opportunity:** Add sustainability info to improve discoverability
  
  **Fix:** Review unused fields, add data if valuable
  
  ---
  
  ## Query Selection Guide
  
  ### Quick Health Check
  ```bash
  catalog check missing-attributes file.xlsx
  catalog check long-titles file.xlsx
  ```
  
  ### Content Quality Audit
  ```bash
  catalog check rufus-bullets file.xlsx
  catalog check prohibited-chars file.xlsx
  ```
  
  ### Comprehensive Audit
  ```bash
  catalog scan file.xlsx
  ```
  
  ### Optimization Opportunities
  ```bash
  catalog check missing-variations file.xlsx
  catalog check new-attributes file.xlsx
  ```
  

• .gitignore37 Bf6d1a56059ecupstream ↗

  *.xlsx
  *.xlsm
  *.csv
  *.json
  .DS_Store
  

• amazon-catalog-auditor.skill6.7 KB4060f4d1162aupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

• LICENSE1.0 KBa4afb8cda3ceupstream ↗

  MIT License
  
  Copyright (c) 2026 Brett Wilson
  
  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:
  
  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.
  
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
  

Plain-text copy, no login: /skill-bundles/bwb03-amazon-catalog-auditor-skill.md