codehava-agent-kit 1.0.1 → 3.0.0

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

@@ -0,0 +1,193 @@
+---
+name: seo-images
+description: >
+  Image optimization analysis for SEO and performance. Checks alt text, file
+  sizes, formats, responsive images, lazy loading, and CLS prevention. Use when
+  user says "image optimization", "alt text", "image SEO", "image size",
+  or "image audit".
+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
+---
+
+# Image Optimization Analysis
+
+## When to Use
+
+- Use when auditing image SEO, alt text, file sizes, formats, or lazy loading.
+- Use when the user wants image-specific performance recommendations.
+- Use when checking media quality signals that affect both SEO and Core Web Vitals.
+
+## Checks
+
+### Alt Text
+- Present on all `<img>` elements (except decorative: `role="presentation"`)
+- Descriptive: describes the image content, not "image.jpg" or "photo"
+- Includes relevant keywords where natural, not keyword-stuffed
+- Length: 10-125 characters
+
+**Good examples:**
+- "Professional plumber repairing kitchen sink faucet"
+- "Red 2024 Toyota Camry sedan front view"
+- "Team meeting in modern office conference room"
+
+**Bad examples:**
+- "image.jpg" (filename, not description)
+- "plumber plumbing plumber services" (keyword stuffing)
+- "Click here" (not descriptive)
+
+### File Size
+
+**Tiered thresholds by image category:**
+
+| Image Category | Target | Warning | Critical |
+|----------------|--------|---------|----------|
+| Thumbnails | < 50KB | > 100KB | > 200KB |
+| Content images | < 100KB | > 200KB | > 500KB |
+| Hero/banner images | < 200KB | > 300KB | > 700KB |
+
+Recommend compression to target thresholds where possible without quality loss.
+
+### Format
+| Format | Browser Support | Use Case |
+|--------|-----------------|----------|
+| WebP | 97%+ | Default recommendation |
+| AVIF | 92%+ | Best compression, newer |
+| JPEG | 100% | Fallback for photos |
+| PNG | 100% | Graphics with transparency |
+| SVG | 100% | Icons, logos, illustrations |
+
+Recommend WebP/AVIF over JPEG/PNG. Check for `<picture>` element with format fallbacks.
+
+#### Recommended `<picture>` Element Pattern
+
+Use progressive enhancement with the most efficient format first:
+
+```html
+<picture>
+  <source srcset="image.avif" type="image/avif">
+  <source srcset="image.webp" type="image/webp">
+  <img src="image.jpg" alt="Descriptive alt text" width="800" height="600" loading="lazy" decoding="async">
+</picture>
+```
+
+The browser will use the first supported format. Current browser support: AVIF 93.8%, WebP 95.3%.
+
+#### JPEG XL: Emerging Format
+
+In November 2025, Google's Chromium team reversed its 2022 decision and announced it will restore JPEG XL support in Chrome using a Rust-based decoder. The implementation is feature-complete but not yet in Chrome stable. JPEG XL offers lossless JPEG recompression (~20% savings with zero quality loss) and competitive lossy compression. Not yet practical for web deployment, but worth monitoring for future adoption.
+
+### Responsive Images
+- `srcset` attribute for multiple sizes
+- `sizes` attribute matching layout breakpoints
+- Appropriate resolution for device pixel ratios
+
+```html
+<img
+  src="image-800.jpg"
+  srcset="image-400.jpg 400w, image-800.jpg 800w, image-1200.jpg 1200w"
+  sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
+  alt="Description"
+>
+```
+
+### Lazy Loading
+- `loading="lazy"` on below-fold images
+- Do NOT lazy-load above-fold/hero images (hurts LCP)
+- Check for native vs JavaScript-based lazy loading
+
+```html
+<!-- Below fold - lazy load -->
+<img src="photo.jpg" loading="lazy" alt="Description">
+
+<!-- Above fold - eager load (default) -->
+<img src="hero.jpg" alt="Hero image">
+```
+
+### `fetchpriority="high"` for LCP Images
+
+Add `fetchpriority="high"` to your hero/LCP image to prioritize its download in the browser's network queue:
+
+```html
+<img src="hero.webp" fetchpriority="high" alt="Hero image description" width="1200" height="630">
+```
+
+**Critical:** Do NOT lazy-load above-the-fold/LCP images. Using `loading="lazy"` on LCP images directly harms LCP scores. Reserve `loading="lazy"` for below-the-fold images only.
+
+### `decoding="async"` for Non-LCP Images
+
+Add `decoding="async"` to non-LCP images to prevent image decoding from blocking the main thread:
+
+```html
+<img src="photo.webp" alt="Description" width="600" height="400" loading="lazy" decoding="async">
+```
+
+### CLS Prevention
+- `width` and `height` attributes set on all `<img>` elements
+- `aspect-ratio` CSS as alternative
+- Flag images without dimensions
+
+```html
+<!-- Good - dimensions set -->
+<img src="photo.jpg" width="800" height="600" alt="Description">
+
+<!-- Good - CSS aspect ratio -->
+<img src="photo.jpg" style="aspect-ratio: 4/3" alt="Description">
+
+<!-- Bad - no dimensions -->
+<img src="photo.jpg" alt="Description">
+```
+
+### File Names
+- Descriptive: `blue-running-shoes.webp` not `IMG_1234.jpg`
+- Hyphenated, lowercase, no special characters
+- Include relevant keywords
+
+### CDN Usage
+- Check if images served from CDN (different domain, CDN headers)
+- Recommend CDN for image-heavy sites
+- Check for edge caching headers
+
+## Output
+
+### Image Audit Summary
+
+| Metric | Status | Count |
+|--------|--------|-------|
+| Total Images | - | XX |
+| Missing Alt Text | ❌ | XX |
+| Oversized (>200KB) | ⚠️ | XX |
+| Wrong Format | ⚠️ | XX |
+| No Dimensions | ⚠️ | XX |
+| Not Lazy Loaded | ⚠️ | XX |
+
+### Prioritized Optimization List
+
+Sorted by file size impact (largest savings first):
+
+| Image | Current Size | Format | Issues | Est. Savings |
+|-------|--------------|--------|--------|--------------|
+| ... | ... | ... | ... | ... |
+
+### Recommendations
+1. Convert X images to WebP format (est. XX KB savings)
+2. Add alt text to X images
+3. Add dimensions to X images
+4. Enable lazy loading on X below-fold images
+5. Compress X oversized images
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| URL unreachable | Report connection error with status code. Suggest verifying URL and checking if site requires authentication. |
+| No images found on page | Report that no `<img>` elements were detected. Suggest checking if images are loaded via JavaScript or CSS background-image. |
+| Images behind CDN or authentication | Note that image files could not be directly accessed for size analysis. Report available metadata (alt text, dimensions, format from markup) and flag inaccessible resources. |

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

@@ -0,0 +1,94 @@
+---
+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.
+risk: unknown
+source: community
+date_added: '2026-02-27'
+---
+
+## 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/templates/.agent/skills/seo-meta-optimizer/SKILL.md

@@ -0,0 +1,91 @@
+---
+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.
+risk: unknown
+source: community
+date_added: '2026-02-27'
+---
+
+## 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/templates/.agent/skills/seo-page/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: seo-page
+description: >
+  Deep single-page SEO analysis covering on-page elements, content quality,
+  technical meta tags, schema, images, and performance. Use when user says
+  "analyze this page", "check page SEO", or provides a single URL for review.
+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
+---
+
+# Single Page Analysis
+
+## When to Use
+
+- Use when the user provides a single URL for detailed on-page SEO review.
+- Use when auditing one page rather than an entire site.
+- Use when checking metadata, content, schema, images, and page-level technical signals together.
+
+## What to Analyze
+
+### On-Page SEO
+- Title tag: 50-60 characters, includes primary keyword, unique
+- Meta description: 150-160 characters, compelling, includes keyword
+- H1: exactly one, matches page intent, includes keyword
+- H2-H6: logical hierarchy (no skipped levels), descriptive
+- URL: short, descriptive, hyphenated, no parameters
+- Internal links: sufficient, relevant anchor text, no orphan pages
+- External links: to authoritative sources, reasonable count
+
+### Content Quality
+- Word count vs page type minimums (see quality-gates.md)
+- Readability: Flesch Reading Ease score, grade level
+- Keyword density: natural (1-3%), semantic variations present
+- E-E-A-T signals: author bio, credentials, first-hand experience markers
+- Content freshness: publication date, last updated date
+
+### Technical Elements
+- Canonical tag: present, self-referencing or correct
+- Meta robots: index/follow unless intentionally blocked
+- Open Graph: og:title, og:description, og:image, og:url
+- Twitter Card: twitter:card, twitter:title, twitter:description
+- Hreflang: if multi-language, correct implementation
+
+### Schema Markup
+- Detect all types (JSON-LD preferred)
+- Validate required properties
+- Identify missing opportunities
+- NEVER recommend HowTo (deprecated) or FAQ (restricted to gov/health)
+
+### Images
+- Alt text: present, descriptive, includes keywords where natural
+- File size: flag >200KB (warning), >500KB (critical)
+- Format: recommend WebP/AVIF over JPEG/PNG
+- Dimensions: width/height set for CLS prevention
+- Lazy loading: loading="lazy" on below-fold images
+
+### Core Web Vitals (reference only, not measurable from HTML alone)
+- Flag potential LCP issues (huge hero images, render-blocking resources)
+- Flag potential INP issues (heavy JS, no async/defer)
+- Flag potential CLS issues (missing image dimensions, injected content)
+
+## Output
+
+### Page Score Card
+```
+Overall Score: XX/100
+
+On-Page SEO:     XX/100  ████████░░
+Content Quality: XX/100  ██████████
+Technical:       XX/100  ███████░░░
+Schema:          XX/100  █████░░░░░
+Images:          XX/100  ████████░░
+```
+
+### Issues Found
+Organized by priority: Critical -> High -> Medium -> Low
+
+### Recommendations
+Specific, actionable improvements with expected impact
+
+### Schema Suggestions
+Ready-to-use JSON-LD code for detected opportunities
+
+## DataForSEO Integration (Optional)
+
+If DataForSEO MCP tools are available, use `serp_organic_live_advanced` for real SERP positions and `backlinks_summary` for backlink data and spam scores.
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess page content. Suggest the user verify the URL and try again. |
+| Page requires authentication (401/403) | Report that the page is behind authentication. Suggest the user provide the rendered HTML directly or a publicly accessible URL. |
+| JavaScript-rendered content (empty body in HTML) | Note that key content may be rendered client-side. Analyze the available HTML and flag that results may be incomplete. Suggest using a browser-rendered snapshot if available. |

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

@@ -0,0 +1,136 @@
+---
+name: seo-plan
+description: >
+  Strategic SEO planning for new or existing websites. Industry-specific
+  templates, competitive analysis, content strategy, and implementation
+  roadmap. Use when user says "SEO plan", "SEO strategy", "content strategy",
+  "site architecture", or "SEO roadmap".
+risk: unknown
+source: "https://github.com/AgriciDaniel/claude-seo"
+date_added: "2026-03-21"
+user-invokable: true
+argument-hint: "[business-type]"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - WebFetch
+  - Write
+---
+
+# Strategic SEO Planning
+
+## When to Use
+
+- Use when building an SEO strategy or roadmap for a new or existing site.
+- Use when planning content, architecture, and implementation phases together.
+- Use when the user asks for an SEO plan rather than a point-in-time audit.
+
+## Process
+
+### 1. Discovery
+- Business type, target audience, competitors, goals
+- Current site assessment (if exists)
+- Budget and timeline constraints
+- Key performance indicators (KPIs)
+
+### 2. Competitive Analysis
+- Identify top 5 competitors
+- Analyze their content strategy, schema usage, technical setup
+- Identify keyword gaps and content opportunities
+- Assess their E-E-A-T signals
+- Estimate their domain authority
+
+### 3. Architecture Design
+- Load industry template from `assets/` directory
+- Design URL hierarchy and content pillars
+- Plan internal linking strategy
+- Sitemap structure with quality gates applied
+- Information architecture for user journeys
+
+### 4. Content Strategy
+- Content gaps vs competitors
+- Page types and estimated counts
+- Blog/resource topics and publishing cadence
+- E-E-A-T building plan (author bios, credentials, experience signals)
+- Content calendar with priorities
+
+### 5. Technical Foundation
+- Hosting and performance requirements
+- Schema markup plan per page type
+- Core Web Vitals baseline targets
+- AI search readiness requirements
+- Mobile-first considerations
+
+### 6. Implementation Roadmap (4 phases)
+
+#### Phase 1: Foundation (weeks 1-4)
+- Technical setup and infrastructure
+- Core pages (home, about, contact, main services)
+- Essential schema implementation
+- Analytics and tracking setup
+
+#### Phase 2: Expansion (weeks 5-12)
+- Content creation for primary pages
+- Blog launch with initial posts
+- Internal linking structure
+- Local SEO setup (if applicable)
+
+#### Phase 3: Scale (weeks 13-24)
+- Advanced content development
+- Link building and outreach
+- GEO optimization
+- Performance optimization
+
+#### Phase 4: Authority (months 7-12)
+- Thought leadership content
+- PR and media mentions
+- Advanced schema implementation
+- Continuous optimization
+
+## Industry Templates
+
+Load from `assets/` directory:
+- `saas.md`: SaaS/software companies
+- `local-service.md`: Local service businesses
+- `ecommerce.md`: E-commerce stores
+- `publisher.md`: Content publishers/media
+- `agency.md`: Agencies and consultancies
+- `generic.md`: General business template
+
+## Output
+
+### Deliverables
+- `SEO-STRATEGY.md`: Complete strategic plan
+- `COMPETITOR-ANALYSIS.md`: Competitive insights
+- `CONTENT-CALENDAR.md`: Content roadmap
+- `IMPLEMENTATION-ROADMAP.md`: Phased action plan
+- `SITE-STRUCTURE.md`: URL hierarchy and architecture
+
+### KPI Targets
+| Metric | Baseline | 3 Month | 6 Month | 12 Month |
+|--------|----------|---------|---------|----------|
+| Organic Traffic | ... | ... | ... | ... |
+| Keyword Rankings | ... | ... | ... | ... |
+| Domain Authority | ... | ... | ... | ... |
+| Indexed Pages | ... | ... | ... | ... |
+| Core Web Vitals | ... | ... | ... | ... |
+
+### Success Criteria
+- Clear, measurable goals per phase
+- Resource requirements defined
+- Dependencies identified
+- Risk mitigation strategies
+
+## DataForSEO Integration (Optional)
+
+If DataForSEO MCP tools are available, use `dataforseo_labs_google_competitors_domain` and `dataforseo_labs_google_domain_intersection` for real competitive intelligence, `dataforseo_labs_bulk_traffic_estimation` for traffic estimates, `kw_data_google_ads_search_volume` and `dataforseo_labs_bulk_keyword_difficulty` for keyword research, and `business_data_business_listings_search` for local business data.
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Unrecognized business type | Fall back to `generic.md` template. Inform user that no industry-specific template was found and proceed with the general business template. |
+| No website URL provided | Proceed with new-site planning mode. Skip current site assessment and competitive gap analysis that require a live URL. |
+| Industry template not found | Check `assets/` directory for available templates. If the requested template file is missing, use `generic.md` and note the missing template in output. |