Add SEO skills 19-28, 31-32 with full Python implementations

12 new skills: Keyword Strategy, SERP Analysis, Position Tracking, Link Building, Content Strategy, E-Commerce SEO, KPI Framework, International SEO, AI Visibility, Knowledge Graph, Competitor Intel, and Crawl Budget. ~20K lines of Python across 25 domain scripts. Updated skill 11 pipeline table and repo CLAUDE.md. Enhanced skill 18 local SEO workflow from jamie.clinic audit. Note: Skill 26 hreflang_validator.py pending (content filter block). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-13 12:05:59 +09:00
parent 159f7ec3f7
commit a3ff965b87
125 changed files with 25948 additions and 173 deletions
--- a/custom-skills/26-seo-international/code/CLAUDE.md
+++ b/custom-skills/26-seo-international/code/CLAUDE.md
@@ -0,0 +1,149 @@
+# CLAUDE.md
+
+## Overview
+
+International SEO audit tool for multi-language and multi-region website optimization. Validates hreflang tags (bidirectional, self-referencing, x-default), analyzes URL structure patterns (ccTLD vs subdomain vs subdirectory), audits content parity across language versions, checks language detection vs declared language, and analyzes international redirect logic. Supports Korean expansion patterns (ko→ja, ko→zh, ko→en).
+
+## Quick Start
+
+```bash
+pip install -r scripts/requirements.txt
+
+# Hreflang validation
+python scripts/hreflang_validator.py --url https://example.com --json
+
+# Full international SEO audit
+python scripts/international_auditor.py --url https://example.com --json
+```
+
+## Scripts
+
+| Script | Purpose | Key Output |
+|--------|---------|------------|
+| `hreflang_validator.py` | Validate hreflang tag implementation | Hreflang errors, missing bidirectional links, x-default issues |
+| `international_auditor.py` | Full international SEO audit | URL structure, content parity, redirect logic, language detection |
+| `base_client.py` | Shared utilities | RateLimiter, ConfigManager, BaseAsyncClient |
+
+## Hreflang Validator
+
+```bash
+# Validate hreflang for homepage
+python scripts/hreflang_validator.py --url https://example.com --json
+
+# Validate with sitemap-based discovery
+python scripts/hreflang_validator.py --url https://example.com --sitemap https://example.com/sitemap.xml --json
+
+# Check specific pages
+python scripts/hreflang_validator.py --urls-file pages.txt --json
+```
+
+**Capabilities**:
+- Hreflang tag extraction from HTML head, HTTP headers, and XML sitemap
+- Bidirectional validation (if page A→B, then B→A must exist)
+- Self-referencing check (each page should reference itself)
+- x-default tag verification
+- Language/region code validation (ISO 639-1 + ISO 3166-1)
+- Conflicting hreflang detection
+- Missing language version detection
+- Return tag validation (confirmation links from alternate pages)
+
+## International Auditor
+
+```bash
+# Full international audit
+python scripts/international_auditor.py --url https://example.com --json
+
+# URL structure analysis
+python scripts/international_auditor.py --url https://example.com --scope structure --json
+
+# Content parity check
+python scripts/international_auditor.py --url https://example.com --scope parity --json
+
+# Korean expansion focus
+python scripts/international_auditor.py --url https://example.com --korean-expansion --json
+```
+
+**Capabilities**:
+- URL structure analysis (ccTLD vs subdomain vs subdirectory)
+  - Recommendation engine based on business context
+- Content parity audit across language versions
+  - Page count comparison per language
+  - Key page availability check (home, about, contact, products)
+  - Content freshness comparison across languages
+- Language/locale detection vs declared language
+  - HTML lang attribute check
+  - Content-Language header check
+  - Actual content language detection
+- International redirect logic audit
+  - IP-based redirect detection
+  - Accept-Language redirect behavior
+  - Geo-redirect best practices (suggest→don't force)
+- Korean expansion patterns (ko→ja, ko→zh, ko→en)
+  - Priority market recommendations for Korean businesses
+  - CJK-specific URL encoding issues
+  - Regional search engine considerations (Naver, Baidu, Yahoo Japan)
+
+## Ahrefs MCP Tools Used
+
+| Tool | Purpose |
+|------|---------|
+| `site-explorer-metrics-by-country` | Country-level traffic distribution |
+| `site-explorer-organic-keywords` | Keywords by country filter |
+
+## Output Format
+
+```json
+{
+  "url": "https://example.com",
+  "url_structure": "subdirectory",
+  "languages_detected": ["ko", "en", "ja"],
+  "hreflang_validation": {
+    "total_pages_checked": 50,
+    "errors": [],
+    "warnings": [],
+    "missing_bidirectional": [],
+    "missing_self_reference": [],
+    "x_default_present": true
+  },
+  "content_parity": {
+    "ko": {"pages": 150, "freshness_score": 90},
+    "en": {"pages": 120, "freshness_score": 75},
+    "ja": {"pages": 80, "freshness_score": 60}
+  },
+  "redirect_logic": {
+    "ip_based_redirect": false,
+    "language_based_redirect": true,
+    "is_forced": false
+  },
+  "score": 68,
+  "timestamp": "2025-01-01T00:00:00"
+}
+```
+
+## Notion Output (Required)
+
+**IMPORTANT**: All audit reports MUST be saved to the OurDigital SEO Audit Log database.
+
+### Database Configuration
+
+| Field | Value |
+|-------|-------|
+| Database ID | `2c8581e5-8a1e-8035-880b-e38cefc2f3ef` |
+| URL | https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef |
+
+### Required Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| Issue | Title | Report title (Korean + date) |
+| Site | URL | Audited website URL |
+| Category | Select | International SEO |
+| Priority | Select | Based on hreflang error count |
+| Found Date | Date | Audit date (YYYY-MM-DD) |
+| Audit ID | Rich Text | Format: INTL-YYYYMMDD-NNN |
+
+### Language Guidelines
+
+- Report content in Korean (한국어)
+- Keep technical English terms as-is (e.g., hreflang, x-default, ccTLD)
+- URLs and code remain unchanged
--- a/custom-skills/26-seo-international/code/scripts/base_client.py
+++ b/custom-skills/26-seo-international/code/scripts/base_client.py
@@ -0,0 +1,207 @@
+"""
+Base Client - Shared async client utilities
+===========================================
+Purpose: Rate-limited async operations for API clients
+Python: 3.10+
+"""
+
+import asyncio
+import logging
+import os
+from asyncio import Semaphore
+from datetime import datetime
+from typing import Any, Callable, TypeVar
+
+from dotenv import load_dotenv
+from tenacity import (
+    retry,
+    stop_after_attempt,
+    wait_exponential,
+    retry_if_exception_type,
+)
+
+# Load environment variables
+load_dotenv()
+
+# Logging setup
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(message)s",
+)
+
+T = TypeVar("T")
+
+
+class RateLimiter:
+    """Rate limiter using token bucket algorithm."""
+
+    def __init__(self, rate: float, per: float = 1.0):
+        """
+        Initialize rate limiter.
+
+        Args:
+            rate: Number of requests allowed
+            per: Time period in seconds (default: 1 second)
+        """
+        self.rate = rate
+        self.per = per
+        self.tokens = rate
+        self.last_update = datetime.now()
+        self._lock = asyncio.Lock()
+
+    async def acquire(self) -> None:
+        """Acquire a token, waiting if necessary."""
+        async with self._lock:
+            now = datetime.now()
+            elapsed = (now - self.last_update).total_seconds()
+            self.tokens = min(self.rate, self.tokens + elapsed * (self.rate / self.per))
+            self.last_update = now
+
+            if self.tokens < 1:
+                wait_time = (1 - self.tokens) * (self.per / self.rate)
+                await asyncio.sleep(wait_time)
+                self.tokens = 0
+            else:
+                self.tokens -= 1
+
+
+class BaseAsyncClient:
+    """Base class for async API clients with rate limiting."""
+
+    def __init__(
+        self,
+        max_concurrent: int = 5,
+        requests_per_second: float = 3.0,
+        logger: logging.Logger | None = None,
+    ):
+        """
+        Initialize base client.
+
+        Args:
+            max_concurrent: Maximum concurrent requests
+            requests_per_second: Rate limit
+            logger: Logger instance
+        """
+        self.semaphore = Semaphore(max_concurrent)
+        self.rate_limiter = RateLimiter(requests_per_second)
+        self.logger = logger or logging.getLogger(self.__class__.__name__)
+        self.stats = {
+            "requests": 0,
+            "success": 0,
+            "errors": 0,
+            "retries": 0,
+        }
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=2, max=10),
+        retry=retry_if_exception_type(Exception),
+    )
+    async def _rate_limited_request(
+        self,
+        coro: Callable[[], Any],
+    ) -> Any:
+        """Execute a request with rate limiting and retry."""
+        async with self.semaphore:
+            await self.rate_limiter.acquire()
+            self.stats["requests"] += 1
+            try:
+                result = await coro()
+                self.stats["success"] += 1
+                return result
+            except Exception as e:
+                self.stats["errors"] += 1
+                self.logger.error(f"Request failed: {e}")
+                raise
+
+    async def batch_requests(
+        self,
+        requests: list[Callable[[], Any]],
+        desc: str = "Processing",
+    ) -> list[Any]:
+        """Execute multiple requests concurrently."""
+        try:
+            from tqdm.asyncio import tqdm
+            has_tqdm = True
+        except ImportError:
+            has_tqdm = False
+
+        async def execute(req: Callable) -> Any:
+            try:
+                return await self._rate_limited_request(req)
+            except Exception as e:
+                return {"error": str(e)}
+
+        tasks = [execute(req) for req in requests]
+
+        if has_tqdm:
+            results = []
+            for coro in tqdm.as_completed(tasks, total=len(tasks), desc=desc):
+                result = await coro
+                results.append(result)
+            return results
+        else:
+            return await asyncio.gather(*tasks, return_exceptions=True)
+
+    def print_stats(self) -> None:
+        """Print request statistics."""
+        self.logger.info("=" * 40)
+        self.logger.info("Request Statistics:")
+        self.logger.info(f"  Total Requests: {self.stats['requests']}")
+        self.logger.info(f"  Successful: {self.stats['success']}")
+        self.logger.info(f"  Errors: {self.stats['errors']}")
+        self.logger.info("=" * 40)
+
+
+class ConfigManager:
+    """Manage API configuration and credentials."""
+
+    def __init__(self):
+        load_dotenv()
+
+    @property
+    def google_credentials_path(self) -> str | None:
+        """Get Google service account credentials path."""
+        # Prefer SEO-specific credentials, fallback to general credentials
+        seo_creds = os.path.expanduser("~/.credential/ourdigital-seo-agent.json")
+        if os.path.exists(seo_creds):
+            return seo_creds
+        return os.getenv("GOOGLE_APPLICATION_CREDENTIALS")
+
+    @property
+    def pagespeed_api_key(self) -> str | None:
+        """Get PageSpeed Insights API key."""
+        return os.getenv("PAGESPEED_API_KEY")
+
+    @property
+    def custom_search_api_key(self) -> str | None:
+        """Get Custom Search API key."""
+        return os.getenv("CUSTOM_SEARCH_API_KEY")
+
+    @property
+    def custom_search_engine_id(self) -> str | None:
+        """Get Custom Search Engine ID."""
+        return os.getenv("CUSTOM_SEARCH_ENGINE_ID")
+
+    @property
+    def notion_token(self) -> str | None:
+        """Get Notion API token."""
+        return os.getenv("NOTION_TOKEN") or os.getenv("NOTION_API_KEY")
+
+    def validate_google_credentials(self) -> bool:
+        """Validate Google credentials are configured."""
+        creds_path = self.google_credentials_path
+        if not creds_path:
+            return False
+        return os.path.exists(creds_path)
+
+    def get_required(self, key: str) -> str:
+        """Get required environment variable or raise error."""
+        value = os.getenv(key)
+        if not value:
+            raise ValueError(f"Missing required environment variable: {key}")
+        return value
+
+
+# Singleton config instance
+config = ConfigManager()
--- a/custom-skills/26-seo-international/code/scripts/international_auditor.py
+++ b/custom-skills/26-seo-international/code/scripts/international_auditor.py
--- a/custom-skills/26-seo-international/code/scripts/requirements.txt
+++ b/custom-skills/26-seo-international/code/scripts/requirements.txt
@@ -0,0 +1,10 @@
+# 26-seo-international dependencies
+requests>=2.31.0
+aiohttp>=3.9.0
+beautifulsoup4>=4.12.0
+lxml>=5.1.0
+langdetect>=1.0.9
+tenacity>=8.2.0
+tqdm>=4.66.0
+python-dotenv>=1.0.0
+rich>=13.7.0
--- a/custom-skills/26-seo-international/desktop/SKILL.md
+++ b/custom-skills/26-seo-international/desktop/SKILL.md
@@ -0,0 +1,124 @@
+---
+name: seo-international
+description: |
+  International SEO audit and hreflang validation for multi-language and multi-region websites.
+  Triggers: hreflang, international SEO, multi-language, multi-region, content parity, x-default, ccTLD, 다국어 SEO.
+---
+
+# International SEO Audit
+
+## Purpose
+
+Audit international SEO implementation: hreflang tags, URL structure patterns, content parity across language versions, redirect logic, and Korean expansion strategies. Identify issues preventing proper multi-language indexing.
+
+## Core Capabilities
+
+1. **Hreflang Validation** - Bidirectional links, self-reference, x-default, language code validation
+2. **URL Structure Analysis** - ccTLD vs subdomain vs subdirectory pattern detection
+3. **Content Parity Audit** - Page count comparison, key page availability across languages
+4. **Redirect Logic Audit** - IP-based, Accept-Language redirects, forced redirect detection
+5. **Korean Expansion** - Priority markets (ja, zh, en), CJK URL issues, regional search engines
+
+## MCP Tool Usage
+
+### Ahrefs for Country Metrics
+```
+mcp__ahrefs__site-explorer-metrics-by-country: Country-level traffic distribution
+mcp__ahrefs__site-explorer-organic-keywords: Keywords filtered by country
+```
+
+### Notion for Report Storage
+```
+mcp__notion__notion-create-pages: Save audit report to SEO Audit Log database
+```
+
+### WebSearch for Best Practices
+```
+WebSearch: Research hreflang implementation guides and regional search engine requirements
+```
+
+## Workflow
+
+### 1. Hreflang Validation
+1. Fetch target URL and extract hreflang tags (HTML head, HTTP headers)
+2. If sitemap provided, also extract xhtml:link hreflang from XML sitemap
+3. Validate language codes (ISO 639-1) and region codes (ISO 3166-1)
+4. Check bidirectional links (if A references B, B must reference A)
+5. Verify self-referencing tags on each page
+6. Check x-default tag presence and validity
+7. Detect conflicting hreflang for same language-region
+8. Report all errors with severity levels
+
+### 2. URL Structure Analysis
+1. Crawl known language versions of the site
+2. Classify pattern: ccTLD (example.kr), subdomain (ko.example.com), subdirectory (example.com/ko/)
+3. Check consistency across all language versions
+4. Provide recommendation based on business context
+
+### 3. Content Parity Audit
+1. Discover all language versions from hreflang tags
+2. Count pages per language version
+3. Check availability of key pages (home, about, contact, products/services)
+4. Compare content freshness (last modified dates) across versions
+5. Flag significant gaps in content availability
+
+### 4. Redirect Logic Audit
+1. Test URL with different Accept-Language headers (ko, en, ja, zh)
+2. Check if redirects are forced (no way to override) vs suggested (banner/popup)
+3. Flag forced geo/language redirects as anti-pattern
+4. Recommend proper implementation (suggest, do not force)
+
+### 5. Korean Expansion Analysis (Optional)
+1. Analyze current traffic by country via Ahrefs
+2. Recommend priority target markets for Korean businesses
+3. Check CJK-specific URL encoding issues
+4. Advise on regional search engines (Naver, Baidu, Yahoo Japan)
+
+## Output Format
+
+```markdown
+## 다국어 SEO 감사: [domain]
+
+### Hreflang 검증
+- 검사 페이지 수: [count]
+- 오류: [count] (심각 [count], 경고 [count])
+- 양방향 링크 누락: [list]
+- 자기참조 누락: [list]
+- x-default: [있음/없음]
+
+### URL 구조
+- 패턴: [ccTLD/subdomain/subdirectory]
+- 일관성: [양호/비일관]
+- 권장사항: [recommendation]
+
+### 콘텐츠 동등성
+| 언어 | 페이지 수 | 핵심 페이지 | 최신성 점수 |
+|------|----------|------------|-----------|
+| ko   | 150      | 5/5        | 90        |
+| en   | 120      | 4/5        | 75        |
+
+### 리다이렉트 로직
+- IP 기반 리다이렉트: [있음/없음]
+- 언어 기반 리다이렉트: [있음/없음]
+- 강제 리다이렉트: [있음/없음] (없어야 정상)
+
+### 종합 점수: [score]/100
+
+### 권장 조치사항
+1. [Priority fixes in Korean]
+```
+
+## Notion Output (Required)
+
+All audit reports MUST be saved to OurDigital SEO Audit Log:
+- **Database ID**: `2c8581e5-8a1e-8035-880b-e38cefc2f3ef`
+- **Properties**: Issue (title), Site (url), Category (International SEO), Priority, Found Date, Audit ID
+- **Language**: Korean with English technical terms
+- **Audit ID Format**: INTL-YYYYMMDD-NNN
+
+## Limitations
+
+- Cannot detect server-side IP-based redirects without proxy testing
+- Content language detection requires sufficient text content
+- Large sites (10,000+ pages) require sampling approach
+- Sitemap-based hreflang requires XML sitemap access
--- a/custom-skills/26-seo-international/desktop/skill.yaml
+++ b/custom-skills/26-seo-international/desktop/skill.yaml
@@ -0,0 +1,8 @@
+name: seo-international
+description: |
+  International SEO audit and hreflang validation. Triggers: hreflang, international SEO, multi-language, multi-region, content parity, x-default, ccTLD.
+allowed-tools:
+  - mcp__ahrefs__*
+  - mcp__notion__*
+  - WebSearch
+  - WebFetch
--- a/custom-skills/26-seo-international/desktop/tools/ahrefs.md
+++ b/custom-skills/26-seo-international/desktop/tools/ahrefs.md
@@ -0,0 +1,43 @@
+# Ahrefs
+
+## Tools Used
+
+### site-explorer-metrics-by-country
+- **Purpose**: Get country-level organic traffic distribution
+- **Usage**: Analyze which countries drive traffic to identify international SEO opportunities
+- **Parameters**: `target` (domain), `country` (optional filter)
+- **Example**:
+  ```
+  mcp__ahrefs__site-explorer-metrics-by-country:
+    target: example.com
+  ```
+
+### site-explorer-organic-keywords
+- **Purpose**: Get organic keyword rankings filtered by country
+- **Usage**: Analyze keyword performance in specific markets
+- **Parameters**: `target` (domain), `country` (ISO country code)
+- **Example**:
+  ```
+  mcp__ahrefs__site-explorer-organic-keywords:
+    target: example.com
+    country: kr
+  ```
+
+## Configuration
+
+- Ahrefs MCP server must be connected in Claude Desktop
+- API access requires active Ahrefs subscription
+
+## Common Patterns
+
+### Country Traffic Analysis
+1. Call `site-explorer-metrics-by-country` to get traffic distribution
+2. Identify top countries by organic traffic share
+3. Compare with hreflang implementation coverage
+4. Flag countries with traffic but no localized version
+
+### Keyword Gap by Market
+1. Call `site-explorer-organic-keywords` with country filter
+2. Compare keyword counts across target markets
+3. Identify markets with low keyword coverage
+4. Recommend content localization priorities
--- a/custom-skills/26-seo-international/desktop/tools/notion.md
+++ b/custom-skills/26-seo-international/desktop/tools/notion.md
@@ -0,0 +1,51 @@
+# Notion
+
+## Database Configuration
+
+| Field | Value |
+|-------|-------|
+| Database ID | `2c8581e5-8a1e-8035-880b-e38cefc2f3ef` |
+| URL | https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef |
+
+## Required Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| Issue | Title | Report title in Korean with date |
+| Site | URL | Audited website URL |
+| Category | Select | "International SEO" |
+| Priority | Select | Based on hreflang error severity |
+| Found Date | Date | Audit date (YYYY-MM-DD) |
+| Audit ID | Rich Text | Format: INTL-YYYYMMDD-NNN |
+
+## Example: Create Audit Report
+
+```
+mcp__notion__notion-create-pages:
+  pages:
+    - parent_id: "2c8581e5-8a1e-8035-880b-e38cefc2f3ef"
+      parent_type: "database"
+      title: "다국어 SEO 감사 - example.com (2025-01-15)"
+      properties:
+        Site:
+          url: "https://example.com"
+        Category:
+          select:
+            name: "International SEO"
+        Priority:
+          select:
+            name: "High"
+        Found Date:
+          date:
+            start: "2025-01-15"
+        Audit ID:
+          rich_text:
+            - text:
+                content: "INTL-20250115-001"
+```
+
+## Language Guidelines
+
+- Report content in Korean (한국어)
+- Keep technical English terms as-is (hreflang, x-default, ccTLD, subdomain)
+- URLs and code remain unchanged
--- a/custom-skills/26-seo-international/desktop/tools/websearch.md
+++ b/custom-skills/26-seo-international/desktop/tools/websearch.md
@@ -0,0 +1,40 @@
+# WebSearch
+
+## Purpose
+
+Search the web for current international SEO best practices, hreflang implementation guides, and regional search engine requirements.
+
+## Common Search Queries
+
+### Hreflang Best Practices
+```
+WebSearch: "hreflang implementation best practices 2025"
+WebSearch: "hreflang common errors fix"
+WebSearch: "x-default hreflang when to use"
+```
+
+### Regional Search Engines
+```
+WebSearch: "Naver SEO requirements Korean websites"
+WebSearch: "Baidu SEO China market entry"
+WebSearch: "Yahoo Japan SEO vs Google Japan"
+```
+
+### International URL Structure
+```
+WebSearch: "ccTLD vs subdomain vs subdirectory international SEO"
+WebSearch: "Google recommendations international targeting"
+```
+
+### Korean Market Expansion
+```
+WebSearch: "Korean business international SEO Japan market"
+WebSearch: "CJK URL encoding SEO best practices"
+```
+
+## Usage Pattern
+
+1. Search for domain-specific international SEO intelligence
+2. Verify current Google documentation on hreflang
+3. Research regional search engine requirements for target markets
+4. Find competitor international SEO strategies