flitzrrr/agent-skills / skills/product-description-seo
product-description-seo
VerifiedEnd-to-end skill for SEO-optimized product descriptions: inventory analysis, generation, quality assurance, catalog update, and deployment. Use whenever the user wants to analyze, write, check, update, or deploy product descriptions — whether for a single product, a category, or an entire catalog. Triggers on: 'product description', 'Produktbeschreibung', 'SEO text', 'catalog text', 'update descriptions', 'which descriptions are missing', 'thin content', 'QA check', 'description quality', or when the user names a product category and wants texts for it. Also triggers on 'deploy' or 'commit' in the context of product descriptions.
| File | Kind | Size |
|---|---|---|
| CROSS-SELL.md | markdown | 1.9 KB |
| KEYWORDS.md | markdown | 1.3 KB |
| SKILL.md | skill md | 12.5 KB |
| scripts/analyze_catalog.py | script | 4.8 KB |
| scripts/check_quality.py | script | 7.5 KB |
| scripts/extract_category.py | script | 2.9 KB |
| scripts/track_progress.py | script | 5.0 KB |
| scripts/update_catalog.py | script | 2.3 KB |
| scripts/validate_json.py | script | 2.5 KB |
scripts/check_quality.py
View on GitHub#!/usr/bin/env python3
"""Quality-check product descriptions against SEO requirements.
Usage:
python check_quality.py <updates.json> [--strict] [--min-words 200] [--max-words 350]
Checks each description against 8 criteria:
1. Word count within range
2. 4-paragraph structure
3. Focus keyword in first sentence
4. No banned superlatives
5. Cross-sell reference present
6. Formal address (no informal pronouns)
7. Meta-description-ready opening
8. Plain text only (no HTML/Markdown)
"""
import json
import sys
import re
import argparse
DEFAULT_BANNED_WORDS = [
# English
"best-in-class", "unparalleled", "revolutionary", "sensational",
"unmatched", "world-leading", "game-changing",
# German
"erstklassig", "herausragend", "unschlagbar", "einzigartig",
"revolutionaer", "sensationell", "unvergleichlich",
"hoechstem niveau",
]
# Indicators that a cross-sell reference is present
CROSS_SELL_INDICATORS = [
"combination with", "kombination mit", "in combination",
"pairs well", "complement", "together with", "zusammen mit",
"ergaenzend", "empfehlen wir", "passend dazu",
]
# Informal pronouns that indicate wrong tone (German du-form)
INFORMAL_PRONOUNS = [
r'\bdu\b', r'\bdein\b', r'\bdeine\b', r'\bdeinem\b',
r'\bdeinen\b', r'\bdeiner\b', r'\bdir\b', r'\bdich\b',
]
def check_description(product: dict, min_words: int = 200, max_words: int = 350,
strict: bool = False) -> dict:
sku = product.get("sku", "?")
name = product.get("name", "?")
text = product.get("beschreibung", product.get("description", ""))
results = {"sku": sku, "name": name, "checks": [], "passed": 0, "failed": 0, "warnings": 0}
# 1. Word count
words = len(text.split())
if min_words <= words <= max_words:
results["checks"].append(("PASS", f"Word count: {words} (target: {min_words}-{max_words})"))
results["passed"] += 1
elif words > max_words:
results["checks"].append(("WARN", f"Word count: {words} -- above {max_words}, consider trimming"))
results["warnings"] += 1
else:
results["checks"].append(("FAIL", f"Word count: {words} -- below {min_words} minimum"))
results["failed"] += 1
# 2. Paragraph structure
paragraphs = [p.strip() for p in text.split("\n\n") if p.strip()]
if len(paragraphs) == 4:
results["checks"].append(("PASS", f"4-paragraph structure: {len(paragraphs)} paragraphs"))
results["passed"] += 1
elif len(paragraphs) >= 3:
results["checks"].append(("WARN", f"Paragraph structure: {len(paragraphs)} paragraphs (target: 4)"))
results["warnings"] += 1
else:
results["checks"].append(("FAIL", f"Paragraph structure: only {len(paragraphs)} paragraphs (target: 4)"))
results["failed"] += 1
# 3. Focus keyword in first sentence
first_sentence = text.split(".")[0].lower() if text else ""
name_parts = name.lower().split()
main_word = max(name_parts, key=len) if name_parts else ""
if main_word and main_word in first_sentence:
results["checks"].append(("PASS", f"Focus keyword in first sentence: '{main_word}' found"))
results["passed"] += 1
else:
results["checks"].append(("FAIL", f"Focus keyword missing in first sentence (expected: '{main_word}')"))
results["failed"] += 1
# 4. Banned superlatives
text_lower = text.lower()
found_banned = [w for w in DEFAULT_BANNED_WORDS if w in text_lower]
if not found_banned:
results["checks"].append(("PASS", "Tone: no banned superlatives"))
results["passed"] += 1
else:
level = "FAIL" if strict else "WARN"
results["checks"].append((level, f"Banned superlatives found: {', '.join(found_banned)}"))
if strict:
results["failed"] += 1
else:
results["warnings"] += 1
# 5. Cross-sell reference (warning only — not all products have natural cross-sells)
has_cross_sell = any(ind in text_lower for ind in CROSS_SELL_INDICATORS)
if has_cross_sell:
results["checks"].append(("PASS", "Cross-sell reference present"))
results["passed"] += 1
else:
level = "FAIL" if strict else "WARN"
results["checks"].append((level, "No cross-sell reference found"))
if strict:
results["failed"] += 1
else:
results["warnings"] += 1
# 6. Formal address
informal_found = []
for pattern in INFORMAL_PRONOUNS:
matches = re.findall(pattern, text_lower)
informal_found.extend(matches)
if not informal_found:
results["checks"].append(("PASS", "Formal address maintained"))
results["passed"] += 1
else:
results["checks"].append(("FAIL", f"Informal pronouns found: {', '.join(set(informal_found))}"))
results["failed"] += 1
# 7. Meta description
first_155 = text[:155]
if len(first_155) >= 100 and "." in first_155:
results["checks"].append(("PASS", f"Meta description: {len(first_155)} chars, contains sentence end"))
results["passed"] += 1
else:
results["checks"].append(("WARN", "Meta description: first 155 chars may need adjustment"))
results["warnings"] += 1
# 8. No HTML/Markdown
if re.search(r'<[^>]+>|#{1,6}\s|\*\*|__|\[.*\]\(.*\)', text):
results["checks"].append(("FAIL", "HTML or Markdown detected -- plain text only"))
results["failed"] += 1
else:
results["checks"].append(("PASS", "Plain text format (no HTML/Markdown)"))
results["passed"] += 1
return results
def main():
parser = argparse.ArgumentParser(description="Quality-check product descriptions")
parser.add_argument("updates_path", help="Path to updates JSON file")
parser.add_argument("--strict", action="store_true", help="Treat warnings as failures")
parser.add_argument("--min-words", type=int, default=200, help="Minimum word count (default: 200)")
parser.add_argument("--max-words", type=int, default=350, help="Maximum word count (default: 350)")
args = parser.parse_args()
with open(args.updates_path, "r", encoding="utf-8") as f:
updates = json.load(f)
print(f"{'=' * 70}")
print(f"QUALITY CHECK -- {len(updates)} descriptions")
print(f"{'=' * 70}")
total_pass = 0
total_fail = 0
total_warn = 0
failed_products = []
for product in updates:
result = check_description(product, args.min_words, args.max_words, args.strict)
total_pass += result["passed"]
total_fail += result["failed"]
total_warn += result["warnings"]
status = "OK" if result["failed"] == 0 else "FAIL"
print(f"\n[{status}] SKU {result['sku']}: {result['name']}"
f" ({result['passed']}P/{result['failed']}F/{result['warnings']}W)")
for check_type, msg in result["checks"]:
icon = {"PASS": " [+]", "FAIL": " [-]", "WARN": " [!]"}[check_type]
print(f" {icon} {msg}")
if result["failed"] > 0:
failed_products.append(f"SKU {result['sku']}: {result['name']}")
total_checks = total_pass + total_fail + total_warn
print(f"\n{'=' * 70}")
print(f"SUMMARY")
print(f"{'=' * 70}")
print(f"Products: {len(updates)}")
print(f"Checks: {total_checks} ({total_pass} passed, {total_fail} failed, {total_warn} warnings)")
if total_checks > 0:
print(f"Pass rate: {total_pass * 100 // total_checks}%")
if failed_products:
print(f"\nNeeds rework:")
for fp in failed_products:
print(f" -> {fp}")
sys.exit(1 if total_fail > 0 else 0)
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |