gkt-node 3.3.0

package/assets/.agent/skills/seo-fundamentals/scripts/seo_checker.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""
+SEO Checker - Search Engine Optimization Audit
+Checks HTML/JSX/TSX pages for SEO best practices.
+
+PURPOSE:
+    - Verify meta tags, titles, descriptions
+    - Check Open Graph tags for social sharing
+    - Validate heading hierarchy
+    - Check image accessibility (alt attributes)
+
+WHAT IT CHECKS:
+    - HTML files (actual web pages)
+    - JSX/TSX files (React page components)
+    - Only files that are likely PUBLIC pages
+
+Usage:
+    python seo_checker.py <project_path>
+"""
+import sys
+import json
+import re
+from pathlib import Path
+from datetime import datetime
+
+# Fix Windows console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+    pass
+
+
+# Directories to skip
+SKIP_DIRS = {
+    'node_modules', '.next', 'dist', 'build', '.git', '.github',
+    '__pycache__', '.vscode', '.idea', 'coverage', 'test', 'tests',
+    '__tests__', 'spec', 'docs', 'documentation', 'examples'
+}
+
+# Files to skip (not pages)
+SKIP_PATTERNS = [
+    'config', 'setup', 'util', 'helper', 'hook', 'context', 'store',
+    'service', 'api', 'lib', 'constant', 'type', 'interface', 'mock',
+    '.test.', '.spec.', '_test.', '_spec.'
+]
+
+
+def is_page_file(file_path: Path) -> bool:
+    """Check if this file is likely a public-facing page."""
+    name = file_path.name.lower()
+    stem = file_path.stem.lower()
+    
+    # Skip utility/config files
+    if any(skip in name for skip in SKIP_PATTERNS):
+        return False
+    
+    # Check path - pages in specific directories are likely pages
+    parts = [p.lower() for p in file_path.parts]
+    page_dirs = ['pages', 'app', 'routes', 'views', 'screens']
+    
+    if any(d in parts for d in page_dirs):
+        return True
+    
+    # Filename indicators for pages
+    page_names = ['page', 'index', 'home', 'about', 'contact', 'blog', 
+                  'post', 'article', 'product', 'landing', 'layout']
+    
+    if any(p in stem for p in page_names):
+        return True
+    
+    # HTML files are usually pages
+    if file_path.suffix.lower() in ['.html', '.htm']:
+        return True
+    
+    return False
+
+
+def find_pages(project_path: Path) -> list:
+    """Find page files to check."""
+    patterns = ['**/*.html', '**/*.htm', '**/*.jsx', '**/*.tsx']
+    
+    files = []
+    for pattern in patterns:
+        for f in project_path.glob(pattern):
+            # Skip excluded directories
+            if any(skip in f.parts for skip in SKIP_DIRS):
+                continue
+            
+            # Check if it's likely a page
+            if is_page_file(f):
+                files.append(f)
+    
+    return files[:50]  # Limit to 50 files
+
+
+def check_page(file_path: Path) -> dict:
+    """Check a single page for SEO issues."""
+    issues = []
+    
+    try:
+        content = file_path.read_text(encoding='utf-8', errors='ignore')
+    except Exception as e:
+        return {"file": str(file_path.name), "issues": [f"Error: {e}"]}
+    
+    # Detect if this is a layout/template file (has Head component)
+    is_layout = 'Head>' in content or '<head' in content.lower()
+    
+    # 1. Title tag
+    has_title = '<title' in content.lower() or 'title=' in content or 'Head>' in content
+    if not has_title and is_layout:
+        issues.append("Missing <title> tag")
+    
+    # 2. Meta description
+    has_description = 'name="description"' in content.lower() or 'name=\'description\'' in content.lower()
+    if not has_description and is_layout:
+        issues.append("Missing meta description")
+    
+    # 3. Open Graph tags
+    has_og = 'og:' in content or 'property="og:' in content.lower()
+    if not has_og and is_layout:
+        issues.append("Missing Open Graph tags")
+    
+    # 4. Heading hierarchy - multiple H1s
+    h1_matches = re.findall(r'<h1[^>]*>', content, re.I)
+    if len(h1_matches) > 1:
+        issues.append(f"Multiple H1 tags ({len(h1_matches)})")
+    
+    # 5. Images without alt
+    img_pattern = r'<img[^>]+>'
+    imgs = re.findall(img_pattern, content, re.I)
+    for img in imgs:
+        if 'alt=' not in img.lower():
+            issues.append("Image missing alt attribute")
+            break
+        if 'alt=""' in img or "alt=''" in img:
+            issues.append("Image has empty alt attribute")
+            break
+    
+    # 6. Check for canonical link (nice to have)
+    # has_canonical = 'rel="canonical"' in content.lower()
+    
+    return {
+        "file": str(file_path.name),
+        "issues": issues
+    }
+
+
+def main():
+    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    
+    print(f"\n{'='*60}")
+    print(f"  SEO CHECKER - Search Engine Optimization Audit")
+    print(f"{'='*60}")
+    print(f"Project: {project_path}")
+    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("-"*60)
+    
+    # Find pages
+    pages = find_pages(project_path)
+    
+    if not pages:
+        print("\n[!] No page files found.")
+        print("    Looking for: HTML, JSX, TSX in pages/app/routes directories")
+        output = {"script": "seo_checker", "files_checked": 0, "passed": True}
+        print("\n" + json.dumps(output, indent=2))
+        sys.exit(0)
+    
+    print(f"Found {len(pages)} page files to analyze\n")
+    
+    # Check each page
+    all_issues = []
+    for f in pages:
+        result = check_page(f)
+        if result["issues"]:
+            all_issues.append(result)
+    
+    # Summary
+    print("=" * 60)
+    print("SEO ANALYSIS RESULTS")
+    print("=" * 60)
+    
+    if all_issues:
+        # Group by issue type
+        issue_counts = {}
+        for item in all_issues:
+            for issue in item["issues"]:
+                issue_counts[issue] = issue_counts.get(issue, 0) + 1
+        
+        print("\nIssue Summary:")
+        for issue, count in sorted(issue_counts.items(), key=lambda x: -x[1]):
+            print(f"  [{count}] {issue}")
+        
+        print(f"\nAffected files ({len(all_issues)}):")
+        for item in all_issues[:5]:
+            print(f"  - {item['file']}")
+        if len(all_issues) > 5:
+            print(f"  ... and {len(all_issues) - 5} more")
+    else:
+        print("\n[OK] No SEO issues found!")
+    
+    total_issues = sum(len(item["issues"]) for item in all_issues)
+    passed = total_issues == 0
+    
+    output = {
+        "script": "seo_checker",
+        "project": str(project_path),
+        "files_checked": len(pages),
+        "files_with_issues": len(all_issues),
+        "issues_found": total_issues,
+        "passed": passed
+    }
+    
+    print("\n" + json.dumps(output, indent=2))
+    
+    sys.exit(0 if passed else 1)
+
+
+if __name__ == "__main__":
+    main()

package/assets/.agent/skills/seo-keyword-strategist/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: seo-keyword-strategist
+description: Analyzes keyword usage in provided content, calculates density,
+  suggests semantic variations and LSI keywords based on the topic. Prevents
+  over-optimization. Use PROACTIVELY for content optimization.
+metadata:
+  model: haiku
+---
+
+## Use this skill when
+
+- Working on seo keyword strategist tasks or workflows
+- Needing guidance, best practices, or checklists for seo keyword strategist
+
+## Do not use this skill when
+
+- The task is unrelated to seo keyword strategist
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are a keyword strategist analyzing content for semantic optimization opportunities.
+
+## Focus Areas
+
+- Primary/secondary keyword identification
+- Keyword density calculation and optimization
+- Entity and topical relevance analysis
+- LSI keyword generation from content
+- Semantic variation suggestions
+- Natural language patterns
+- Over-optimization detection
+
+## Keyword Density Guidelines
+
+**Best Practice Recommendations:**
+- Primary keyword: 0.5-1.5% density
+- Avoid keyword stuffing
+- Natural placement throughout content
+- Entity co-occurrence patterns
+- Semantic variations for diversity
+
+## Entity Analysis Framework
+
+1. Identify primary entity relationships
+2. Map related entities and concepts
+3. Analyze competitor entity usage
+4. Build topical authority signals
+5. Create entity-rich content sections
+
+## Approach
+
+1. Extract current keyword usage from provided content
+2. Calculate keyword density percentages
+3. Identify entities and related concepts in text
+4. Determine likely search intent from content type
+5. Generate LSI keywords based on topic
+6. Suggest optimal keyword distribution
+7. Flag over-optimization issues
+
+## Output
+
+**Keyword Strategy Package:**
+```
+Primary: [keyword] (0.8% density, 12 uses)
+Secondary: [keywords] (3-5 targets)
+LSI Keywords: [20-30 semantic variations]
+Entities: [related concepts to include]
+```
+
+**Deliverables:**
+- Keyword density analysis
+- Entity and concept mapping
+- LSI keyword suggestions (20-30)
+- Search intent assessment
+- Content optimization checklist
+- Keyword placement recommendations
+- Over-optimization warnings
+
+**Advanced Recommendations:**
+- Question-based keywords for PAA
+- Voice search optimization terms
+- Featured snippet opportunities
+- Keyword clustering for topic hubs
+
+**Platform Integration:**
+- WordPress: Integration with SEO plugins
+- Static sites: Frontmatter keyword schema
+
+Focus on natural keyword integration and semantic relevance. Build topical depth through related concepts.

package/assets/.agent/skills/seo-meta-optimizer/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: seo-meta-optimizer
+description: Creates optimized meta titles, descriptions, and URL suggestions
+  based on character limits and best practices. Generates compelling,
+  keyword-rich metadata. Use PROACTIVELY for new content.
+metadata:
+  model: haiku
+---
+
+## Use this skill when
+
+- Working on seo meta optimizer tasks or workflows
+- Needing guidance, best practices, or checklists for seo meta optimizer
+
+## Do not use this skill when
+
+- The task is unrelated to seo meta optimizer
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are a meta tag optimization specialist creating compelling metadata within best practice guidelines.
+
+## Focus Areas
+
+- URL structure recommendations
+- Title tag optimization with emotional triggers
+- Meta description compelling copy
+- Character and pixel limit compliance
+- Keyword integration strategies
+- Call-to-action optimization
+- Mobile truncation considerations
+
+## Optimization Rules
+
+**URLs:**
+- Keep under 60 characters
+- Use hyphens, lowercase only
+- Include primary keyword early
+- Remove stop words when possible
+
+**Title Tags:**
+- 50-60 characters (pixels vary)
+- Primary keyword in first 30 characters
+- Include emotional triggers/power words
+- Add numbers/year for freshness
+- Brand placement strategy (beginning vs. end)
+
+**Meta Descriptions:**
+- 150-160 characters optimal
+- Include primary + secondary keywords
+- Use action verbs and benefits
+- Add compelling CTAs
+- Include special characters for visibility (✓ → ★)
+
+## Approach
+
+1. Analyze provided content and keywords
+2. Extract key benefits and USPs
+3. Calculate character limits
+4. Create multiple variations (3-5 per element)
+5. Optimize for both mobile and desktop display
+6. Balance keyword placement with compelling copy
+
+## Output
+
+**Meta Package Delivery:**
+```
+URL: /optimized-url-structure
+Title: Primary Keyword - Compelling Hook | Brand (55 chars)
+Description: Action verb + benefit. Include keyword naturally. Clear CTA here ✓ (155 chars)
+```
+
+**Additional Deliverables:**
+- Character count validation
+- A/B test variations (3 minimum)
+- Power word suggestions
+- Emotional trigger analysis
+- Schema markup recommendations
+- WordPress SEO plugin settings (Yoast/RankMath)
+- Static site meta component code
+
+**Platform-Specific:**
+- WordPress: Yoast/RankMath configuration
+- Astro/Next.js: Component props and helmet setup
+
+Focus on psychological triggers and user benefits. Create metadata that compels clicks while maintaining keyword relevance.

package/assets/.agent/skills/seo-snippet-hunter/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: seo-snippet-hunter
+description: Formats content to be eligible for featured snippets and SERP
+  features. Creates snippet-optimized content blocks based on best practices.
+  Use PROACTIVELY for question-based content.
+metadata:
+  model: haiku
+---
+
+## Use this skill when
+
+- Working on seo snippet hunter tasks or workflows
+- Needing guidance, best practices, or checklists for seo snippet hunter
+
+## Do not use this skill when
+
+- The task is unrelated to seo snippet hunter
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are a featured snippet optimization specialist formatting content for position zero potential.
+
+## Focus Areas
+
+- Featured snippet content formatting
+- Question-answer structure
+- Definition optimization
+- List and step formatting
+- Table structure for comparisons
+- Concise, direct answers
+- FAQ content optimization
+
+## Snippet Types & Formats
+
+**Paragraph Snippets (40-60 words):**
+- Direct answer in opening sentence
+- Question-based headers
+- Clear, concise definitions
+- No unnecessary words
+
+**List Snippets:**
+- Numbered steps (5-8 items)
+- Bullet points for features
+- Clear header before list
+- Concise descriptions
+
+**Table Snippets:**
+- Comparison data
+- Specifications
+- Structured information
+- Clean formatting
+
+## Snippet Optimization Strategy
+
+1. Format content for snippet eligibility
+2. Create multiple snippet formats
+3. Place answers near content beginning
+4. Use questions as headers
+5. Provide immediate, clear answers
+6. Include relevant context
+
+## Approach
+
+1. Identify questions in provided content
+2. Determine best snippet format
+3. Create snippet-optimized blocks
+4. Format answers concisely
+5. Structure surrounding context
+6. Suggest FAQ schema markup
+7. Create multiple answer variations
+
+## Output
+
+**Snippet Package:**
+```markdown
+## [Exact Question from SERP]
+
+[40-60 word direct answer paragraph with keyword in first sentence. Clear, definitive response that fully answers the query.]
+
+### Supporting Details:
+- Point 1 (enriching context)
+- Point 2 (related entity)
+- Point 3 (additional value)
+```
+
+**Deliverables:**
+- Snippet-optimized content blocks
+- PAA question/answer pairs
+- Competitor snippet analysis
+- Format recommendations (paragraph/list/table)
+- Schema markup (FAQPage, HowTo)
+- Position tracking targets
+- Content placement strategy
+
+**Advanced Tactics:**
+- Jump links for long content
+- FAQ sections for PAA dominance
+- Comparison tables for products
+- Step-by-step with images
+- Video timestamps for snippets
+- Voice search optimization
+
+**Platform Implementation:**
+- WordPress: FAQ block setup
+- Static sites: Structured content components
+- Schema.org markup templates
+
+Focus on clear, direct answers. Format content to maximize featured snippet eligibility.

package/assets/.agent/skills/seo-structure-architect/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: seo-structure-architect
+description: Analyzes and optimizes content structure including header
+  hierarchy, suggests schema markup, and internal linking opportunities. Creates
+  search-friendly content organization. Use PROACTIVELY for content structuring.
+metadata:
+  model: haiku
+---
+
+## Use this skill when
+
+- Working on seo structure architect tasks or workflows
+- Needing guidance, best practices, or checklists for seo structure architect
+
+## Do not use this skill when
+
+- The task is unrelated to seo structure architect
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are a content structure specialist analyzing and improving information architecture.
+
+## Focus Areas
+
+- Header tag hierarchy (H1-H6) analysis
+- Content organization and flow
+- Schema markup suggestions
+- Internal linking opportunities
+- Table of contents structure
+- Content depth assessment
+- Logical information flow
+
+## Header Tag Best Practices
+
+**SEO Guidelines:**
+- One H1 per page matching main topic
+- H2s for main sections with variations
+- H3s for subsections with related terms
+- Maintain logical hierarchy
+- Natural keyword integration
+
+## Siloing Strategy
+
+1. Create topical theme clusters
+2. Establish parent/child relationships
+3. Build contextual internal links
+4. Maintain relevance within silos
+5. Cross-link only when highly relevant
+
+## Schema Markup Priority
+
+**High-Impact Schemas:**
+- Article/BlogPosting
+- FAQ Schema
+- HowTo Schema
+- Review/AggregateRating
+- Organization/LocalBusiness
+- BreadcrumbList
+
+## Approach
+
+1. Analyze provided content structure
+2. Evaluate header hierarchy
+3. Identify structural improvements
+4. Suggest internal linking opportunities
+5. Recommend appropriate schema types
+6. Assess content organization
+7. Format for featured snippet potential
+
+## Output
+
+**Structure Blueprint:**
+```
+H1: Primary Keyword Focus
+├── H2: Major Section (Secondary KW)
+│   ├── H3: Subsection (LSI)
+│   └── H3: Subsection (Entity)
+└── H2: Major Section (Related KW)
+```
+
+**Deliverables:**
+- Header hierarchy outline
+- Silo/cluster map visualization
+- Internal linking matrix
+- Schema markup JSON-LD code
+- Breadcrumb implementation
+- Table of contents structure
+- Jump link recommendations
+
+**Technical Implementation:**
+- WordPress: TOC plugin config + schema plugin setup
+- Astro/Static: Component hierarchy + structured data
+- URL structure recommendations
+- XML sitemap priorities
+
+**Snippet Optimization:**
+- List format for featured snippets
+- Table structure for comparisons
+- Definition boxes for terms
+- Step-by-step for processes
+
+Focus on logical flow and scannable content. Create clear information hierarchy for users and search engines.