codehava-agent-kit 1.0.0 → 2.0.0

package/templates/.agent/skills/seo-plan/assets/publisher.md

@@ -0,0 +1,153 @@
+<!-- Updated: 2026-02-07 -->
+# Publisher/Media SEO Strategy Template
+
+## Industry Characteristics
+
+- High content volume
+- Time-sensitive content (news)
+- Ad revenue dependent on traffic
+- Authority and trust critical
+- Competing with social platforms
+- AI Overviews impact on traffic
+
+## Recommended Site Architecture
+
+```
+/
+├── Home
+├── /news (or /latest)
+├── /topics
+│   ├── /topic-1
+│   ├── /topic-2
+│   └── ...
+├── /authors
+│   ├── /author-1
+│   └── ...
+├── /opinion
+├── /reviews
+├── /guides
+├── /videos
+├── /podcasts
+├── /newsletter
+├── /about
+│   ├── /editorial-policy
+│   ├── /corrections
+│   └── /contact
+└── /[year]/[month]/[slug] (article URLs)
+```
+
+## Schema Recommendations
+
+| Page Type | Schema Types |
+|-----------|-------------|
+| Article | NewsArticle or Article, Person (author), Organization (publisher) |
+| Author Page | Person, ProfilePage |
+| Topic Page | CollectionPage, ItemList |
+| Homepage | WebSite, Organization |
+| Video | VideoObject |
+| Podcast | PodcastEpisode, PodcastSeries |
+
+### NewsArticle Schema Example
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "NewsArticle",
+  "headline": "Article Headline",
+  "datePublished": "2026-02-07T10:00:00Z",
+  "dateModified": "2026-02-07T14:30:00Z",
+  "author": {
+    "@type": "Person",
+    "name": "Author Name",
+    "url": "https://example.com/authors/author-name"
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "Publication Name",
+    "logo": {
+      "@type": "ImageObject",
+      "url": "https://example.com/logo.png"
+    }
+  },
+  "image": ["https://example.com/article-image.jpg"],
+  "mainEntityOfPage": {
+    "@type": "WebPage",
+    "@id": "https://example.com/article-url"
+  }
+}
+```
+
+## E-E-A-T Requirements
+
+Publishers face highest E-E-A-T scrutiny.
+
+### Author Pages Must Include
+- Full name and photo
+- Bio and credentials
+- Areas of expertise
+- Contact information
+- Social profiles (sameAs)
+- Previous articles by this author
+
+### Editorial Standards
+- Clear correction policy
+- Transparent editorial process
+- Fact-checking procedures
+- Conflict of interest disclosures
+
+## Content Priorities
+
+### High Priority
+1. Breaking news (speed matters)
+2. Evergreen guides on core topics
+3. Author pages with credentials
+4. Topic hubs/pillar pages
+
+### Medium Priority
+1. Opinion/analysis pieces
+2. Video content
+3. Interactive content
+4. Newsletter landing pages
+
+### GEO Considerations
+- Clear, quotable facts in articles
+- Tables for data-heavy content
+- Expert quotes with attribution
+- Update dates prominently displayed
+- Structured headings (H2/H3)
+- First-party data and original research are highly cited by AI systems
+- Ensure author entities are clearly defined with Person schema + sameAs links
+- Monitor AI citation frequency across Google AI Overviews, AI Mode, ChatGPT, Perplexity
+- Treat AI citation as a standalone KPI alongside organic traffic
+
+### Publisher SEO Updates (2025-2026)
+
+- **Google News automatic inclusion:** Google News no longer accepts manual applications (since March 2025). Inclusion is fully automatic based on Google's content quality criteria. Focus on Google News sitemap markup and consistent, high-quality publishing cadence.
+- **KPI shift:** Traffic-based KPIs (sessions, pageviews) are declining in relevance as AI Overviews reduce click-through rates. Leading publishers are shifting to: subscriber conversions, time on page, scroll depth, newsletter signups, AI citation frequency, and revenue per visitor.
+- **Site reputation abuse risk:** Publishers hosting third-party content (coupons, product reviews, affiliate content) under their domain are at high risk. Google penalized Forbes, WSJ, Time, and CNN for this in late 2024. If hosting third-party content, ensure strong editorial oversight and clear first-party involvement.
+
+## Technical Considerations
+
+### Core Web Vitals
+- Ad placement affects CLS
+- Lazy load ads and images below fold
+- Optimize hero images for LCP
+- Minimize render-blocking resources
+
+### AMP (if used)
+- Consider dropping AMP (no longer required for Top Stories)
+- Ensure canonical setup is correct
+- Monitor performance vs non-AMP
+
+### Pagination
+- Proper pagination for multi-page articles
+- Or infinite scroll with proper indexing
+- Canonical to page 1 or full article
+
+## Key Metrics to Track
+
+- Page views from organic
+- Time on page
+- Pages per session
+- Newsletter signups from organic
+- Google News/Discover traffic
+- AI Overview appearances

package/templates/.agent/skills/seo-plan/assets/saas.md

@@ -0,0 +1,135 @@
+<!-- Updated: 2026-02-07 -->
+# SaaS SEO Strategy Template
+
+## Industry Characteristics
+
+- Long sales cycles with multiple touchpoints
+- Feature-focused decision making
+- Comparison shopping behavior
+- Heavy research phase before purchase
+- Integration and ecosystem considerations
+
+## Recommended Site Architecture
+
+```
+/
+├── Home
+├── /product (or /platform)
+│   ├── /features
+│   │   ├── /feature-1
+│   │   ├── /feature-2
+│   │   └── ...
+│   ├── /integrations
+│   │   ├── /integration-1
+│   │   └── ...
+│   └── /security
+├── /solutions
+│   ├── /by-industry
+│   │   ├── /industry-1
+│   │   └── ...
+│   └── /by-use-case
+│       ├── /use-case-1
+│       └── ...
+├── /pricing
+├── /customers
+│   ├── /case-studies
+│   │   ├── /case-study-1
+│   │   └── ...
+│   └── /testimonials
+├── /resources
+│   ├── /blog
+│   ├── /guides
+│   ├── /webinars
+│   ├── /templates
+│   └── /glossary
+├── /docs (or /help)
+│   └── /api
+├── /company
+│   ├── /about
+│   ├── /careers
+│   ├── /press
+│   └── /contact
+└── /compare
+    ├── /vs-competitor-1
+    └── /vs-competitor-2
+```
+
+## Content Priorities
+
+### High Priority Pages
+1. Homepage (value proposition, social proof)
+2. Features overview
+3. Pricing page
+4. Key integrations
+5. Top 3-5 use case pages
+
+### Medium Priority Pages
+1. Individual feature pages
+2. Industry solution pages
+3. Case studies (2-3 detailed ones)
+4. Comparison pages (vs competitors)
+
+### Content Marketing Focus
+1. Bottom-of-funnel: Comparison guides, ROI calculators
+2. Middle-of-funnel: How-to guides, best practices
+3. Top-of-funnel: Industry trends, educational content
+
+## Schema Recommendations
+
+| Page Type | Schema Types |
+|-----------|-------------|
+| Homepage | Organization, WebSite, SoftwareApplication |
+| Product/Features | SoftwareApplication, Offer |
+| Pricing | SoftwareApplication, Offer (with pricing) |
+| Blog | Article, BlogPosting |
+| Case Studies | Article, Organization (customer) |
+| Documentation | TechArticle |
+
+## Key Metrics to Track
+
+- Organic traffic to pricing page
+- Demo/trial signups from organic
+- Blog → pricing page conversion
+- Comparison page rankings
+- Integration page performance
+
+## Comparison & Alternative Pages
+
+Comparison pages are among the highest-converting content types for SaaS, with conversion rates of **4-7%** vs. 0.5-1.8% for standard blog content (35.8% of marketers report comparison content performs "better than ever" per Intergrowth November 2025 survey).
+
+**Recommended page types:**
+- `/{product}-vs-{competitor}`: Direct 1:1 comparison
+- `/{competitor}-alternative`: Targeting competitor brand searches
+- `/compare/{category}`: Category comparison hub
+- `/best-{category}-tools`: Roundup-style pages
+
+**Best practices:**
+- Include structured comparison tables with pricing, features, pros/cons
+- Be factually accurate about competitors: verify claims regularly
+- Include customer testimonials from users who switched
+- Add FAQ schema for common comparison questions (valuable for AI search)
+- Update regularly: stale comparison data damages credibility
+- Cross-reference the `seo-competitor-pages` skill for detailed frameworks
+
+**Legal considerations:**
+- Nominative fair use generally permits competitor brand mentions for comparison purposes
+- Do NOT imply endorsement or affiliation
+- Do NOT make false or unverifiable claims about competitor products
+- Different jurisdictions have different trademark laws: consult legal counsel
+
+## Competitive Considerations
+
+- Monitor competitor feature releases
+- Track competitor content strategies
+- Identify keyword gaps in feature coverage
+- Watch for new comparison opportunities
+
+## Generative Engine Optimization (GEO) for SaaS
+
+- [ ] Include clear, structured feature comparisons that AI systems can parse and cite
+- [ ] Use SoftwareApplication schema with complete feature lists and pricing
+- [ ] Publish original benchmark data, case studies, and ROI metrics
+- [ ] Build content clusters around key product categories and use cases
+- [ ] Ensure integration pages have clear, quotable descriptions
+- [ ] Structure pricing information in tables AI can extract
+- [ ] Monitor AI citation across Google AI Overviews, ChatGPT, and Perplexity

package/templates/.agent/skills/seo-programmatic/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: seo-programmatic
+description: "Plan and audit programmatic SEO pages generated at scale from structured data. Use when designing templates, URL systems, internal linking, quality gates, and index-bloat safeguards for pages at scale."
+risk: unknown
+source: "https://github.com/AgriciDaniel/claude-seo"
+date_added: "2026-03-21"
+user-invokable: true
+argument-hint: "[url or plan]"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - WebFetch
+  - Write
+---
+
+# Programmatic SEO Analysis & Planning
+
+Build and audit SEO pages generated at scale from structured data sources.
+Enforces quality gates to prevent thin content penalties and index bloat.
+
+## When to Use
+
+- Use when the user wants programmatic SEO planning or review.
+- Use when designing templates, data-driven pages, or scalable URL systems.
+- Use when preventing thin content and index bloat across large page sets.
+
+## Data Source Assessment
+
+Evaluate the data powering programmatic pages:
+- **CSV/JSON files**: Row count, column uniqueness, missing values
+- **API endpoints**: Response structure, data freshness, rate limits
+- **Database queries**: Record count, field completeness, update frequency
+- Data quality checks:
+  - Each record must have enough unique attributes to generate distinct content
+  - Flag duplicate or near-duplicate records (>80% field overlap)
+  - Verify data freshness; stale data produces stale pages
+
+## Template Engine Planning
+
+Design templates that produce unique, valuable pages:
+- **Variable injection points**: Title, H1, body sections, meta description, schema
+- **Content blocks**: Static (shared across pages) vs dynamic (unique per page)
+- **Conditional logic**: Show/hide sections based on data availability
+- **Supplementary content**: Related items, contextual tips, user-generated content
+- Template review checklist:
+  - Each page must read as a standalone, valuable resource
+  - No "mad-libs" patterns (just swapping city/product names in identical text)
+  - Dynamic sections must add genuine information, not just keyword variations
+
+## URL Pattern Strategy
+
+### Common Patterns
+- `/tools/[tool-name]`: Tool/product directory pages
+- `/[city]/[service]`: Location + service pages
+- `/integrations/[platform]`: Integration landing pages
+- `/glossary/[term]`: Definition/reference pages
+- `/templates/[template-name]`: Downloadable template pages
+
+### URL Rules
+- Lowercase, hyphenated slugs derived from data
+- Logical hierarchy reflecting site architecture
+- No duplicate slugs; enforce uniqueness at generation time
+- Keep URLs under 100 characters
+- No query parameters for primary content URLs
+- Consistent trailing slash usage (match existing site pattern)
+
+## Internal Linking Automation
+
+- **Hub/spoke model**: Category hub pages linking to individual programmatic pages
+- **Related items**: Auto-link to 3-5 related pages based on data attributes
+- **Breadcrumbs**: Generate BreadcrumbList schema from URL hierarchy
+- **Cross-linking**: Link between programmatic pages sharing attributes (same category, same city, same feature)
+- **Anchor text**: Use descriptive, varied anchor text. Avoid exact-match keyword repetition
+- Link density: 3-5 internal links per 1000 words (match seo-content guidelines)
+
+## Thin Content Safeguards
+
+### Quality Gates
+
+| Metric | Threshold | Action |
+|--------|-----------|--------|
+| Pages without content review | 100+ | ⚠️ WARNING: require content audit before publishing |
+| Pages without justification | 500+ | 🛑 HARD STOP: require explicit user approval and thin content audit |
+| Unique content per page | <40% | ❌ Flag as thin content (likely penalty risk) |
+| Word count per page | <300 | ⚠️ Flag for review (may lack sufficient value) |
+
+### Scaled Content Abuse: Enforcement Context (2025-2026)
+
+Google's Scaled Content Abuse policy (introduced March 2024) saw major enforcement escalation in 2025:
+
+- **June 2025:** Wave of manual actions targeting websites with AI-generated content at scale
+- **August 2025:** SpamBrain spam update enhanced pattern detection for AI-generated link schemes and content farms
+- **Result:** Google reported 45% reduction in low-quality, unoriginal content in search results post-March 2024 enforcement
+
+**Enhanced quality gates for programmatic pages:**
+- **Content differentiation:** ≥30-40% of content must be genuinely unique between any two programmatic pages (not just city/keyword string replacement)
+- **Human review:** Minimum 5-10% sample review of generated pages before publishing
+- **Progressive rollout:** Publish in batches of 50-100 pages. Monitor indexing and rankings for 2-4 weeks before expanding. Never publish 500+ programmatic pages simultaneously without explicit quality review.
+- **Standalone value test:** Each page should pass: "Would this page be worth publishing even if no other similar pages existed?"
+- **Site reputation abuse:** If publishing programmatic content under a high-authority domain (not your own), this may trigger site reputation abuse penalties. Google began enforcing this aggressively in November 2024.
+
+> **Recommendation:** The WARNING gate at `<40% unique content` remains appropriate. Consider a HARD STOP at `<30%` unique content to prevent scaled content abuse risk.
+
+### Safe Programmatic Pages (OK at scale)
+✅ Integration pages (with real setup docs, API details, screenshots)
+✅ Template/tool pages (with downloadable content, usage instructions)
+✅ Glossary pages (200+ word definitions with examples, related terms)
+✅ Product pages (unique specs, reviews, comparison data)
+✅ Data-driven pages (unique statistics, charts, analysis per record)
+
+### Penalty Risk (avoid at scale)
+❌ Location pages with only city name swapped in identical text
+❌ "Best [tool] for [industry]" without industry-specific value
+❌ "[Competitor] alternative" without real comparison data
+❌ AI-generated pages without human review and unique value-add
+❌ Pages where >60% of content is shared template boilerplate
+
+### Uniqueness Calculation
+Unique content % = (words unique to this page) / (total words on page) × 100
+
+Measure against all other pages in the programmatic set. Shared headers, footers, and navigation are excluded from the calculation. Template boilerplate text IS included.
+
+## Canonical Strategy
+
+- Every programmatic page must have a self-referencing canonical tag
+- Parameter variations (sort, filter, pagination) canonical to the base URL
+- Paginated series: canonical to page 1 or use rel=next/prev
+- If programmatic pages overlap with manual pages, the manual page is canonical
+- No canonical to a different domain unless intentional cross-domain setup
+
+## Sitemap Integration
+
+- Auto-generate sitemap entries for all programmatic pages
+- Split at 50,000 URLs per sitemap file (protocol limit)
+- Use sitemap index if multiple sitemap files needed
+- `<lastmod>` reflects actual data update timestamp (not generation time)
+- Exclude noindexed programmatic pages from sitemap
+- Register sitemap in robots.txt
+- Update sitemap dynamically as new records are added to data source
+
+## Index Bloat Prevention
+
+- **Noindex low-value pages**: Pages that don't meet quality gates
+- **Pagination**: Noindex paginated results beyond page 1 (or use rel=next/prev)
+- **Faceted navigation**: Noindex filtered views, canonical to base category
+- **Crawl budget**: For sites with >10k programmatic pages, monitor crawl stats in Search Console
+- **Thin page consolidation**: Merge records with insufficient data into aggregated pages
+- **Regular audits**: Monthly review of indexed page count vs intended count
+
+## Output
+
+### Programmatic SEO Score: XX/100
+
+### Assessment Summary
+| Category | Status | Score |
+|----------|--------|-------|
+| Data Quality | ✅/⚠️/❌ | XX/100 |
+| Template Uniqueness | ✅/⚠️/❌ | XX/100 |
+| URL Structure | ✅/⚠️/❌ | XX/100 |
+| Internal Linking | ✅/⚠️/❌ | XX/100 |
+| Thin Content Risk | ✅/⚠️/❌ | XX/100 |
+| Index Management | ✅/⚠️/❌ | XX/100 |
+
+### Critical Issues (fix immediately)
+### High Priority (fix within 1 week)
+### Medium Priority (fix within 1 month)
+### Low Priority (backlog)
+
+### Recommendations
+- Data source improvements
+- Template modifications
+- URL pattern adjustments
+- Quality gate compliance actions
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| URL unreachable | Report connection error with status code. Suggest verifying URL accessibility and checking for authentication requirements. |
+| No programmatic pages detected | Inform user that no template-generated or data-driven page patterns were found. Suggest checking if pages use client-side rendering or if the URL points to the correct section. |
+| Thin content threshold exceeded | Trigger quality gate warning. Report the unique content percentage and flag pages below 40% uniqueness. Require user acknowledgment before proceeding. |
+| Quality gate violation | Halt analysis at the HARD STOP threshold (500+ pages without justification or <30% unique content). Present findings and require explicit user approval to continue. |

package/templates/.agent/skills/seo-schema/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: seo-schema
+description: >
+  Detect, validate, and generate Schema.org structured data. JSON-LD format
+  preferred. Use when user says "schema", "structured data", "rich results",
+  "JSON-LD", or "markup".
+risk: unknown
+source: "https://github.com/AgriciDaniel/claude-seo"
+date_added: "2026-03-21"
+user-invokable: true
+argument-hint: "[url]"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - WebFetch
+  - Write
+---
+
+# Schema Markup Analysis & Generation
+
+## When to Use
+
+- Use when detecting, validating, or generating Schema.org structured data.
+- Use when the user asks about JSON-LD, rich results, or markup opportunities.
+- Use when schema validation is the main task, rather than a broader SEO audit.
+
+## Detection
+
+1. Scan page source for JSON-LD `<script type="application/ld+json">`
+2. Check for Microdata (`itemscope`, `itemprop`)
+3. Check for RDFa (`typeof`, `property`)
+4. Always recommend JSON-LD as primary format (Google's stated preference)
+
+## Validation
+
+- Check required properties per schema type
+- Validate against Google's supported rich result types
+- Test for common errors:
+  - Missing @context
+  - Invalid @type
+  - Wrong data types
+  - Placeholder text
+  - Relative URLs (should be absolute)
+  - Invalid date formats
+- Flag deprecated types (see below)
+
+## Schema Type Status (as of Feb 2026)
+
+Read `references/schema-types.md` for the full list. Key rules:
+
+### ACTIVE (recommend freely):
+Organization, LocalBusiness, SoftwareApplication, WebApplication, Product (with Certification markup as of April 2025), ProductGroup, Offer, Service, Article, BlogPosting, NewsArticle, Review, AggregateRating, BreadcrumbList, WebSite, WebPage, Person, ProfilePage, ContactPage, VideoObject, ImageObject, Event, JobPosting, Course, DiscussionForumPosting
+
+### VIDEO & SPECIALIZED (recommend freely):
+BroadcastEvent, Clip, SeekToAction, SoftwareSourceCode
+
+See `schema/templates.json` for ready-to-use JSON-LD templates for these types.
+
+> **JSON-LD and JavaScript rendering:** Per Google's December 2025 JS SEO guidance, structured data injected via JavaScript may face delayed processing. For time-sensitive markup (especially Product, Offer), include JSON-LD in the initial server-rendered HTML.
+
+### RESTRICTED (only for specific sites):
+- **FAQ**: ONLY for government and healthcare authority sites (restricted Aug 2023)
+
+### DEPRECATED (never recommend):
+- **HowTo**: Rich results removed September 2023
+- **SpecialAnnouncement**: Deprecated July 31, 2025
+- **CourseInfo, EstimatedSalary, LearningVideo**: Retired June 2025
+- **ClaimReview**: Retired from rich results June 2025
+- **VehicleListing**: Retired from rich results June 2025
+- **Practice Problem**: Retired from rich results late 2025
+- **Dataset**: Retired from rich results late 2025
+- **Book Actions**: Deprecated then reversed, still functional as of Feb 2026 (historical note)
+
+## Generation
+
+When generating schema for a page:
+1. Identify page type from content analysis
+2. Select appropriate schema type(s)
+3. Generate valid JSON-LD with all required + recommended properties
+4. Include only truthful, verifiable data. Use placeholders clearly marked for user to fill
+5. Validate output before presenting
+
+## Common Schema Templates
+
+### Organization
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "[Company Name]",
+  "url": "[Website URL]",
+  "logo": "[Logo URL]",
+  "contactPoint": {
+    "@type": "ContactPoint",
+    "telephone": "[Phone]",
+    "contactType": "customer service"
+  },
+  "sameAs": [
+    "[Facebook URL]",
+    "[LinkedIn URL]",
+    "[Twitter URL]"
+  ]
+}
+```
+
+### LocalBusiness
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "LocalBusiness",
+  "name": "[Business Name]",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "[Street]",
+    "addressLocality": "[City]",
+    "addressRegion": "[State]",
+    "postalCode": "[ZIP]",
+    "addressCountry": "US"
+  },
+  "telephone": "[Phone]",
+  "openingHours": "Mo-Fr 09:00-17:00",
+  "geo": {
+    "@type": "GeoCoordinates",
+    "latitude": "[Lat]",
+    "longitude": "[Long]"
+  }
+}
+```
+
+### Article/BlogPosting
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "[Title]",
+  "author": {
+    "@type": "Person",
+    "name": "[Author Name]"
+  },
+  "datePublished": "[YYYY-MM-DD]",
+  "dateModified": "[YYYY-MM-DD]",
+  "image": "[Image URL]",
+  "publisher": {
+    "@type": "Organization",
+    "name": "[Publisher]",
+    "logo": {
+      "@type": "ImageObject",
+      "url": "[Logo URL]"
+    }
+  }
+}
+```
+
+## Output
+
+- `SCHEMA-REPORT.md`: detection and validation results
+- `generated-schema.json`: ready-to-use JSON-LD snippets
+
+### Validation Results
+| Schema | Type | Status | Issues |
+|--------|------|--------|--------|
+| ... | ... | ✅/⚠️/❌ | ... |
+
+### Recommendations
+- Missing schema opportunities
+- Validation fixes needed
+- Generated code for implementation
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| URL unreachable | Report connection error with status code. Suggest verifying URL and checking if the page requires authentication. |
+| No schema markup found | Report that no JSON-LD, Microdata, or RDFa was detected. Recommend appropriate schema types based on page content analysis. |
+| Invalid JSON-LD syntax | Parse and report specific syntax errors (missing brackets, trailing commas, unquoted keys). Provide corrected JSON-LD output. |
+| Deprecated schema type detected | Flag the deprecated type with its retirement date. Recommend the current replacement type or advise removal if no replacement exists. |