opencode-skills-antigravity 1.0.4 → 1.0.6

package/bundled-skills/seo-hreflang/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: seo-hreflang
+description: >
+  Hreflang and international SEO audit, validation, and generation. Detects
+  common mistakes, validates language/region codes, and generates correct
+  hreflang implementations. Use when user says "hreflang", "i18n SEO",
+  "international SEO", "multi-language", "multi-region", or "language tags".
+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
+---
+
+# Hreflang & International SEO
+
+## When to Use
+
+- Use when validating or generating hreflang for multilingual or multiregional sites.
+- Use when the user mentions international SEO, language tags, x-default, or hreflang issues.
+- Use when auditing locale alternates across HTML, headers, or sitemap implementations.
+
+Validate existing hreflang implementations or generate correct hreflang tags
+for multi-language and multi-region sites. Supports HTML, HTTP header, and
+XML sitemap implementations.
+
+## Validation Checks
+
+### 1. Self-Referencing Tags
+- Every page must include an hreflang tag pointing to itself
+- The self-referencing URL must exactly match the page's canonical URL
+- Missing self-referencing tags cause Google to ignore the entire hreflang set
+
+### 2. Return Tags
+- If page A links to page B with hreflang, page B must link back to page A
+- Every hreflang relationship must be bidirectional (A→B and B→A)
+- Missing return tags invalidate the hreflang signal for both pages
+- Check all language versions reference each other (full mesh)
+
+### 3. x-default Tag
+- Required: designates the fallback page for unmatched languages/regions
+- Typically points to the language selector page or English version
+- Only one x-default per set of alternates
+- Must also have return tags from all other language versions
+
+### 4. Language Code Validation
+- Must use ISO 639-1 two-letter codes (e.g., `en`, `fr`, `de`, `ja`)
+- Common errors:
+  - `eng` instead of `en` (ISO 639-2, not valid for hreflang)
+  - `jp` instead of `ja` (incorrect code for Japanese)
+  - `zh` without region qualifier (ambiguous; use `zh-Hans` or `zh-Hant`)
+
+### 5. Region Code Validation
+- Optional region qualifier uses ISO 3166-1 Alpha-2 (e.g., `en-US`, `en-GB`, `pt-BR`)
+- Format: `language-REGION` (lowercase language, uppercase region)
+- Common errors:
+  - `en-uk` instead of `en-GB` (UK is not a valid ISO 3166-1 code)
+  - `es-LA` (Latin America is not a country; use specific countries)
+  - Region without language prefix
+
+### 6. Canonical URL Alignment
+- Hreflang tags must only appear on canonical URLs
+- If a page has `rel=canonical` pointing elsewhere, hreflang on that page is ignored
+- The canonical URL and hreflang URL must match exactly (including trailing slashes)
+- Non-canonical pages should not be in any hreflang set
+
+### 7. Protocol Consistency
+- All URLs in an hreflang set must use the same protocol (HTTPS or HTTP)
+- Mixed HTTP/HTTPS in hreflang sets causes validation failures
+- After HTTPS migration, update all hreflang tags to HTTPS
+
+### 8. Cross-Domain Support
+- Hreflang works across different domains (e.g., example.com and example.de)
+- Cross-domain hreflang requires return tags on both domains
+- Verify both domains are verified in Google Search Console
+- Sitemap-based implementation recommended for cross-domain setups
+
+## Common Mistakes
+
+| Issue | Severity | Fix |
+|-------|----------|-----|
+| Missing self-referencing tag | Critical | Add hreflang pointing to same page URL |
+| Missing return tags (A→B but no B→A) | Critical | Add matching return tags on all alternates |
+| Missing x-default | High | Add x-default pointing to fallback/selector page |
+| Invalid language code (e.g., `eng`) | High | Use ISO 639-1 two-letter codes |
+| Invalid region code (e.g., `en-uk`) | High | Use ISO 3166-1 Alpha-2 codes |
+| Hreflang on non-canonical URL | High | Move hreflang to canonical URL only |
+| HTTP/HTTPS mismatch in URLs | Medium | Standardize all URLs to HTTPS |
+| Trailing slash inconsistency | Medium | Match canonical URL format exactly |
+| Hreflang in both HTML and sitemap | Low | Choose one method (sitemap preferred for large sites) |
+| Language without region when needed | Low | Add region qualifier for geo-targeted content |
+
+## Implementation Methods
+
+### Method 1: HTML Link Tags
+Best for: Sites with <50 language/region variants per page.
+
+```html
+<link rel="alternate" hreflang="en-US" href="https://example.com/page" />
+<link rel="alternate" hreflang="en-GB" href="https://example.co.uk/page" />
+<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
+<link rel="alternate" hreflang="x-default" href="https://example.com/page" />
+```
+
+Place in `<head>` section. Every page must include all alternates including itself.
+
+### Method 2: HTTP Headers
+Best for: Non-HTML files (PDFs, documents).
+
+```
+Link: <https://example.com/page>; rel="alternate"; hreflang="en-US",
+      <https://example.com/fr/page>; rel="alternate"; hreflang="fr",
+      <https://example.com/page>; rel="alternate"; hreflang="x-default"
+```
+
+Set via server configuration or CDN rules.
+
+### Method 3: XML Sitemap (Recommended for large sites)
+Best for: Sites with many language variants, cross-domain setups, or 50+ pages.
+
+See Hreflang Sitemap Generation section below.
+
+### Method Comparison
+| Method | Best For | Pros | Cons |
+|--------|----------|------|------|
+| HTML link tags | Small sites (<50 variants) | Easy to implement, visible in source | Bloats `<head>`, hard to maintain at scale |
+| HTTP headers | Non-HTML files | Works for PDFs, images | Complex server config, not visible in HTML |
+| XML sitemap | Large sites, cross-domain | Scalable, centralized management | Not visible on page, requires sitemap maintenance |
+
+## Hreflang Generation
+
+### Process
+1. **Detect languages**: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute)
+2. **Map page equivalents**: Match corresponding pages across languages/regions
+3. **Validate language codes**: Verify all codes against ISO 639-1 and ISO 3166-1
+4. **Generate tags**: Create hreflang tags for each page including self-referencing
+5. **Verify return tags**: Confirm all relationships are bidirectional
+6. **Add x-default**: Set fallback for each page set
+7. **Output**: Generate implementation code (HTML, HTTP headers, or sitemap XML)
+
+## Hreflang Sitemap Generation
+
+### Sitemap with Hreflang
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+        xmlns:xhtml="http://www.w3.org/1999/xhtml">
+  <url>
+    <loc>https://example.com/page</loc>
+    <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
+    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
+    <xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" />
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
+  </url>
+  <url>
+    <loc>https://example.com/fr/page</loc>
+    <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/page" />
+    <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
+    <xhtml:link rel="alternate" hreflang="de" href="https://example.de/page" />
+    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
+  </url>
+</urlset>
+```
+
+Key rules:
+- Include the `xmlns:xhtml` namespace declaration
+- Every `<url>` entry must include ALL language alternates (including itself)
+- Each alternate must appear as a separate `<url>` entry with its own full set
+- Split at 50,000 URLs per sitemap file
+
+## Output
+
+### Hreflang Validation Report
+
+#### Summary
+- Total pages scanned: XX
+- Language variants detected: XX
+- Issues found: XX (Critical: X, High: X, Medium: X, Low: X)
+
+#### Validation Results
+| Language | URL | Self-Ref | Return Tags | x-default | Status |
+|----------|-----|----------|-------------|-----------|--------|
+| en-US | https://... | ✅ | ✅ | ✅ | ✅ |
+| fr | https://... | ❌ | ⚠️ | ✅ | ❌ |
+| de | https://... | ✅ | ❌ | ✅ | ❌ |
+
+### Generated Hreflang Tags
+- HTML `<link>` tags (if HTML method chosen)
+- HTTP header values (if header method chosen)
+- `hreflang-sitemap.xml` (if sitemap method chosen)
+
+### Recommendations
+- Missing implementations to add
+- Incorrect codes to fix
+- Method migration suggestions (e.g., HTML to sitemap for scale)
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess site structure. Suggest the user verify the URL and try again. |
+| No hreflang tags found | Report the absence. Check for other internationalization signals (subdirectories, subdomains, ccTLDs) and recommend the appropriate hreflang implementation method. |
+| Invalid language/region codes detected | List each invalid code with the correct replacement. Provide a corrected hreflang tag set ready to implement. |

package/bundled-skills/seo-image-gen/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: seo-image-gen
+description: "Generate SEO-focused images such as OG cards, hero images, schema assets, product visuals, and infographics. Use when image generation is part of an SEO workflow or content publishing task."
+risk: unknown
+source: "https://github.com/AgriciDaniel/claude-seo"
+date_added: "2026-03-21"
+argument-hint: "[og|hero|product|infographic|custom|batch] <description>"
+user-invokable: true
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - WebFetch
+  - Write
+---
+
+# SEO Image Gen: AI Image Generation for SEO Assets (Extension)
+
+Generate production-ready images for SEO use cases using Gemini's image generation
+via the banana Creative Director pipeline. Maps SEO needs to optimized domain modes,
+aspect ratios, and resolution defaults.
+
+## When to Use
+
+- Use when generating OG images, hero images, schema visuals, infographics, or similar SEO assets.
+- Use when image generation is part of a broader SEO or publishing workflow.
+- Use only when the required image-generation extension is available.
+
+## Architecture Note
+
+This skill has two components with distinct roles:
+- **SKILL.md** (this file): Handles interactive `/seo image-gen` commands for generating images
+- **Agent** (`agents/seo-image-gen.md`): Audit-only analyst spawned during `/seo audit` to assess existing OG/social images and produce a generation plan (never auto-generates)
+
+## Prerequisites
+
+This skill requires the banana extension to be installed:
+```bash
+./extensions/banana/install.sh
+```
+
+**Check availability:** Before using any image generation tool, verify the MCP server
+is connected by checking if `gemini_generate_image` or `set_aspect_ratio` tools are
+available. If tools are not available, inform the user the extension is not installed
+and provide install instructions.
+
+## Quick Reference
+
+| Command | What it does |
+|---------|-------------|
+| `/seo image-gen og <description>` | Generate OG/social preview image (1200x630 feel) |
+| `/seo image-gen hero <description>` | Blog hero image (widescreen, dramatic) |
+| `/seo image-gen product <description>` | Product photography (clean, white BG) |
+| `/seo image-gen infographic <description>` | Infographic visual (vertical, data-heavy) |
+| `/seo image-gen custom <description>` | Custom image with full Creative Director pipeline |
+| `/seo image-gen batch <description> [N]` | Generate N variations (default: 3) |
+
+## SEO Image Use Cases
+
+Each use case maps to pre-configured banana parameters:
+
+| Use Case | Aspect Ratio | Resolution | Domain Mode | Notes |
+|----------|-------------|------------|-------------|-------|
+| **OG/Social Preview** | `16:9` | `1K` | Product or UI/Web | Clean, professional, text-friendly |
+| **Blog Hero** | `16:9` | `2K` | Cinema or Editorial | Dramatic, atmospheric, editorial quality |
+| **Schema Image** | `4:3` | `1K` | Product | Clean, descriptive, schema ImageObject |
+| **Social Square** | `1:1` | `1K` | UI/Web | Platform-optimized square |
+| **Product Photo** | `4:3` | `2K` | Product | White background, studio lighting |
+| **Infographic** | `2:3` | `4K` | Infographic | Data-heavy, vertical layout |
+| **Favicon/Icon** | `1:1` | `512` | Logo | Minimal, scalable, recognizable |
+| **Pinterest Pin** | `2:3` | `2K` | Editorial | Tall vertical card |
+
+## Generation Pipeline
+
+For every generation request:
+
+1. **Identify use case** from command or context (og, hero, product, etc.)
+2. **Apply SEO defaults** from the use cases table above
+3. **Set aspect ratio** via `set_aspect_ratio` MCP tool
+4. **Construct Reasoning Brief** using the banana Creative Director pipeline:
+   - Load `references/prompt-engineering.md` for the 6-component system
+   - Apply domain mode emphasis (Subject 30%, Style 25%, Context 15%, etc.)
+   - Be SPECIFIC and VISCERAL: describe what the camera sees
+5. **Generate** via `gemini_generate_image` MCP tool
+6. **Post-generation SEO checklist** (see below)
+
+### Check for Presets
+
+If the user mentions a brand or has SEO presets configured:
+```bash
+python3 ~/.claude/skills/seo-image-gen/scripts/presets.py list
+```
+Load matching preset and apply as defaults. Also check `references/seo-image-presets.md`
+for SEO-specific preset templates.
+
+## Post-Generation SEO Checklist
+
+After every successful generation, guide the user on:
+
+1. **Alt text**:Write descriptive, keyword-rich alt text for the generated image
+2. **File naming**:Rename to SEO-friendly format: `keyword-description-widthxheight.webp`
+3. **WebP conversion**:Convert to WebP for optimal page speed:
+   ```bash
+   magick output.png -quality 85 output.webp
+   ```
+4. **File size**:Target under 200KB for hero images, under 100KB for thumbnails
+5. **Schema markup**:Suggest `ImageObject` schema for the generated image:
+   ```json
+   {
+     "@type": "ImageObject",
+     "url": "https://example.com/images/keyword-description.webp",
+     "width": 1200,
+     "height": 630,
+     "caption": "Descriptive caption with target keyword"
+   }
+   ```
+6. **OG meta tags**:For social preview images, remind about:
+   ```html
+   <meta property="og:image" content="https://example.com/images/og-image.webp" />
+   <meta property="og:image:width" content="1200" />
+   <meta property="og:image:height" content="630" />
+   <meta property="og:image:alt" content="Descriptive alt text" />
+   ```
+
+## Cost Awareness
+
+Image generation costs money. Be transparent:
+- Show estimated cost before generating (especially for batch)
+- Log every generation: `python3 ~/.claude/skills/seo-image-gen/scripts/cost_tracker.py log --model MODEL --resolution RES --prompt "brief"`
+- Run `cost_tracker.py summary` if user asks about usage
+
+Approximate costs (gemini-3.1-flash):
+- 512: ~$0.02/image
+- 1K resolution: ~$0.04/image
+- 2K resolution: ~$0.08/image
+- 4K resolution: ~$0.16/image
+
+## Model Routing
+
+| Scenario | Model | Why |
+|----------|-------|-----|
+| OG images, social previews | `gemini-3.1-flash-image-preview` @ 1K | Fast, cost-effective |
+| Hero images, product photos | `gemini-3.1-flash-image-preview` @ 2K | Quality + detail |
+| Infographics with text | `gemini-3.1-flash-image-preview` @ 2K, thinking: high | Better text rendering |
+| Quick drafts | `gemini-2.5-flash-image` @ 512 | Rapid iteration |
+
+## Error Handling
+
+| Error | Resolution |
+|-------|-----------|
+| MCP not configured | Run `./extensions/banana/install.sh` |
+| API key invalid | New key at https://aistudio.google.com/apikey |
+| Rate limited (429) | Wait 60s, retry. Free tier: ~10 RPM / ~500 RPD |
+| `IMAGE_SAFETY` | Rephrase prompt - see `references/prompt-engineering.md` Safety section |
+| MCP unavailable | Fall back: `python3 ~/.claude/skills/seo-image-gen/scripts/generate.py --prompt "..." --aspect-ratio "16:9"` |
+| Extension not installed | Show install instructions: `./extensions/banana/install.sh` |
+
+## Cross-Skill Integration
+
+- **seo-images** (analysis) feeds into **seo-image-gen** (generation): audit results from `/seo images` identify missing or low-quality images; use those findings to drive `/seo image-gen` commands
+- **seo-audit** spawns the seo-image-gen **agent** (not this skill) to analyze OG/social images across the site and produce a prioritized generation plan
+- **seo-schema** can consume generated images: after generation, suggest `ImageObject` schema markup pointing to the new assets
+
+## Reference Documentation
+
+Load on-demand. Do NOT load all at startup:
+- `references/prompt-engineering.md`:6-component system, domain modes, templates
+- `references/gemini-models.md`:Model specs, rate limits, capabilities
+- `references/mcp-tools.md`:MCP tool parameters and responses
+- `references/post-processing.md`:ImageMagick/FFmpeg pipeline recipes
+- `references/cost-tracking.md`:Pricing, usage tracking
+- `references/presets.md`:Brand preset management
+- `references/seo-image-presets.md`:SEO-specific preset templates
+
+## Response Format
+
+After generating, always provide:
+1. **Image path**:where it was saved
+2. **Crafted prompt**:show what was sent to the API (educational)
+3. **Settings**:model, aspect ratio, resolution
+4. **SEO checklist**:alt text suggestion, file naming, WebP conversion
+5. **Schema snippet**:ImageObject or og:image markup if applicable

package/bundled-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/bundled-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. |