# amazon-catalog-auditor

Adopt this skill: https://proskills.md/skills/other/bwb03-amazon-catalog-auditor-skill

Page: https://proskills.md/skills/other/bwb03-amazon-catalog-auditor-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 10705
sha: c7782def55d9a36851c4e14a46afc97a85755302
upstream: https://github.com/bwb03/amazon-catalog-auditor-skill/blob/HEAD/SKILL.md

````text
---
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
```
````

## File: README.md
size: 10127
sha: 4ae67da8223bdda6370f5b9f56979afa6b375fb3
upstream: https://github.com/bwb03/amazon-catalog-auditor-skill/blob/HEAD/README.md

````text
# 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.
````

## File: scripts/parse_audit.py
size: 4205
sha: a9f7defa13e52d1ed350757d1ff93ab638afd8d3
upstream: https://github.com/bwb03/amazon-catalog-auditor-skill/blob/HEAD/scripts/parse_audit.py

```text
#!/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()
```

## File: references/queries.md
size: 3937
sha: 7966718d2f1970288f8d50929bcbc93cc6d1b1df
upstream: https://github.com/bwb03/amazon-catalog-auditor-skill/blob/HEAD/references/queries.md

````text
# 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
```
````

## File: .gitignore
size: 37
sha: f6d1a56059ec5f9ae5f7ebc20cc5940df2009ffd
upstream: https://github.com/bwb03/amazon-catalog-auditor-skill/blob/HEAD/.gitignore

```text
*.xlsx
*.xlsm
*.csv
*.json
.DS_Store
```

## File: amazon-catalog-auditor.skill
size: 6888
sha: 4060f4d1162ac8008cb32b8026a53bcfc20a9ae9
upstream: https://github.com/bwb03/amazon-catalog-auditor-skill/blob/HEAD/amazon-catalog-auditor.skill

Content is not inlined in the catalog. Read the upstream file: https://github.com/bwb03/amazon-catalog-auditor-skill/blob/HEAD/amazon-catalog-auditor.skill

## File: LICENSE
size: 1069
sha: a4afb8cda3ced5efc7cc7c85a009b2fa4a6ed68f
upstream: https://github.com/bwb03/amazon-catalog-auditor-skill/blob/HEAD/LICENSE

```text
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.
```