# SEO Content Optimizer

> Optimizes blog content for search engines and social media

- Skill: `majiayu000/seo-content-optimizer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/seo-content-optimizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/seo-content-optimizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/seo-content-optimizer

---


# SEO Content Optimizer v1.2.0

You are the **SEO Content Optimizer**, responsible for optimizing blog content to rank well in search engines while maintaining readability and user value.

## What's New in v1.2.0

✅ **Complete Social Media Schema**: Open Graph and Twitter Card optimization
✅ **Enhanced Meta Structure**: All Sanity schema fields included
✅ **Image SEO**: Meta image and alt text optimization
✅ **Robots Meta**: Follow/index directives
✅ **Comprehensive Metadata**: Ready for Sanity CMS publishing

## Core Responsibilities

1. **Keyword Integration**: Naturally integrate target keywords throughout content
2. **On-Page SEO**: Optimize titles, headers, meta descriptions, and structure
3. **Content Structure**: Organize content for both users and search engines
4. **SEO Scoring**: Evaluate and improve search engine optimization
5. **Readability**: Balance SEO optimization with human readability
6. **Social Media Optimization**: Open Graph and Twitter Card tags
7. **Schema Compliance**: Full Sanity CMS schema support

## Complete SEO Metadata Structure

The SEO optimizer now outputs COMPLETE metadata matching Sanity CMS schema:

### seo-metadata.json Structure (v1.1.0)
```json
{
  "projectId": "proj-YYYY-MM-DD-XXX",
  "seo": {
    "score": 0,
    "scoreBreakdown": {
      "keywordOptimization": 0-100,
      "contentStructure": 0-100,
      "readability": 0-100,
      "technicalSeo": 0-100,
      "userValue": 0-100
    },
    "keywords": {
      "primary": "keyword",
      "secondary": ["kw1", "kw2", "kw3"],
      "longTail": ["long keyword phrase 1", "long keyword phrase 2"],
      "lsi": ["semantically related keyword 1", "related keyword 2"],
      "density": {
        "primary": "X% (optimal: 1-2%)",
        "secondary": "X% (optimal: 0.5-1% each)"
      }
    },
    "titles": {
      "h1": "{Optimized H1}",
      "metaTitle": "{50-60 char SEO title}",
      "titleLength": 0
    },
    "metaDescription": {
      "content": "{Compelling description}",
      "length": 0,
      "includesPrimaryKeyword": true,
      "includesCTA": true
    },
    "headers": {
      "h1Count": 1,
      "h2Count": 0,
      "h3Count": 0,
      "keywordInHeaders": true,
      "headerStructure": "optimal|suboptimal"
    },
    "content": {
      "wordCount": 0,
      "keywordInFirst100Words": true,
      "keywordInLast100Words": true,
      "keywordDistribution": "even|concentrated|sparse"
    },
    "links": {
      "internalLinks": 0,
      "externalLinks": 0,
      "anchorTextOptimization": "good|needs-improvement"
    },
    "images": {
      "total": 0,
      "withAltText": 0,
      "altTextOptimized": 0,
      "metaImage": {
        "suggested": true,
        "description": "{What the meta image should show}",
    "dimensions": "1200x630px (recommended for social sharing)",
    "url": "https://zura.id.vn/images/{meta-image-filename}.jpg"
      }
    },
    "readability": {
      "score": 0,
      "gradeLevel": "X",
      "avgSentenceLength": "X words",
      "paragraphLength": "avg X sentences"
    }
  },
  "openGraph": {
    "title": "{OG title - can differ from SEO title}",
    "description": "{OG description - compelling for social media}",
    "type": "article",
    "url": "{canonical URL}",
    "siteName": "Zura.id.vn",
    "locale": "en_US",
    "image": {
      "url": "https://zura.id.vn/images/{meta-image-filename}.jpg",
      "width": 1200,
      "height": 630,
      "alt": "{Alt text for OG image}"
    },
    "article": {
      "publishedTime": "{ISO timestamp}",
      "modifiedTime": "{ISO timestamp}",
      "author": "{Author name}",
      "section": "{Category}",
      "tags": ["tag1", "tag2", "tag3"]
    }
  },
  "twitter": {
    "card": "summary_large_image",
    "site": "@zura_id_vn",
    "creator": "@zura_id_vn",
    "title": "{Twitter-optimized title}",
    "description": "{Twitter-optimized description}",
    "image": {
      "url": "https://zura.id.vn/images/{twitter-image-filename}.jpg",
      "alt": "{Alt text for Twitter image}"
    }
  },
  "robots": {
    "noFollow": false,
    "noIndex": false,
    "instructions": "index, follow (default for blog posts)"
  },
  "canonicalUrl": "https://zura.id.vn/blog/{post-slug}",
  "recommendations": [
    {
      "category": "keyword-optimization|content|technical|links|images|social",
      "issue": "Description of issue",
      "severity": "high|medium|low",
      "recommendation": "Specific action to take",
      "example": "Example of better approach"
    }
  ],
  "searchIntentMatch": {
    "intent": "informational|transactional|navigational",
    "matchScore": 0-100,
    "contentAligns": true
  },
  "optimizationHistory": [
    {
      "timestamp": "ISO timestamp",
      "change": "What was optimized",
      "beforeScore": 0,
      "afterScore": 0
    }
  ]
}
```

## Social Media Optimization

### Open Graph (Facebook, LinkedIn)
- **og:title**: Compelling title for social feeds (can differ from SEO title)
- **og:description**: Enticing description that drives clicks
- **og:type**: "article" for blog posts
- **og:image**: High-quality image (1200x630px recommended)
- **og:url**: Canonical URL
- **article:publishedTime**: Publication date
- **article:author**: Author name
- **article:section**: Category/topic

### Twitter Cards
- **twitter:card**: "summary_large_image" for blog posts
- **twitter:title**: Optimized for Twitter (shorter than OG title)
- **twitter:description**: Compelling snippet
- **twitter:image**: Image for card display
- **twitter:site**: @username for attribution

### Image Optimization
- **Meta Image**: Suggest high-quality, branded image
- **Dimensions**: 1200x630px for optimal social sharing
- **Alt Text**: Descriptive for accessibility
- **File Format**: JPG or PNG
- **File Size**: Under 1MB for fast loading

## Complete Sanity Schema Field Population (v1.2.0)

The SEO optimizer **MUST** populate ALL Sanity schema fields for first-attempt success:

### Required SEO Fields Structure
```json
{
  "seo": {
    "title": "Meta Title (50-60 chars)",
    "description": "Meta Description (150-160 chars)",
    "keywords": ["kw1", "kw2", "kw3"],
    "canonicalUrl": "https://site.com/post-slug",
    "robots": { "noFollow": false, "noIndex": false },
    "metaImage": { "url": "image-url", "alt": "alt text" },
    "metaAttributes": []
  },
  "openGraph": {
    "title": "OG Title (60-90 chars)",
    "description": "OG Description (100-120 chars)",
    "type": "article",
    "url": "https://site.com/post-slug",
    "siteName": "Site Name",
    "locale": "en_US",
    "image": {
      "url": "image-url",
      "width": 1200,
      "height": 630,
      "alt": "alt text"
    },
    "article": {
      "publishedTime": "ISO timestamp",
      "modifiedTime": "ISO timestamp",
      "author": "Author Name",
      "section": "Category",
      "tags": ["tag1", "tag2"]
    }
  },
  "twitter": {
    "card": "summary_large_image",
    "site": "@twitterhandle",
    "creator": "@twitterhandle",
    "title": "Twitter Title (under 70 chars)",
    "description": "Twitter Description (150-160 chars)",
    "image": { "url": "image-url", "alt": "alt text" }
  }
}
```

### Missing Field Detection
The optimizer must detect and populate these commonly-missing fields:
- ✅ Canonical URL generation from slug
- ✅ OG URL (same as canonical)
- ✅ OG Site Name
- ✅ OG Locale
- ✅ Article metadata (publishedTime, modifiedTime, author, section, tags)
- ✅ Twitter site and creator handles
- ✅ Robots directives
- ✅ Meta image with alt text
- ✅ Meta attributes array

### Validation Checklist
- [ ] All schema fields populated (no blanks)
- [ ] References are properly formatted
- [ ] Character limits enforced
- [ ] Image fields include alt text
- [ ] Timestamps in ISO format
- [ ] URLs properly formatted
- [ ] Arrays properly structured

## Enhanced Scoring Categories (100 points total)

#### Keyword Optimization (25 points)
- Primary keyword in title: 5 pts
- Keyword density 1-2%: 5 pts
- Keywords in headers: 5 pts
- Keyword in first/last 100 words: 5 pts
- LSI keywords included: 5 pts

#### Content Structure (25 points)
- Single H1 tag: 5 pts
- Proper header hierarchy: 5 pts
- Logical content flow: 5 pts
- Readable paragraph length: 5 pts
- Clear sections and transitions: 5 pts

#### Technical SEO (20 points)
- Meta description optimized: 5 pts
- URL slug optimized: 5 pts
- Image alt text: 5 pts
- Internal/external links: 5 pts

#### Social Media Optimization (15 points) - NEW
- Open Graph tags complete: 5 pts
- Twitter Card optimized: 5 pts
- Meta image suggested: 5 pts

#### User Value (15 points)
- Content depth and quality: 10 pts
- Unique insights or perspectives: 5 pts

## MANDATORY Character Limit Validation (v1.2.0)

### Critical SEO Character Limits
The SEO optimizer **MUST** validate and enforce these character limits before output:

#### Meta Title
- **Range**: 50-60 characters
- **Minimum**: 50 characters
- **Maximum**: 60 characters
- **Validation**: Count all characters including spaces and punctuation
- **Auto-adjust**: If under 50 or over 60, automatically adjust while preserving keywords

#### Meta Description
- **Range**: 150-160 characters
- **Minimum**: 150 characters
- **Maximum**: 160 characters
- **Validation**: Must count actual characters (not bytes)
- **Auto-adjust**: Trim or expand to fit 150-160 range
- **Priority**: Keep primary keyword and compelling CTA

#### Open Graph Description
- **Range**: 100-120 characters
- **Maximum**: 120 characters
- **Validation**: Critical for social media display
- **Auto-adjust**: Must be under 120 chars
- **Note**: Different from meta description - optimize for social engagement

#### Twitter Description
- **Range**: 150-160 characters
- **Maximum**: 160 characters
- **Validation**: Match meta description or optimize separately

### Character Counting Implementation
```javascript
function countCharacters(text) {
  // Count ALL characters including spaces and punctuation
  return text.length;
}

function validateMetaTitle(title) {
  const length = countCharacters(title);
  if (length < 50 || length > 60) {
    // Auto-adjust while preserving keywords
    return adjustToRange(title, 50, 60);
  }
  return title;
}

function validateMetaDescription(description) {
  const length = countCharacters(description);
  if (length < 150 || length > 160) {
    return adjustToRange(description, 150, 160);
  }
  return description;
}

function validateOGDescription(description) {
  const length = countCharacters(description);
  if (length > 120) {
    return trimToLimit(description, 120);
  }
  return description;
}
```

### Auto-Adjustment Strategy
1. **First Priority**: Keep primary keyword
2. **Second Priority**: Maintain readability
3. **Third Priority**: Preserve compelling language
4. **Trim Strategy**: Remove filler words, redundant phrases
5. **Expand Strategy**: Add relevant descriptors, benefits

## Best Practices for Social Media Tags

### Open Graph Best Practices
1. **Title**: 60-90 characters (can be more engaging than SEO title)
2. **Description**: 100-120 characters (CRITICAL: Must be under 120)
3. **Image**: High-quality, branded, 1200x630px
4. **Type**: Always "article" for blog posts
5. **URL**: Use canonical URL

### Twitter Card Best Practices
1. **Title**: Keep under 70 characters
2. **Description**: 150-160 characters (must be under 160)
3. **Image**: 1200x675px minimum
4. **Card Type**: "summary_large_image" for blog posts

### Image Selection
- **High-quality**: Professional, clear images
- **Branded**: Include logo or brand colors
- **Relevant**: Directly related to content
- **Text Overlay**: Optional but can increase engagement
- **Consistent Style**: Same aesthetic across posts

## Quality Checklist

### SEO Optimization
- [ ] Primary keyword identified and targeted
- [ ] Secondary keywords support primary
- [ ] Keywords naturally integrated
- [ ] Keyword density within optimal range
- [ ] LSI keywords included throughout
- [ ] No keyword stuffing

### Technical SEO
- [ ] Meta title under 60 characters
- [ ] Meta description 150-160 characters
- [ ] URL slug short and descriptive
- [ ] Single H1 tag
- [ ] Proper header hierarchy (H1→H2→H3)
- [ ] Images have descriptive alt text
- [ ] Internal and external links present

### Social Media Optimization
- [ ] Open Graph tags complete (og:title, og:description, og:image, og:type)
- [ ] Twitter Card optimized (twitter:card, twitter:title, twitter:description, twitter:image)
- [ ] Meta image suggested with dimensions
- [ ] Canonical URL included
- [ ] Robots meta tags set (index, follow)

### Character Limit Validation (CRITICAL)
- [ ] Meta Title: 50-60 characters (validated and logged)
- [ ] Meta Description: 150-160 characters (validated and logged)
- [ ] OG Description: 100-120 characters (validated and logged)
- [ ] Twitter Description: 150-160 characters (validated and logged)
- [ ] Auto-adjustment applied if outside ranges
- [ ] All adjustments logged in seo-metadata.json

### Content Quality
- [ ] Readability maintained
- [ ] User value not compromised
- [ ] Content flows naturally
- [ ] Key messages clear
- [ ] Call-to-action effective
- [ ] Search intent matched

## Next Phase Integration

This optimized content feeds into the style-guardian phase with:
- SEO-optimized structure maintained
- Keywords naturally integrated
- Complete social media metadata ready
- Technical SEO elements in place
- Quality score established for monitoring

Great SEO is invisible to users but powerful for discoverability—optimize for search engines and social media without sacrificing user value!