@namch/agent-assistant 1.0.0 → 1.0.1

package/skills/content-creator/scripts/seo_optimizer.py

@@ -0,0 +1,419 @@
+#!/usr/bin/env python3
+"""
+SEO Content Optimizer - Analyzes and optimizes content for SEO
+"""
+
+import re
+from typing import Dict, List, Set
+import json
+
+class SEOOptimizer:
+    def __init__(self):
+        # Common stop words to filter
+        self.stop_words = {
+            'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+            'of', 'with', 'by', 'from', 'as', 'is', 'was', 'are', 'were', 'be',
+            'been', 'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will',
+            'would', 'could', 'should', 'may', 'might', 'must', 'can', 'shall'
+        }
+        
+        # SEO best practices
+        self.best_practices = {
+            'title_length': (50, 60),
+            'meta_description_length': (150, 160),
+            'url_length': (50, 60),
+            'paragraph_length': (40, 150),
+            'heading_keyword_placement': True,
+            'keyword_density': (0.01, 0.03)  # 1-3%
+        }
+    
+    def analyze(self, content: str, target_keyword: str = None, 
+                secondary_keywords: List[str] = None) -> Dict:
+        """Analyze content for SEO optimization"""
+        
+        analysis = {
+            'content_length': len(content.split()),
+            'keyword_analysis': {},
+            'structure_analysis': self._analyze_structure(content),
+            'readability': self._analyze_readability(content),
+            'meta_suggestions': {},
+            'optimization_score': 0,
+            'recommendations': []
+        }
+        
+        # Keyword analysis
+        if target_keyword:
+            analysis['keyword_analysis'] = self._analyze_keywords(
+                content, target_keyword, secondary_keywords or []
+            )
+        
+        # Generate meta suggestions
+        analysis['meta_suggestions'] = self._generate_meta_suggestions(
+            content, target_keyword
+        )
+        
+        # Calculate optimization score
+        analysis['optimization_score'] = self._calculate_seo_score(analysis)
+        
+        # Generate recommendations
+        analysis['recommendations'] = self._generate_recommendations(analysis)
+        
+        return analysis
+    
+    def _analyze_keywords(self, content: str, primary: str, 
+                         secondary: List[str]) -> Dict:
+        """Analyze keyword usage and density"""
+        content_lower = content.lower()
+        word_count = len(content.split())
+        
+        results = {
+            'primary_keyword': {
+                'keyword': primary,
+                'count': content_lower.count(primary.lower()),
+                'density': 0,
+                'in_title': False,
+                'in_headings': False,
+                'in_first_paragraph': False
+            },
+            'secondary_keywords': [],
+            'lsi_keywords': []
+        }
+        
+        # Calculate primary keyword metrics
+        if word_count > 0:
+            results['primary_keyword']['density'] = (
+                results['primary_keyword']['count'] / word_count
+            )
+        
+        # Check keyword placement
+        first_para = content.split('\n\n')[0] if '\n\n' in content else content[:200]
+        results['primary_keyword']['in_first_paragraph'] = (
+            primary.lower() in first_para.lower()
+        )
+        
+        # Analyze secondary keywords
+        for keyword in secondary:
+            count = content_lower.count(keyword.lower())
+            results['secondary_keywords'].append({
+                'keyword': keyword,
+                'count': count,
+                'density': count / word_count if word_count > 0 else 0
+            })
+        
+        # Extract potential LSI keywords
+        results['lsi_keywords'] = self._extract_lsi_keywords(content, primary)
+        
+        return results
+    
+    def _analyze_structure(self, content: str) -> Dict:
+        """Analyze content structure for SEO"""
+        lines = content.split('\n')
+        
+        structure = {
+            'headings': {'h1': 0, 'h2': 0, 'h3': 0, 'total': 0},
+            'paragraphs': 0,
+            'lists': 0,
+            'images': 0,
+            'links': {'internal': 0, 'external': 0},
+            'avg_paragraph_length': 0
+        }
+        
+        paragraphs = []
+        current_para = []
+        
+        for line in lines:
+            # Count headings
+            if line.startswith('# '):
+                structure['headings']['h1'] += 1
+                structure['headings']['total'] += 1
+            elif line.startswith('## '):
+                structure['headings']['h2'] += 1
+                structure['headings']['total'] += 1
+            elif line.startswith('### '):
+                structure['headings']['h3'] += 1
+                structure['headings']['total'] += 1
+            
+            # Count lists
+            if line.strip().startswith(('- ', '* ', '1. ')):
+                structure['lists'] += 1
+            
+            # Count links
+            internal_links = len(re.findall(r'\[.*?\]\(/.*?\)', line))
+            external_links = len(re.findall(r'\[.*?\]\(https?://.*?\)', line))
+            structure['links']['internal'] += internal_links
+            structure['links']['external'] += external_links
+            
+            # Track paragraphs
+            if line.strip() and not line.startswith('#'):
+                current_para.append(line)
+            elif current_para:
+                paragraphs.append(' '.join(current_para))
+                current_para = []
+        
+        if current_para:
+            paragraphs.append(' '.join(current_para))
+        
+        structure['paragraphs'] = len(paragraphs)
+        
+        if paragraphs:
+            avg_length = sum(len(p.split()) for p in paragraphs) / len(paragraphs)
+            structure['avg_paragraph_length'] = round(avg_length, 1)
+        
+        return structure
+    
+    def _analyze_readability(self, content: str) -> Dict:
+        """Analyze content readability"""
+        sentences = re.split(r'[.!?]+', content)
+        words = content.split()
+        
+        if not sentences or not words:
+            return {'score': 0, 'level': 'Unknown'}
+        
+        avg_sentence_length = len(words) / len(sentences)
+        
+        # Simple readability scoring
+        if avg_sentence_length < 15:
+            level = 'Easy'
+            score = 90
+        elif avg_sentence_length < 20:
+            level = 'Moderate'
+            score = 70
+        elif avg_sentence_length < 25:
+            level = 'Difficult'
+            score = 50
+        else:
+            level = 'Very Difficult'
+            score = 30
+        
+        return {
+            'score': score,
+            'level': level,
+            'avg_sentence_length': round(avg_sentence_length, 1)
+        }
+    
+    def _extract_lsi_keywords(self, content: str, primary_keyword: str) -> List[str]:
+        """Extract potential LSI (semantically related) keywords"""
+        words = re.findall(r'\b[a-z]+\b', content.lower())
+        word_freq = {}
+        
+        # Count word frequencies
+        for word in words:
+            if word not in self.stop_words and len(word) > 3:
+                word_freq[word] = word_freq.get(word, 0) + 1
+        
+        # Sort by frequency and return top related terms
+        sorted_words = sorted(word_freq.items(), key=lambda x: x[1], reverse=True)
+        
+        # Filter out the primary keyword and return top 10
+        lsi_keywords = []
+        for word, count in sorted_words:
+            if word != primary_keyword.lower() and count > 1:
+                lsi_keywords.append(word)
+            if len(lsi_keywords) >= 10:
+                break
+        
+        return lsi_keywords
+    
+    def _generate_meta_suggestions(self, content: str, keyword: str = None) -> Dict:
+        """Generate SEO meta tag suggestions"""
+        # Extract first sentence for description base
+        sentences = re.split(r'[.!?]+', content)
+        first_sentence = sentences[0] if sentences else content[:160]
+        
+        suggestions = {
+            'title': '',
+            'meta_description': '',
+            'url_slug': '',
+            'og_title': '',
+            'og_description': ''
+        }
+        
+        if keyword:
+            # Title suggestion
+            suggestions['title'] = f"{keyword.title()} - Complete Guide"
+            if len(suggestions['title']) > 60:
+                suggestions['title'] = keyword.title()[:57] + "..."
+            
+            # Meta description
+            desc_base = f"Learn everything about {keyword}. {first_sentence}"
+            if len(desc_base) > 160:
+                desc_base = desc_base[:157] + "..."
+            suggestions['meta_description'] = desc_base
+            
+            # URL slug
+            suggestions['url_slug'] = re.sub(r'[^a-z0-9-]+', '-', 
+                                            keyword.lower()).strip('-')
+            
+            # Open Graph tags
+            suggestions['og_title'] = suggestions['title']
+            suggestions['og_description'] = suggestions['meta_description']
+        
+        return suggestions
+    
+    def _calculate_seo_score(self, analysis: Dict) -> int:
+        """Calculate overall SEO optimization score"""
+        score = 0
+        max_score = 100
+        
+        # Content length scoring (20 points)
+        if 300 <= analysis['content_length'] <= 2500:
+            score += 20
+        elif 200 <= analysis['content_length'] < 300:
+            score += 10
+        elif analysis['content_length'] > 2500:
+            score += 15
+        
+        # Keyword optimization (30 points)
+        if analysis['keyword_analysis']:
+            kw_data = analysis['keyword_analysis']['primary_keyword']
+            
+            # Density scoring
+            if 0.01 <= kw_data['density'] <= 0.03:
+                score += 15
+            elif 0.005 <= kw_data['density'] < 0.01:
+                score += 8
+            
+            # Placement scoring
+            if kw_data['in_first_paragraph']:
+                score += 10
+            if kw_data.get('in_headings'):
+                score += 5
+        
+        # Structure scoring (25 points)
+        struct = analysis['structure_analysis']
+        if struct['headings']['total'] > 0:
+            score += 10
+        if struct['paragraphs'] >= 3:
+            score += 10
+        if struct['links']['internal'] > 0 or struct['links']['external'] > 0:
+            score += 5
+        
+        # Readability scoring (25 points)
+        readability_score = analysis['readability']['score']
+        score += int(readability_score * 0.25)
+        
+        return min(score, max_score)
+    
+    def _generate_recommendations(self, analysis: Dict) -> List[str]:
+        """Generate SEO improvement recommendations"""
+        recommendations = []
+        
+        # Content length recommendations
+        if analysis['content_length'] < 300:
+            recommendations.append(
+                f"Increase content length to at least 300 words (currently {analysis['content_length']})"
+            )
+        elif analysis['content_length'] > 3000:
+            recommendations.append(
+                "Consider breaking long content into multiple pages or adding a table of contents"
+            )
+        
+        # Keyword recommendations
+        if analysis['keyword_analysis']:
+            kw_data = analysis['keyword_analysis']['primary_keyword']
+            
+            if kw_data['density'] < 0.01:
+                recommendations.append(
+                    f"Increase keyword density for '{kw_data['keyword']}' (currently {kw_data['density']:.2%})"
+                )
+            elif kw_data['density'] > 0.03:
+                recommendations.append(
+                    f"Reduce keyword density to avoid over-optimization (currently {kw_data['density']:.2%})"
+                )
+            
+            if not kw_data['in_first_paragraph']:
+                recommendations.append(
+                    "Include primary keyword in the first paragraph"
+                )
+        
+        # Structure recommendations
+        struct = analysis['structure_analysis']
+        if struct['headings']['total'] == 0:
+            recommendations.append("Add headings (H1, H2, H3) to improve content structure")
+        if struct['links']['internal'] == 0:
+            recommendations.append("Add internal links to related content")
+        if struct['avg_paragraph_length'] > 150:
+            recommendations.append("Break up long paragraphs for better readability")
+        
+        # Readability recommendations
+        if analysis['readability']['avg_sentence_length'] > 20:
+            recommendations.append("Simplify sentences for better readability")
+        
+        return recommendations
+
+def optimize_content(content: str, keyword: str = None, 
+                     secondary_keywords: List[str] = None) -> str:
+    """Main function to optimize content"""
+    optimizer = SEOOptimizer()
+    
+    # Parse secondary keywords from comma-separated string if provided
+    if secondary_keywords and isinstance(secondary_keywords, str):
+        secondary_keywords = [kw.strip() for kw in secondary_keywords.split(',')]
+    
+    results = optimizer.analyze(content, keyword, secondary_keywords)
+    
+    # Format output
+    output = [
+        "=== SEO Content Analysis ===",
+        f"Overall SEO Score: {results['optimization_score']}/100",
+        f"Content Length: {results['content_length']} words",
+        f"",
+        "Content Structure:",
+        f"  Headings: {results['structure_analysis']['headings']['total']}",
+        f"  Paragraphs: {results['structure_analysis']['paragraphs']}",
+        f"  Avg Paragraph Length: {results['structure_analysis']['avg_paragraph_length']} words",
+        f"  Internal Links: {results['structure_analysis']['links']['internal']}",
+        f"  External Links: {results['structure_analysis']['links']['external']}",
+        f"",
+        f"Readability: {results['readability']['level']} (Score: {results['readability']['score']})",
+        f""
+    ]
+    
+    if results['keyword_analysis']:
+        kw = results['keyword_analysis']['primary_keyword']
+        output.extend([
+            "Keyword Analysis:",
+            f"  Primary Keyword: {kw['keyword']}",
+            f"  Count: {kw['count']}",
+            f"  Density: {kw['density']:.2%}",
+            f"  In First Paragraph: {'Yes' if kw['in_first_paragraph'] else 'No'}",
+            f""
+        ])
+        
+        if results['keyword_analysis']['lsi_keywords']:
+            output.append("  Related Keywords Found:")
+            for lsi in results['keyword_analysis']['lsi_keywords'][:5]:
+                output.append(f"    • {lsi}")
+            output.append("")
+    
+    if results['meta_suggestions']:
+        output.extend([
+            "Meta Tag Suggestions:",
+            f"  Title: {results['meta_suggestions']['title']}",
+            f"  Description: {results['meta_suggestions']['meta_description']}",
+            f"  URL Slug: {results['meta_suggestions']['url_slug']}",
+            f""
+        ])
+    
+    output.extend([
+        "Recommendations:",
+    ])
+    
+    for rec in results['recommendations']:
+        output.append(f"  • {rec}")
+    
+    return '\n'.join(output)
+
+if __name__ == "__main__":
+    import sys
+    
+    if len(sys.argv) > 1:
+        with open(sys.argv[1], 'r') as f:
+            content = f.read()
+        
+        keyword = sys.argv[2] if len(sys.argv) > 2 else None
+        secondary = sys.argv[3] if len(sys.argv) > 3 else None
+        
+        print(optimize_content(content, keyword, secondary))
+    else:
+        print("Usage: python seo_optimizer.py <file> [primary_keyword] [secondary_keywords]")

package/skills/context-window-management/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: context-window-management
+description: "Strategies for managing LLM context windows including summarization, trimming, routing, and avoiding context rot Use when: context window, token limit, context management, context engineering, long context."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# Context Window Management
+
+You're a context engineering specialist who has optimized LLM applications handling
+millions of conversations. You've seen systems hit token limits, suffer context rot,
+and lose critical information mid-dialogue.
+
+You understand that context is a finite resource with diminishing returns. More tokens
+doesn't mean better results—the art is in curating the right information. You know
+the serial position effect, the lost-in-the-middle problem, and when to summarize
+versus when to retrieve.
+
+Your cor
+
+## Capabilities
+
+- context-engineering
+- context-summarization
+- context-trimming
+- context-routing
+- token-counting
+- context-prioritization
+
+## Patterns
+
+### Tiered Context Strategy
+
+Different strategies based on context size
+
+### Serial Position Optimization
+
+Place important content at start and end
+
+### Intelligent Summarization
+
+Summarize by importance, not just recency
+
+## Anti-Patterns
+
+### ❌ Naive Truncation
+
+### ❌ Ignoring Token Costs
+
+### ❌ One-Size-Fits-All
+
+## Related Skills
+
+Works well with: `rag-implementation`, `conversation-memory`, `prompt-caching`, `llm-npc-dialogue`

package/skills/conversation-memory/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: conversation-memory
+description: "Persistent memory systems for LLM conversations including short-term, long-term, and entity-based memory Use when: conversation memory, remember, memory persistence, long-term memory, chat history."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# Conversation Memory
+
+You're a memory systems specialist who has built AI assistants that remember
+users across months of interactions. You've implemented systems that know when
+to remember, when to forget, and how to surface relevant memories.
+
+You understand that memory is not just storage—it's about retrieval, relevance,
+and context. You've seen systems that remember everything (and overwhelm context)
+and systems that forget too much (frustrating users).
+
+Your core principles:
+1. Memory types differ—short-term, lo
+
+## Capabilities
+
+- short-term-memory
+- long-term-memory
+- entity-memory
+- memory-persistence
+- memory-retrieval
+- memory-consolidation
+
+## Patterns
+
+### Tiered Memory System
+
+Different memory tiers for different purposes
+
+### Entity Memory
+
+Store and update facts about entities
+
+### Memory-Aware Prompting
+
+Include relevant memories in prompts
+
+## Anti-Patterns
+
+### ❌ Remember Everything
+
+### ❌ No Memory Retrieval
+
+### ❌ Single Memory Store
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Memory store grows unbounded, system slows | high | // Implement memory lifecycle management |
+| Retrieved memories not relevant to current query | high | // Intelligent memory retrieval |
+| Memories from one user accessible to another | critical | // Strict user isolation in memory |
+
+## Related Skills
+
+Works well with: `context-window-management`, `rag-implementation`, `prompt-caching`, `llm-npc-dialogue`