quality-validation

name: quality-validation description: Automated content quality validation with word count checks (800-2000 words), AI phrase blacklist detection, SEO validation (meta descriptions, images), and frontmatter verification. Use when validating generated content, checking posts before deployment, or ensuring quality standards compliance. Non-blocking warnings for minor issues.

Quality Validation Skill

Automated content validation with word count, AI phrase detection, SEO checks, and frontmatter validation.

When to Use This Skill
Skill Boundaries
Dependencies
Quick Start
Quality Gate Checks
Quality Report Format
AI Reviewer (Optional)
Common Failures & Fixes
Integration with CI/CD
Testing
Advanced Topics
Related Skills

When to Use This Skill

Activate this skill when:

User requests "quality check", "validate content", or "run quality gate"
Need to verify posts meet quality standards before publishing
Checking for AI-generated phrases (blacklist detection)
Validating SEO requirements (meta descriptions, images)
Verifying frontmatter completeness and correctness

Do NOT use this skill for:

Generating new content → Use content-generation skill
Hugo build operations → Use hugo-operations skill
Topic queue management → Use keyword-curation skill

Examples:

"Run quality checks on recent posts"
"Validate content quality"
"Check if posts pass quality gate"

Skill Boundaries

This skill handles:

✅ Word count validation (800-2000 words for EN/KO)
✅ AI phrase blacklist detection
✅ SEO validation (meta descriptions, keywords, images)
✅ Frontmatter verification (YAML syntax, required fields)
✅ References section check (2+ external links)
✅ Quality report generation (JSON format)

Defer to other skills:

❌ Content generation → Use content-generation skill
❌ Fixing content issues → Manual editing or regeneration
❌ Hugo build → Use hugo-operations skill
❌ Topic queue → Use keyword-curation skill

Dependencies

Required Python packages:

pyyaml==6.0 - YAML frontmatter parsing
python-dateutil==2.8.2 - Date validation

Installation:

pip install -r requirements.txt

Verification:

python -c "import yaml, dateutil; print('✓ All dependencies installed')"

Note: This skill does NOT require Claude API (no API costs).

Quick Start

# Run quality gate on all content
python scripts/quality_gate.py

# View results
cat quality_report.json

# Run AI reviewer (optional, requires API)
python scripts/ai_reviewer.py
cat ai_review_report.json

Quality Gate Checks

1. Word Count Validation

Requirements:

Language	Minimum	Target	Maximum
English	800	900-1,200	2,000
Korean	800	900-1,200	2,000

Check:

Counts words (EN/KO)
FAIL if below minimum
WARN if above maximum
PASS if within range

2. AI Phrase Blacklist

English: "revolutionary", "game-changer", "cutting-edge", "it's important to note", "in today's digital landscape"

Korean: "물론", "혁신적", "게임체인저", "디지털 시대", "중요한 점은"

Check:

Searches content for blacklisted phrases
FAIL if any found
Reports phrase and line number

Full list: See resources/ai-phrases.md

3. SEO Validation

Meta Description:

✅ Exists in frontmatter
✅ Length: 120-160 characters
❌ FAIL if missing or out of range

Featured Image:

✅ Exists in frontmatter
⚠️ WARN if missing (not blocking)

Keyword Density:

Target: 5-7 natural mentions (not enforced)

4. References Check

Requirements:

✅ ## References section exists
✅ 2+ external links
✅ FAIL if missing

5. Frontmatter Validation

Required Fields:

title: "Post Title"
date: 2026-01-24T18:00:00+09:00  # KST timezone
categories: ["category"]
tags: ["tag1", "tag2"]
description: "120-160 char description"
image: "https://images.unsplash.com/..."
imageCredit: "Photo by [Name](URL)"
lang: "en"  # or "ko"

Check:

✅ Valid YAML syntax
✅ All required fields present
✅ Date format correct (ISO 8601 with KST)
✅ Category valid (8 categories)
✅ Language valid (en/ko)

Quality Report Format

Location: quality_report.json

Structure:

{
  "timestamp": "2026-01-24T21:50:00+09:00",
  "files_checked": 63,
  "passed": 60,
  "failed": 3,
  "warnings": 5,
  "details": [
    {
      "file": "content/en/tech/2026-01-24-ai-trends.md",
      "status": "PASS",
      "checks": {
        "word_count": {"status": "PASS", "value": 1050},
        "ai_phrases": {"status": "PASS", "found": []},
        "seo": {"status": "PASS", "description_length": 145},
        "references": {"status": "PASS", "count": 3},
        "frontmatter": {"status": "PASS"}
      }
    }
  ]
}

Exit code:

0 - All checks passed
1 - Critical failures (blocks deployment)

AI Reviewer (Optional)

Cost: ~$0.02 per review (Claude API)

5-Criteria Scoring (1-10 scale):

Authenticity - Human tone, natural language
Value - Practical insights, actionable advice
Engagement - Clear structure, compelling flow
Technical Accuracy - Correct information
SEO Quality - Keyword integration, meta description

Recommendation Thresholds:

≥ 8.0: APPROVE (publish immediately)
6.0-7.9: REVISE (minor improvements)
< 6.0: REJECT (major rewrite)

Details: See resources/ai-reviewer.md

Common Failures & Fixes

Failure 1: Word Count Too Low

Error: Word count 650 below minimum 800

Fix:

# In scripts/generate_posts.py, line ~1100
max_tokens=12000  # Increase to 14000

# Or update system prompt
"Write 900-1200 words..."

Failure 2: AI Phrases Detected

Error: Found blacklisted phrase: "revolutionary" at line 15

Fix (Immediate): Manual edit

vim content/en/tech/2026-01-24-post.md
# Remove "revolutionary", replace with specific term

Fix (Prevent): Update prompt in scripts/generate_posts.py

Failure 3: Missing References

Error: No References section found

Fix (Immediate):

## References
1. [Source 1](https://example.com)
2. [Source 2](https://example.com)

Failure 4: Meta Description Out of Range

Error: Meta description 95 chars, should be 120-160

Fix:

description: "Expand this to 120-160 characters with relevant keywords and compelling hook"

Integration with CI/CD

GitHub Actions: .github/workflows/daily-content.yml

Steps:

- name: Quality gate (blocking)
  run: python scripts/quality_gate.py

- name: AI review (non-blocking)
  run: python scripts/ai_reviewer.py || true

Behavior:

✅ Quality gate failure → BLOCKS PR creation
⚠️ AI reviewer → INFORMATIONAL only (doesn't block)