Product Taxonomy

Strictly per-subcategory. Never create a schema file for a top-level category. Each file maps to exactly one subcategory from categories.md. If the user asks to research a top-level category (e.g., "Machinery & Industrial Equipment"), ask them to pick a specific subcategory within it. Attribute duplication across sibling subcategory files is expected and acceptable — each schema should stand on its own.

Slugging convention: lowercase, spaces to hyphens, strip special characters (&, /, (, ), ,). The slug is derived from the subcategory name, not the top-level category. Examples:

• "Electric Vehicle Charging Equipment" → electric-vehicle-charging-equipment.md
• "Batteries & Grid-Scale Energy Storage" → batteries-grid-scale-energy-storage.md
• "Meat, Poultry & Seafood Products" → meat-poultry-seafood-products.md
• "Power Tools (Drills, Saws, Sanders)" → power-tools-drills-saws-sanders.md

Only product-taxonomy writes to these files. All other skills are read-only.

Phase 1: Understand the Request and Check Existing Data

Determine what the user wants:

• Research SKU attributes: Research companies to discover typical attributes for a subcategory that doesn't have a schema file yet
• Deepen an existing schema: Research more companies to refine an existing attribute list
• Browse/review: Show what's in the taxonomy already

1. Read docs/product-taxonomy/categories.md — this is the closed list of valid subcategories.
2. Match the input to an existing subcategory. The user's input is free text — it may not exactly match a subcategory name. Find the closest semantic match:
   • Exact or near-exact match → proceed (e.g., "power tools" → "Power Tools (Drills, Saws, Sanders)")
   • Close semantic equivalent (one match) → confirm with the user (e.g., "drills" → "Power Tools (Drills, Saws, Sanders)" — say: "The closest subcategory is 'Power Tools (Drills, Saws, Sanders)'. Shall I research that?")
   • Ambiguous — matches multiple subcategories → list the candidates and ask the user to pick one (e.g., "clothing" matches "Men's Clothing", "Women's Clothing", and "Children's & Infants' Clothing" — list all three and ask which one)
   • No reasonable match → stop and ask for clarification. Do not create new subcategories or top-level categories. Explain what exists and ask the user to pick one, or to update categories.md themselves first.
   • Not a tangible goods category (e.g., "SaaS platforms", "consulting services") → explain that this taxonomy is exclusively for physical products and ask for a different input.
   • If the user names a top-level category (e.g., "Machinery & Industrial Equipment"), ask them to pick a specific subcategory within it — schema files are per-subcategory only.
3. Check if docs/product-taxonomy/sku-schemas/{subcategory-slug}.md already exists for the matched subcategory. If it does, read it in full — this is an evolution run, not a fresh start.
4. Check if any reports in docs/ reference this subcategory. Those reports may contain real-world SKU attributes discovered from specific companies — useful input.

Phase 2: Research SKU Attributes

Before starting research, read .claude/skills/product-taxonomy/references/research-methodology.md — it details how to select companies, what to look for on product pages, what counts as a tangible goods attribute (and what doesn't), and common pitfalls.

If a schema file already exists (evolution run)

This is how schemas improve over time. The existing file is the baseline — your job is to enrich it, not replace it.

1. Read the existing schema and note which companies were already researched (listed in the Changelog's Sources column).
2. Research 2-3 new companies not already in the Sources — preferably from different regions or market segments to broaden coverage.
3. Compare what you find against the existing attribute list:
   • New attribute found? Add it to the table. This is how the schema grows.
   • Existing attribute confirmed? Leave it as-is. No change needed.
   • Existing attribute seems wrong or redundant? Do not remove it. Mark it as DEPRECATED per the append-only rule. Schemas only grow; they never shrink.
4. Update the "Last updated" date and prepend a new row to the Changelog documenting what changed and which companies were researched.

The schema evolves with each run — every time the skill is invoked for an existing subcategory, it gets a little better.

Evolution mode (scraper-generator feedback loop)

When this skill is invoked by the scraper-generator feedback loop (evolution mode), follow these additional constraints:

• Can only ADD new attributes to Extended — do not add directly to Core.
• Can PROMOTE extended → core when an attribute appears in scraper output from 3+ different companies.
• Never delete or rename existing attributes — append-only, same as regular evolution runs.
• Evaluate significance broadly — when the scraper-generator proposes new attributes, research whether they are genuinely significant for the subcategory by checking other companies, not just the triggering one. An attribute that only one company uses is not a good candidate.

If starting fresh

Investigate 3-5 companies selling products in the subcategory. The methodology file explains how to pick a mix of manufacturers, distributors, and retailers for breadth.

The goal is to identify the most significant attributes for the subcategory — the ones that consistently appear on pricelists and product catalogs across companies. Only record attributes that describe the physical product itself, not services, software, or marketing layered on top.

Phase 3: Synthesize the Schema

After researching multiple companies, synthesize a two-tier attribute schema for the subcategory. The schema should cover most products in the subcategory without drilling into sub-subcategories.

Two-tier attribute split

Produce two attribute tables — Core Attributes and Extended Attributes — not a single flat list. These two tiers drive how scrapers prioritize extraction effort (see .claude/skills/scraper-generator/references/coder.md for the full four-level product record format).

Core attributes (5-10 category-specific, plus the 6 mandatory core rows): The most important category-specific attributes — scrapers put high effort into extracting these. They define what makes a product identifiable and comparable within its subcategory. Selection criteria:

• Identity: what kind of product (tool_type, fastener_type, dosage_form)
• Material/composition: what it's made of (material, primary_ingredient)
• Primary dimension: the key size/capacity metric (voltage, thread_size, capacity_oz)
• Identification/provenance: model number, country of origin

Extended attributes (10-15): Important but secondary — scrapers put moderate effort into extracting these. Real attributes that are product-type-specific or less commonly published. Everything that doesn't fit core.

Which attributes to include: the ones that are most significant for the subcategory AND commonly appear on pricelists and product catalogs. The test is: "Would this attribute appear on a typical pricelist or product comparison sheet for this subcategory?" If yes, include it. If it's only on deep spec sheets or niche enthusiast sites, leave it out.

Use this as a calibration guide (counts are category-specific attributes only — the 6 mandatory core rows don't count toward these ranges):

• Category-specific core under 5 — too thin
• Category-specific core 5-10 — right
• Category-specific core over 10 — too many, demote to extended
• Extended under 10 — too thin
• Extended 10-15 — right
• Extended over 15 — trim back
• Total category-specific 15-30

Mandatory attributes

Every schema must include these 5 attributes as the first rows of the Core Attributes table, with Mandatory set to yes. They appear in every schema regardless of category. Descriptions and example values should be tailored to the category, but the attribute names, keys, data types, and mandatory status are fixed.

Start the Core Attributes table with these 5 (all yes), then add the non-mandatory core attribute below, then category-specific core attributes. Extended attributes always have Mandatory set to —.

Non-mandatory core attribute

One additional attribute appears in every schema immediately after the 5 mandatory rows, but with Mandatory set to —:

Row order in Core Attributes: 5 mandatory rows → price_includes_vat → category-specific core attributes.

The Mandatory column tells downstream consumers (scraper-generator, eval-generator) which core attributes must always be present vs. which are best-effort. Mandatory core attributes get strict 100% validation; category-specific core attributes get coverage-based validation.

Note on Brand: Brand is NOT included in SKU schemas — it is a mandatory core attribute on the product record, handled outside the taxonomy.

Synthesis steps

1. Merge attributes that are the same concept but named differently across companies (e.g., "Item No." / "Article Number" / "SKU" → standardize as "SKU")
2. Prioritize by pricelist presence — if 3 out of 5 companies show this attribute on their pricelist or catalog listing (not buried in a spec sheet), it belongs in the schema.

Compliance attributes

Keep compliance and certification attributes international and universal. Include widely recognized standards (ISO, CE, UL, RoHS, REACH, HACCP, GMP) but avoid country-specific regulatory details (individual US state registrations, country-specific label requirements, locale-specific certifications). The goal is a schema that works globally, not one tuned to a single jurisdiction.

Schema evolution rules

What you can change freely:

• Update the Description of an existing attribute (improve clarity, add detail)
• Update the Example Values (add better examples, fix typos)

Descriptions and Example Values must be company-neutral. Never mention specific company names in the Description or Example Values columns. Descriptions should explain what the attribute represents generically. Example Values should be realistic product data, not brand names. Company names belong only in two places: the Brand/Manufacturer attribute's Example Values (where they ARE the data), and the Changelog Sources column.

What you cannot change:

• Attribute Name — renaming breaks downstream references. If the name is wrong, deprecate and create a new one.
• Key — changing a key breaks downstream scrapers and eval configs that reference it. If the key is wrong, deprecate the attribute and create a new one.
• Data Type — changing a type (e.g., text → enum, number → text) breaks downstream parsing. If the type needs to change, deprecate the old attribute and create a new one with the correct type.

Never delete an attribute. Downstream systems may depend on it. If an attribute is wrong, redundant, or no longer used, mark it as deprecated:

Mark the description with DEPRECATED and the date. This preserves backward compatibility while keeping the schema clean for readers.

Phase 4: Write the Output

Verify subcategory exists in categories.md

The subcategory you are researching must already exist in docs/product-taxonomy/categories.md. This skill does not add new subcategories or top-level categories — that is done by editing categories.md directly, outside of this skill. If Phase 1 matched the user's input to an existing subcategory, proceed. Otherwise you should have already stopped in Phase 1.

Write/Update the SKU schema file

Write to docs/product-taxonomy/sku-schemas/{subcategory-slug}.md using the exact format below. Every schema file must follow this structure precisely — no variations.

Canonical file structure

# SKU Schema: {Subcategory Name}

**Last updated:** {today's date}
**Parent category:** {Top-Level Category Name}
**Taxonomy ID:** `{taxonomy_id}`

## Core Attributes

| Attribute | Key | Data Type | Unit | Mandatory | Description | Example Values |
|-----------|-----|-----------|------|-----------|-------------|----------------|
| SKU | sku | text | — | yes | {category-specific description} | {examples} |
| Product Name | product_name | text | — | yes | {category-specific description} | {examples} |
| URL | url | text | — | yes | {category-specific description} | {examples} |
| Price | price | number | — | yes | {category-specific description} | {examples} |
| Currency | currency | text | — | yes | {category-specific description} | {examples} |
| Price Includes VAT | price_includes_vat | boolean | — | — | {category-specific description} | true, false |
| {core attr} | {key} | {type} | {unit or —} | — | {description} | {examples} |
| ... | ... | ... | ... | ... | ... | ... |

## Extended Attributes

| Attribute | Key | Data Type | Unit | Mandatory | Description | Example Values |
|-----------|-----|-----------|------|-----------|-------------|----------------|
| {extended attr} | {key} | {type} | {unit or —} | — | {description} | {examples} |
| ... | ... | ... | ... | ... | ... | ... |

## Changelog

| Date | Change | Sources |
|------|--------|---------|
| {today} | Initial schema — {N} core + {M} extended attributes from {companies} | [{Company 1}]({URL}), [{Company 2}]({URL}) |

The Taxonomy ID must be looked up from docs/product-taxonomy/categories.md. Each subcategory line has the format - Subcategory Name \taxonomy.id`. Parse it using the regex: re.match(r'^- (.+?) \x60([a-z][a-z0-9_.]+)\x60$', line.strip())` — group 2 is the taxonomy ID.

Strict format rules

These rules are non-negotiable. Every schema must comply exactly.

The Changelog is the history of the schema. Every run adds a row at the top (most recent first). On evolution runs, the new row should look like:

| 2026-03-15 | Added: Halal Cert, Kosher Cert. Deprecated: none. | [Al Islami](url), [Brakes UK](url) |

Phase 5: Self-Verification

Before presenting results, re-read the schema file you just wrote and check it against these quality gates. If any gate fails, fix the issue before proceeding.

If all checks pass, proceed to the summary.

Phase 6: Summary

Tell the user:

• What subcategory was researched
• Where the schema file was saved (full path)
• How many companies were investigated (and which were new vs already in Sources)
• How many attributes are in the schema now
• If evolution run: how many new attributes were added, how many deprecated, and what the new attributes are
• Any interesting findings

Investigation Tips

• B2B/industrial sites often have the most detailed product specs
• Distributor sites (Grainger, McMaster-Carr, RS Components) are goldmines for attribute discovery since they standardize across brands
• Manufacturer sites show brand-specific naming but often have the deepest spec sheets
• E-commerce platforms (Amazon, Home Depot) show which attributes consumers filter by — these are the most commercially important ones
• If a category is broad (e.g., "Machinery & Industrial Equipment" has 12 subcategories), research one subcategory at a time rather than trying to cover everything at once