add skills

.agents/skills/content-modeling-best-practices/references/taxonomy-classification.md

@@ -0,0 +1,136 @@
+# Taxonomy and Classification
+
+Organizing content with taxonomies enables filtering, navigation, and content relationships. Well-designed taxonomies scale; poorly designed ones become maintenance nightmares.
+
+## Types of Classification
+
+### Flat Taxonomy
+Simple list of terms with no hierarchy.
+
+**Use for:** Tags, simple categories
+**Example:** Blog tags: "javascript", "react", "tutorial"
+
+```typescript
+defineType({
+  name: 'tag',
+  type: 'document',
+  fields: [
+    defineField({ name: 'title', type: 'string' }),
+    defineField({ name: 'slug', type: 'slug' }),
+  ]
+})
+```
+
+### Hierarchical Taxonomy
+Terms with parent-child relationships.
+
+**Use for:** Product categories, content sections
+**Example:** Electronics > Phones > Smartphones
+
+```typescript
+defineType({
+  name: 'category',
+  type: 'document',
+  fields: [
+    defineField({ name: 'title', type: 'string' }),
+    defineField({ name: 'slug', type: 'slug' }),
+    defineField({ 
+      name: 'parent', 
+      type: 'reference', 
+      to: [{ type: 'category' }],
+      description: 'Parent category (leave empty for top-level)'
+    }),
+  ]
+})
+```
+
+### Faceted Classification
+Multiple independent dimensions.
+
+**Use for:** Complex filtering (e-commerce)
+**Example:** Filter by color AND size AND price range
+
+```typescript
+// Multiple taxonomy types
+defineField({ name: 'color', type: 'reference', to: [{ type: 'color' }] })
+defineField({ name: 'size', type: 'reference', to: [{ type: 'size' }] })
+defineField({ name: 'material', type: 'reference', to: [{ type: 'material' }] })
+```
+
+## Design Principles
+
+### 1. Mutual Exclusivity (When Appropriate)
+Categories should be distinct. If items frequently belong to multiple categories, consider tags instead.
+
+**Categories:** One primary classification
+**Tags:** Many optional classifications
+
+### 2. User-Centric Naming
+Use terms your audience uses, not internal jargon.
+
+**Bad:** "Content Assets" (internal term)
+**Good:** "Resources" or "Downloads" (user term)
+
+### 3. Balanced Depth
+Too shallow: Everything lumped together
+Too deep: Users can't find anything
+
+**Rule of thumb:** 3-4 levels max for hierarchies
+
+### 4. Scalable Structure
+Design for 10x growth. Will your structure work with 10,000 items?
+
+## Querying Taxonomies
+
+### Get all items in a category
+
+```groq
+*[_type == "product" && category._ref == $categoryId]
+```
+
+### Get items in category OR children
+
+```groq
+// First get all descendant category IDs
+*[_type == "product" && category._ref in 
+  *[_type == "category" && (
+    _id == $categoryId || 
+    parent._ref == $categoryId ||
+    parent->parent._ref == $categoryId
+  )]._id
+]
+```
+
+### Get category tree
+
+```groq
+*[_type == "category" && !defined(parent)]{
+  title,
+  slug,
+  "children": *[_type == "category" && parent._ref == ^._id]{
+    title,
+    slug,
+    "children": *[_type == "category" && parent._ref == ^._id]{
+      title,
+      slug
+    }
+  }
+}
+```
+
+## Common Mistakes
+
+### Over-categorization
+Creating a category for everything results in mostly-empty categories.
+
+**Fix:** Start minimal, add categories as content grows.
+
+### Inconsistent Granularity
+Some categories broad ("Technology"), others narrow ("React 18 Server Components").
+
+**Fix:** Define clear criteria for category creation.
+
+### No Governance
+Anyone can create taxonomy terms, leading to duplicates and inconsistency.
+
+**Fix:** Limit who can create/edit taxonomy documents. Use validation.