@neyugn/agent-kits 0.1.0

package/kits/coder/skills/seo-patterns/scripts/seo_checker.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+SEO Checker - SEO and GEO audit for AGT-Kit
+============================================
+
+Checks pages for SEO best practices and AI citation readiness (GEO).
+
+Usage:
+    python3 .agent/skills/seo-patterns/scripts/seo_checker.py <project_path>
+
+Checks:
+    - JSON-LD structured data
+    - Meta tags (title, description, og:*)
+    - Heading structure (H1, H2)
+    - E-E-A-T signals (author, dates)
+    - FAQ sections (AI-citable)
+"""
+
+import sys
+import re
+import json
+from pathlib import Path
+from datetime import datetime
+from typing import Dict, List, Any
+
+# Fix console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+    pass
+
+SKIP_DIRS = {'node_modules', '.git', 'dist', 'build', '__pycache__', '.next', 'venv', 'test', 'tests'}
+
+
+def find_pages(project_path: Path) -> List[Path]:
+    """Find public-facing web pages."""
+    patterns = ['**/*.html', '**/pages/**/*.tsx', '**/app/**/*.tsx', '**/app/**/*.jsx']
+    
+    files = []
+    for pattern in patterns:
+        for f in project_path.glob(pattern):
+            if not any(skip in f.parts for skip in SKIP_DIRS):
+                # Filter to likely page files
+                name = f.stem.lower()
+                if any(x in name for x in ['page', 'index', 'home', 'about', 'blog', 'post', 'product']):
+                    files.append(f)
+                elif 'pages' in f.parts or 'app' in f.parts:
+                    files.append(f)
+    
+    return files[:20]  # Limit
+
+
+def check_page(file_path: Path) -> Dict[str, Any]:
+    """Check a single page for SEO elements."""
+    try:
+        content = file_path.read_text(encoding='utf-8', errors='ignore')
+    except:
+        return {'file': file_path.name, 'passed': [], 'issues': ['Read error'], 'score': 0}
+    
+    passed = []
+    issues = []
+    
+    # 1. JSON-LD Structured Data
+    if 'application/ld+json' in content:
+        passed.append("JSON-LD structured data")
+        if '"@type"' in content:
+            if 'Article' in content:
+                passed.append("Article schema")
+            if 'FAQPage' in content:
+                passed.append("FAQ schema (highly citable)")
+    else:
+        issues.append("No JSON-LD structured data")
+    
+    # 2. Heading Structure
+    h1_count = len(re.findall(r'<h1[^>]*>', content, re.I))
+    h2_count = len(re.findall(r'<h2[^>]*>', content, re.I))
+    
+    if h1_count == 1:
+        passed.append("Single H1 heading")
+    elif h1_count == 0:
+        issues.append("No H1 heading")
+    else:
+        issues.append(f"Multiple H1 headings ({h1_count})")
+    
+    if h2_count >= 2:
+        passed.append(f"{h2_count} H2 subheadings")
+    else:
+        issues.append("Add more H2 subheadings")
+    
+    # 3. Meta Tags
+    if '<title>' in content or 'title=' in content:
+        passed.append("Title tag found")
+    else:
+        issues.append("Missing title tag")
+    
+    if 'meta' in content.lower() and 'description' in content.lower():
+        passed.append("Meta description")
+    else:
+        issues.append("Missing meta description")
+    
+    # 4. Author Attribution (E-E-A-T)
+    author_patterns = ['author', 'byline', 'written-by', 'rel="author"']
+    if any(p in content.lower() for p in author_patterns):
+        passed.append("Author attribution")
+    else:
+        issues.append("No author info (E-E-A-T)")
+    
+    # 5. Publication Date
+    date_patterns = ['datePublished', 'dateModified', 'datetime=', 'pubdate']
+    if any(re.search(p, content, re.I) for p in date_patterns):
+        passed.append("Publication date")
+    else:
+        issues.append("No publication date")
+    
+    # 6. Open Graph
+    if 'og:' in content or 'property="og:' in content:
+        passed.append("Open Graph tags")
+    
+    # 7. Lists and Tables (structured content)
+    list_count = len(re.findall(r'<(ul|ol)[^>]*>', content, re.I))
+    table_count = len(re.findall(r'<table[^>]*>', content, re.I))
+    
+    if list_count >= 2:
+        passed.append(f"{list_count} lists")
+    if table_count >= 1:
+        passed.append(f"{table_count} table(s)")
+    
+    # Calculate score
+    total = len(passed) + len(issues)
+    score = (len(passed) / total * 100) if total > 0 else 0
+    
+    return {
+        'file': file_path.name,
+        'passed': passed,
+        'issues': issues,
+        'score': round(score)
+    }
+
+
+def main():
+    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    
+    print(f"\n{'='*60}")
+    print(f"[AGT-KIT SEO CHECKER] SEO & GEO Audit")
+    print(f"{'='*60}")
+    print(f"Project: {project_path}")
+    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("-"*60)
+    
+    pages = find_pages(project_path)
+    
+    if not pages:
+        print("\nNo public pages found.")
+        print("Looking for: HTML files, pages/, app/ directories")
+        output = {
+            "script": "seo_checker",
+            "skill": "seo-patterns",
+            "project": str(project_path),
+            "pages_checked": 0,
+            "passed": True,
+            "message": "No pages found"
+        }
+        print(json.dumps(output, indent=2))
+        sys.exit(0)
+    
+    print(f"Found {len(pages)} pages to analyze\n")
+    
+    results = []
+    for page in pages:
+        result = check_page(page)
+        results.append(result)
+        
+        # Print summary
+        status = "✅" if result['score'] >= 60 else "⚠️"
+        print(f"{status} {result['file']}: {result['score']}%")
+        
+        if result['score'] < 60:
+            for issue in result['issues'][:2]:
+                print(f"   - {issue}")
+    
+    # Average score
+    avg_score = sum(r['score'] for r in results) / len(results) if results else 0
+    
+    print("\n" + "="*60)
+    print(f"AVERAGE SEO SCORE: {avg_score:.0f}%")
+    print("="*60)
+    
+    if avg_score >= 80:
+        print("✅ Excellent - Well optimized for search & AI")
+    elif avg_score >= 60:
+        print("✅ Good - Some improvements recommended")
+    elif avg_score >= 40:
+        print("⚠️  Needs work - Add structured elements")
+    else:
+        print("❌ Poor - SEO optimization needed")
+    
+    output = {
+        "script": "seo_checker",
+        "skill": "seo-patterns",
+        "project": str(project_path),
+        "pages_checked": len(results),
+        "average_score": round(avg_score),
+        "passed": avg_score >= 60
+    }
+    
+    print("\n" + json.dumps(output, indent=2))
+    sys.exit(0 if avg_score >= 60 else 1)
+
+
+if __name__ == "__main__":
+    main()

package/kits/coder/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,478 @@
+---
+name: systematic-debugging
+description: 4-phase systematic debugging methodology with root cause analysis and evidence-based verification. Use when debugging complex issues, investigating production bugs, or when trial-and-error is failing.
+allowed-tools: Read, Write, Edit, Bash, Grep
+---
+
+# Systematic Debugging - Scientific Defect Resolution
+
+> **Philosophy:** Debugging is detective work. Gather evidence, form hypotheses, test systematically.
+
+---
+
+## 🎯 Core Principle: Scientific Method for Bugs
+
+```
+❌ WRONG: Change random things → Hope it works → Repeat
+✅ CORRECT: Observe → Hypothesize → Predict → Test → Verify
+```
+
+**The Scientific Debugging Approach:**
+
+- Every change must be driven by a testable hypothesis
+- One variable at a time
+- Document evidence and outcomes
+- Root cause, not symptom treatment
+
+---
+
+## 🔄 The 4-Phase Debugging Workflow
+
+### Phase Overview
+
+```
+PHASE 1: REPRODUCE     → Reliably trigger the bug
+    ↓
+PHASE 2: DIAGNOSE      → Gather evidence, form hypotheses
+    ↓
+PHASE 3: FIX           → Apply targeted fix
+    ↓
+PHASE 4: VERIFY        → Confirm fix, prevent regression
+```
+
+---
+
+## 📍 Phase 1: Reproduce
+
+### Goal: Create a Minimal, Reliable Reproduction
+
+**Without reliable reproduction, debugging is guessing.**
+
+### Reproduction Checklist
+
+```markdown
+- [ ] Can trigger bug consistently (>90% success rate)
+- [ ] Identified minimum steps to reproduce
+- [ ] Know environment conditions (OS, browser, versions)
+- [ ] Have isolated from unrelated factors
+- [ ] Created automated test case if possible
+```
+
+### Information Gathering Template
+
+```markdown
+## Bug Reproduction Details
+
+**Reported Behavior:** [What user/test observed]
+
+**Expected Behavior:** [What should happen]
+
+**Environment:**
+
+- OS: [e.g., macOS 14.2]
+- Runtime: [e.g., Node 20.10.0]
+- Dependencies: [Key versions]
+
+**Reproduction Steps:**
+
+1. [Step 1]
+2. [Step 2]
+3. [Observe: Expected X, Got Y]
+
+**Frequency:** [Always / Intermittent / Random]
+
+**First Occurred:** [When / after what change]
+```
+
+### Handling Intermittent Bugs
+
+| Pattern              | Investigation Approach                  |
+| -------------------- | --------------------------------------- |
+| Race condition       | Add timing logs, check for async issues |
+| Memory-related       | Check for uninitialized variables       |
+| State-dependent      | Log state at failure points             |
+| Environment-specific | Compare configurations                  |
+| Load-dependent       | Test under high load/concurrency        |
+
+### If Bug Won't Reproduce
+
+1. Check if bug is already fixed
+2. Review recent code changes (git log)
+3. Compare environments in detail
+4. Add defensive logging for next occurrence
+5. Set up alerts to capture live failure
+
+---
+
+## 🔬 Phase 2: Diagnose
+
+### Goal: Identify Root Cause Through Evidence
+
+### The Hypothesis Cycle
+
+```
+    ┌────────────────────────────────┐
+    │         OBSERVE                │
+    │   (Gather evidence/data)       │
+    └──────────────┬─────────────────┘
+                   ↓
+    ┌────────────────────────────────┐
+    │       HYPOTHESIZE              │
+    │   (What could cause this?)     │
+    └──────────────┬─────────────────┘
+                   ↓
+    ┌────────────────────────────────┐
+    │         PREDICT                │
+    │   (If hypothesis true, then..) │
+    └──────────────┬─────────────────┘
+                   ↓
+    ┌────────────────────────────────┐
+    │          TEST                  │
+    │   (Run experiment)             │
+    └──────────────┬─────────────────┘
+                   ↓
+             ┌─────┴─────┐
+        Confirmed?   Refuted?
+             ↓           ↓
+         Refine      New Hypothesis
+```
+
+### Evidence Gathering Techniques
+
+| Technique                | When to Use                        | How                             |
+| ------------------------ | ---------------------------------- | ------------------------------- |
+| **Strategic Logging**    | Understanding execution flow       | Add logs at decision points     |
+| **Debugger Breakpoints** | Inspecting state at specific point | Set conditional breakpoints     |
+| **Binary Search**        | Large codebase, unclear location   | Comment out half, narrow down   |
+| **Stack Trace Analysis** | Exception/crash occurred           | Read trace bottom-up            |
+| **Git Bisect**           | Bug appeared in recent commits     | Automate finding bad commit     |
+| **Diff Analysis**        | Recently working code broke        | Compare working vs broken code  |
+| **Rubber Duck**          | Logic seems correct but isn't      | Explain code line by line aloud |
+
+### Hypothesis Documentation
+
+```markdown
+## Hypothesis #1: [Title]
+
+**Statement:** [What you think is wrong]
+
+**Evidence For:**
+
+- [Supporting observation 1]
+- [Supporting observation 2]
+
+**Evidence Against:**
+
+- [Contradicting observation if any]
+
+**Test Plan:**
+
+- [How to confirm or refute this]
+
+**Prediction:**
+
+- If true: [Expected observation]
+- If false: [What we'd see instead]
+
+**Result:** ✅ Confirmed / ❌ Refuted / 🔄 Needs more data
+```
+
+### Root Cause Categories
+
+| Category          | Examples                              | Investigation Focus           |
+| ----------------- | ------------------------------------- | ----------------------------- |
+| **Logic Error**   | Wrong condition, off-by-one           | Step through logic carefully  |
+| **State Problem** | Race condition, stale cache           | Track state changes over time |
+| **Data Issue**    | Invalid input, null reference         | Inspect data at boundaries    |
+| **Integration**   | API contract broken, version mismatch | Check integration points      |
+| **Resource**      | Leak, exhaustion, timeout             | Monitor resource usage        |
+| **Configuration** | Wrong env var, missing setting        | Compare environments          |
+
+### 5 Whys Analysis
+
+```markdown
+## 5 Whys: [Bug Title]
+
+1. **Why** did [observed failure occur]?
+   → Because [immediate cause]
+
+2. **Why** did [immediate cause] happen?
+   → Because [deeper cause]
+
+3. **Why** did [deeper cause] happen?
+   → Because [even deeper cause]
+
+4. **Why** did [even deeper cause] happen?
+   → Because [near root cause]
+
+5. **Why** did [near root cause] happen?
+   → Because [ROOT CAUSE]
+
+**Root Cause:** [Final answer]
+```
+
+---
+
+## 🔧 Phase 3: Fix
+
+### Goal: Apply Targeted, Minimal Fix
+
+### Pre-Fix Checklist
+
+```markdown
+- [ ] Root cause is identified and documented
+- [ ] Hypothesis has been tested and confirmed
+- [ ] Understand the full impact of the fix
+- [ ] Fix addresses root cause, not just symptom
+- [ ] Have a test that will prove the fix works
+```
+
+### Fix Quality Criteria
+
+| Criterion      | Description                             |
+| -------------- | --------------------------------------- |
+| **Targeted**   | Changes only what's necessary           |
+| **Root-Cause** | Fixes the cause, not the symptom        |
+| **Safe**       | Doesn't introduce new bugs              |
+| **Readable**   | Future developers can understand why    |
+| **Testable**   | Can verify it works with automated test |
+
+### Fix Documentation
+
+```markdown
+## Fix Applied
+
+**Root Cause:** [What was actually wrong]
+
+**Solution:** [What change was made]
+
+**Files Modified:**
+
+- `path/to/file.ts` - [Description of change]
+
+**Why This Fix:**
+
+- [Rationale for this approach]
+
+**Alternative Considered:**
+
+- [Other option] - Not chosen because [reason]
+
+**Risk Assessment:**
+
+- [Low/Medium/High] - [Justification]
+```
+
+### Common Fix Patterns
+
+| Bug Type         | Fix Pattern                             |
+| ---------------- | --------------------------------------- |
+| Null reference   | Add null check + handle gracefully      |
+| Race condition   | Add synchronization/locking             |
+| Off-by-one       | Adjust boundary condition               |
+| State corruption | Reset or validate state at entry points |
+| Memory leak      | Ensure resources are cleaned up         |
+| Timeout          | Adjust timeout + add retry logic        |
+
+---
+
+## ✅ Phase 4: Verify
+
+### Goal: Confirm Fix Works, Prevent Regression
+
+### Verification Checklist
+
+```markdown
+## Verification Steps
+
+### Immediate Verification
+
+- [ ] Original reproduction steps no longer trigger bug
+- [ ] Automated test for this bug passes
+- [ ] Related functionality still works
+- [ ] No new warnings/errors introduced
+
+### Regression Prevention
+
+- [ ] Unit test added for the specific case
+- [ ] Edge cases tested
+- [ ] Integration tests pass
+- [ ] Code reviewed by another person
+
+### Documentation
+
+- [ ] Root cause documented (for future learning)
+- [ ] Commit message explains the fix
+- [ ] Ticket/issue updated with resolution
+```
+
+### Test Case Template
+
+```markdown
+## Regression Test: [Bug ID/Title]
+
+**Purpose:** Prevent recurrence of [bug description]
+
+**Test:**
+```
+
+// Test code or test case description
+expect(buggyFunction(problematicInput)).toBe(correctOutput);
+
+```
+
+**Covers:**
+- [x] The exact failure case
+- [x] Similar edge cases: [list them]
+```
+
+### Rollback Strategy
+
+```markdown
+## Rollback Plan
+
+**If fix causes issues:**
+
+1. Revert commit: `git revert [commit-hash]`
+2. Deploy previous version
+3. Notify stakeholders
+4. Document what went wrong with fix
+
+**Monitoring:**
+
+- [What metrics to watch]
+- [Alert thresholds]
+- [Duration of elevated monitoring]
+```
+
+---
+
+## 🛠️ Debugging Tools & Techniques
+
+### Tool Selection Guide
+
+| Situation              | Tool/Technique | Command/Usage                      |
+| ---------------------- | -------------- | ---------------------------------- |
+| Find when bug appeared | Git Bisect     | `git bisect start; git bisect bad` |
+| Trace execution path   | Debugger       | Set breakpoints, step through      |
+| Find pattern in code   | Grep/Ripgrep   | `rg "pattern" --type ts`           |
+| Profile performance    | Profiler       | Chrome DevTools, `node --prof`     |
+| Monitor network        | Network tab    | Check request/response             |
+| Find recent changes    | Git log/blame  | `git log -p --since="2 days ago"`  |
+
+### Strategic Logging
+
+```typescript
+// Good: Context-rich, actionable logs
+logger.debug("Processing order", {
+  orderId,
+  userId,
+  itemCount: items.length,
+  totalAmount,
+});
+
+// Bad: Vague, unhelpful
+console.log("here"); // ❌
+console.log(data); // ❌ No context
+```
+
+### Binary Search Debugging
+
+```
+Step 1: Identify a working point and broken point
+Step 2: Test the midpoint
+Step 3: If midpoint works → bug is after
+        If midpoint broken → bug is before
+Step 4: Repeat until bug location is isolated
+```
+
+---
+
+## 🚨 Anti-Patterns
+
+| ❌ Don't                   | ✅ Do                                       |
+| -------------------------- | ------------------------------------------- |
+| Change random things       | Test one hypothesis at a time               |
+| Fix the symptom            | Find and fix root cause                     |
+| Skip reproduction          | Establish reliable repro first              |
+| Hope it's fixed            | Verify with tests                           |
+| Fix and forget             | Document and add regression test            |
+| Debug in production        | Reproduce in safe environment when possible |
+| Remove code until it works | Understand why code was there               |
+| Assume the obvious cause   | Test each hypothesis with evidence          |
+
+---
+
+## 📋 Debugging Session Template
+
+```markdown
+# Debug Session: [Issue Title]
+
+**Date:** YYYY-MM-DD
+**Status:** 🔄 In Progress | ✅ Resolved | ❌ Blocked
+
+---
+
+## Symptoms
+
+[What's happening]
+
+## Reproduction
+
+[Steps to reproduce reliably]
+
+---
+
+## Diagnosis
+
+### Hypothesis 1: [Title]
+
+- **Test:** [How to test]
+- **Result:** ❌ Refuted / ✅ Confirmed
+
+### Hypothesis 2: [Title]
+
+- **Test:** [How to test]
+- **Result:** ❌ Refuted / ✅ Confirmed
+
+---
+
+## Root Cause
+
+[What is actually wrong and why it causes the symptom]
+
+---
+
+## Fix
+
+[What was changed]
+
+---
+
+## Verification
+
+- [ ] Reproduction no longer triggers bug
+- [ ] Regression test added
+- [ ] Related functionality verified
+
+---
+
+## Lessons Learned
+
+[What can prevent similar bugs in the future]
+```
+
+---
+
+## 🔗 Related Skills
+
+| Need                     | Skill              |
+| ------------------------ | ------------------ |
+| Understanding before fix | `brainstorming`    |
+| Planning complex fixes   | `plan-writing`     |
+| Writing regression tests | `testing-patterns` |
+| Clean fix code           | `clean-code`       |
+
+---
+
+> **Remember:** The most expensive bugs are those that keep coming back. Invest in understanding the root cause, and your fix will stick.

package/kits/coder/skills/systematic-debugging/assets/.gitkeep

@@ -0,0 +1 @@
+# Assets directory - add templates, images, etc.

package/kits/coder/skills/systematic-debugging/references/deep-dive.md

@@ -0,0 +1,21 @@
+# Reference Documentation for Systematic Debugging
+
+[TODO: Add detailed reference content here]
+
+## Overview
+
+[Detailed explanation of concepts]
+
+## Deep Dive Topics
+
+### Topic 1
+
+[Content]
+
+### Topic 2
+
+[Content]
+
+## Examples
+
+[Real-world examples]