codehava-agent-kit 1.0.1 → 3.0.0

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

@@ -0,0 +1,129 @@
+---
+name: seo-sitemap
+description: >
+  Analyze existing XML sitemaps or generate new ones with industry templates.
+  Validates format, URLs, and structure. Use when user says "sitemap",
+  "generate sitemap", "sitemap issues", or "XML sitemap".
+risk: unknown
+source: "https://github.com/AgriciDaniel/claude-seo"
+date_added: "2026-03-21"
+user-invokable: true
+argument-hint: "[url or generate]"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - WebFetch
+  - Write
+---
+
+# Sitemap Analysis & Generation
+
+## When to Use
+
+- Use when analyzing an existing XML sitemap or generating a new one.
+- Use when the user mentions sitemap issues, sitemap generation, or sitemap validation.
+- Use when checking URL coverage, sitemap limits, and sitemap quality rules.
+
+## Mode 1: Analyze Existing Sitemap
+
+### Validation Checks
+- Valid XML format
+- URL count <50,000 per file (protocol limit)
+- All URLs return HTTP 200
+- `<lastmod>` dates are accurate (not all identical)
+- No deprecated tags: `<priority>` and `<changefreq>` are ignored by Google
+- Sitemap referenced in robots.txt
+- Compare crawled pages vs sitemap; flag missing pages
+
+### Quality Signals
+- Sitemap index file if >50k URLs
+- Split by content type (pages, posts, images, videos)
+- No non-canonical URLs in sitemap
+- No noindexed URLs in sitemap
+- No redirected URLs in sitemap
+- HTTPS URLs only (no HTTP)
+
+### Common Issues
+| Issue | Severity | Fix |
+|-------|----------|-----|
+| >50k URLs in single file | Critical | Split with sitemap index |
+| Non-200 URLs | High | Remove or fix broken URLs |
+| Noindexed URLs included | High | Remove from sitemap |
+| Redirected URLs included | Medium | Update to final URLs |
+| All identical lastmod | Low | Use actual modification dates |
+| Priority/changefreq used | Info | Can remove (ignored by Google) |
+
+## Mode 2: Generate New Sitemap
+
+### Process
+1. Ask for business type (or auto-detect from existing site)
+2. Load industry template from `../seo-plan/assets/` directory
+3. Interactive structure planning with user
+4. Apply quality gates:
+   - ⚠️ WARNING at 30+ location pages (require 60%+ unique content)
+   - 🛑 HARD STOP at 50+ location pages (require justification)
+5. Generate valid XML output
+6. Split at 50k URLs with sitemap index
+7. Generate STRUCTURE.md documentation
+
+### Safe Programmatic Pages (OK at scale)
+✅ Integration pages (with real setup docs)
+✅ Template/tool pages (with downloadable content)
+✅ Glossary pages (200+ word definitions)
+✅ Product pages (unique specs, reviews)
+✅ User profile pages (user-generated content)
+
+### Penalty Risk (avoid at scale)
+❌ Location pages with only city name swapped
+❌ "Best [tool] for [industry]" without industry-specific value
+❌ "[Competitor] alternative" without real comparison data
+❌ AI-generated pages without human review and unique value
+
+## Sitemap Format
+
+### Standard Sitemap
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://example.com/page</loc>
+    <lastmod>2026-02-07</lastmod>
+  </url>
+</urlset>
+```
+
+### Sitemap Index (for >50k URLs)
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <sitemap>
+    <loc>https://example.com/sitemap-pages.xml</loc>
+    <lastmod>2026-02-07</lastmod>
+  </sitemap>
+  <sitemap>
+    <loc>https://example.com/sitemap-posts.xml</loc>
+    <lastmod>2026-02-07</lastmod>
+  </sitemap>
+</sitemapindex>
+```
+
+## Error Handling
+
+- **URL unreachable**: Report the HTTP status code and suggest checking if the site is live
+- **No sitemap found**: Check common locations (/sitemap.xml, /sitemap_index.xml, robots.txt reference) before reporting "not found"
+- **Invalid XML format**: Report specific parsing errors with line numbers
+- **Rate limiting detected**: Back off and report partial results with a note about retry timing
+
+## Output
+
+### For Analysis
+- `VALIDATION-REPORT.md`: analysis results
+- Issues list with severity
+- Recommendations
+
+### For Generation
+- `sitemap.xml` (or split files with index)
+- `STRUCTURE.md`: site architecture documentation
+- URL count and organization summary

package/templates/.agent/skills/seo-snippet-hunter/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: seo-snippet-hunter
+description: Formats content to be eligible for featured snippets and SERP features. Creates snippet-optimized content blocks based on best practices. Use PROACTIVELY for question-based content.
+risk: unknown
+source: community
+date_added: '2026-02-27'
+---
+
+## Use this skill when
+
+- Working on seo snippet hunter tasks or workflows
+- Needing guidance, best practices, or checklists for seo snippet hunter
+
+## Do not use this skill when
+
+- The task is unrelated to seo snippet hunter
+- 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 featured snippet optimization specialist formatting content for position zero potential.
+
+## Focus Areas
+
+- Featured snippet content formatting
+- Question-answer structure
+- Definition optimization
+- List and step formatting
+- Table structure for comparisons
+- Concise, direct answers
+- FAQ content optimization
+
+## Snippet Types & Formats
+
+**Paragraph Snippets (40-60 words):**
+- Direct answer in opening sentence
+- Question-based headers
+- Clear, concise definitions
+- No unnecessary words
+
+**List Snippets:**
+- Numbered steps (5-8 items)
+- Bullet points for features
+- Clear header before list
+- Concise descriptions
+
+**Table Snippets:**
+- Comparison data
+- Specifications
+- Structured information
+- Clean formatting
+
+## Snippet Optimization Strategy
+
+1. Format content for snippet eligibility
+2. Create multiple snippet formats
+3. Place answers near content beginning
+4. Use questions as headers
+5. Provide immediate, clear answers
+6. Include relevant context
+
+## Approach
+
+1. Identify questions in provided content
+2. Determine best snippet format
+3. Create snippet-optimized blocks
+4. Format answers concisely
+5. Structure surrounding context
+6. Suggest FAQ schema markup
+7. Create multiple answer variations
+
+## Output
+
+**Snippet Package:**
+```markdown
+## [Exact Question from SERP]
+
+[40-60 word direct answer paragraph with keyword in first sentence. Clear, definitive response that fully answers the query.]
+
+### Supporting Details:
+- Point 1 (enriching context)
+- Point 2 (related entity)
+- Point 3 (additional value)
+```
+
+**Deliverables:**
+- Snippet-optimized content blocks
+- PAA question/answer pairs
+- Competitor snippet analysis
+- Format recommendations (paragraph/list/table)
+- Schema markup (FAQPage, HowTo)
+- Position tracking targets
+- Content placement strategy
+
+**Advanced Tactics:**
+- Jump links for long content
+- FAQ sections for PAA dominance
+- Comparison tables for products
+- Step-by-step with images
+- Video timestamps for snippets
+- Voice search optimization
+
+**Platform Implementation:**
+- WordPress: FAQ block setup
+- Static sites: Structured content components
+- Schema.org markup templates
+
+Focus on clear, direct answers. Format content to maximize featured snippet eligibility.

package/templates/.agent/skills/seo-structure-architect/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: seo-structure-architect
+description: Analyzes and optimizes content structure including header hierarchy, suggests schema markup, and internal linking opportunities. Creates search-friendly content organization.
+risk: unknown
+source: community
+date_added: '2026-02-27'
+---
+
+## Use this skill when
+
+- Working on seo structure architect tasks or workflows
+- Needing guidance, best practices, or checklists for seo structure architect
+
+## Do not use this skill when
+
+- The task is unrelated to seo structure architect
+- 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 content structure specialist analyzing and improving information architecture.
+
+## Focus Areas
+
+- Header tag hierarchy (H1-H6) analysis
+- Content organization and flow
+- Schema markup suggestions
+- Internal linking opportunities
+- Table of contents structure
+- Content depth assessment
+- Logical information flow
+
+## Header Tag Best Practices
+
+**SEO Guidelines:**
+- One H1 per page matching main topic
+- H2s for main sections with variations
+- H3s for subsections with related terms
+- Maintain logical hierarchy
+- Natural keyword integration
+
+## Siloing Strategy
+
+1. Create topical theme clusters
+2. Establish parent/child relationships
+3. Build contextual internal links
+4. Maintain relevance within silos
+5. Cross-link only when highly relevant
+
+## Schema Markup Priority
+
+**High-Impact Schemas:**
+- Article/BlogPosting
+- FAQ Schema
+- HowTo Schema
+- Review/AggregateRating
+- Organization/LocalBusiness
+- BreadcrumbList
+
+## Approach
+
+1. Analyze provided content structure
+2. Evaluate header hierarchy
+3. Identify structural improvements
+4. Suggest internal linking opportunities
+5. Recommend appropriate schema types
+6. Assess content organization
+7. Format for featured snippet potential
+
+## Output
+
+**Structure Blueprint:**
+```
+H1: Primary Keyword Focus
+├── H2: Major Section (Secondary KW)
+│   ├── H3: Subsection (LSI)
+│   └── H3: Subsection (Entity)
+└── H2: Major Section (Related KW)
+```
+
+**Deliverables:**
+- Header hierarchy outline
+- Silo/cluster map visualization
+- Internal linking matrix
+- Schema markup JSON-LD code
+- Breadcrumb implementation
+- Table of contents structure
+- Jump link recommendations
+
+**Technical Implementation:**
+- WordPress: TOC plugin config + schema plugin setup
+- Astro/Static: Component hierarchy + structured data
+- URL structure recommendations
+- XML sitemap priorities
+
+**Snippet Optimization:**
+- List format for featured snippets
+- Table structure for comparisons
+- Definition boxes for terms
+- Step-by-step for processes
+
+Focus on logical flow and scannable content. Create clear information hierarchy for users and search engines.

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

@@ -0,0 +1,175 @@
+---
+name: seo-technical
+description: "Audit technical SEO across crawlability, indexability, security, URLs, mobile, Core Web Vitals, structured data, JavaScript rendering, and related platform signals like robots.txt and AI crawler access."
+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
+---
+
+# Technical SEO Audit
+
+## When to Use
+
+- Use when the user wants a technical SEO review focused on crawlability, indexability, performance, or rendering.
+- Use when auditing robots.txt, canonicalization, JavaScript SEO, Core Web Vitals, or AI crawler access.
+- Use when the task is infrastructure- and implementation-oriented rather than content-focused.
+
+## Categories
+
+### 1. Crawlability
+- robots.txt: exists, valid, not blocking important resources
+- XML sitemap: exists, referenced in robots.txt, valid format
+- Noindex tags: intentional vs accidental
+- Crawl depth: important pages within 3 clicks of homepage
+- JavaScript rendering: check if critical content requires JS execution
+- Crawl budget: for large sites (>10k pages), efficiency matters
+
+#### AI Crawler Management
+
+As of 2025-2026, AI companies actively crawl the web to train models and power AI search. Managing these crawlers via robots.txt is a critical technical SEO consideration.
+
+**Known AI crawlers:**
+
+| Crawler | Company | robots.txt token | Purpose |
+|---------|---------|-----------------|---------|
+| GPTBot | OpenAI | `GPTBot` | Model training |
+| ChatGPT-User | OpenAI | `ChatGPT-User` | Real-time browsing |
+| ClaudeBot | Anthropic | `ClaudeBot` | Model training |
+| PerplexityBot | Perplexity | `PerplexityBot` | Search index + training |
+| Bytespider | ByteDance | `Bytespider` | Model training |
+| Google-Extended | Google | `Google-Extended` | Gemini training (NOT search) |
+| CCBot | Common Crawl | `CCBot` | Open dataset |
+
+**Key distinctions:**
+- Blocking `Google-Extended` prevents Gemini training use but does NOT affect Google Search indexing or AI Overviews (those use `Googlebot`)
+- Blocking `GPTBot` prevents OpenAI training but does NOT prevent ChatGPT from citing your content via browsing (`ChatGPT-User`)
+- ~3-5% of websites now use AI-specific robots.txt rules
+
+**Example, selective AI crawler blocking:**
+```
+# Allow search indexing, block AI training crawlers
+User-agent: GPTBot
+Disallow: /
+
+User-agent: Google-Extended
+Disallow: /
+
+User-agent: Bytespider
+Disallow: /
+
+# Allow all other crawlers (including Googlebot for search)
+User-agent: *
+Allow: /
+```
+
+**Recommendation:** Consider your AI visibility strategy before blocking. Being cited by AI systems drives brand awareness and referral traffic. Cross-reference the `seo-geo` skill for full AI visibility optimization.
+
+### 2. Indexability
+- Canonical tags: self-referencing, no conflicts with noindex
+- Duplicate content: near-duplicates, parameter URLs, www vs non-www
+- Thin content: pages below minimum word counts per type
+- Pagination: rel=next/prev or load-more pattern
+- Hreflang: correct for multi-language/multi-region sites
+- Index bloat: unnecessary pages consuming crawl budget
+
+### 3. Security
+- HTTPS: enforced, valid SSL certificate, no mixed content
+- Security headers:
+  - Content-Security-Policy (CSP)
+  - Strict-Transport-Security (HSTS)
+  - X-Frame-Options
+  - X-Content-Type-Options
+  - Referrer-Policy
+- HSTS preload: check preload list inclusion for high-security sites
+
+### 4. URL Structure
+- Clean URLs: descriptive, hyphenated, no query parameters for content
+- Hierarchy: logical folder structure reflecting site architecture
+- Redirects: no chains (max 1 hop), 301 for permanent moves
+- URL length: flag >100 characters
+- Trailing slashes: consistent usage
+
+### 5. Mobile Optimization
+- Responsive design: viewport meta tag, responsive CSS
+- Touch targets: minimum 48x48px with 8px spacing
+- Font size: minimum 16px base
+- No horizontal scroll
+- Mobile-first indexing: Google indexes mobile version. **Mobile-first indexing is 100% complete as of July 5, 2024.** Google now crawls and indexes ALL websites exclusively with the mobile Googlebot user-agent.
+
+### 6. Core Web Vitals
+- **LCP** (Largest Contentful Paint): target <2.5s
+- **INP** (Interaction to Next Paint): target <200ms
+  - INP replaced FID on March 12, 2024. FID was fully removed from all Chrome tools (CrUX API, PageSpeed Insights, Lighthouse) on September 9, 2024. Do NOT reference FID anywhere.
+- **CLS** (Cumulative Layout Shift): target <0.1
+- Evaluation uses 75th percentile of real user data
+- Use PageSpeed Insights API or CrUX data if MCP available
+
+### 7. Structured Data
+- Detection: JSON-LD (preferred), Microdata, RDFa
+- Validation against Google's supported types
+- See seo-schema skill for full analysis
+
+### 8. JavaScript Rendering
+- Check if content visible in initial HTML vs requires JS
+- Identify client-side rendered (CSR) vs server-side rendered (SSR)
+- Flag SPA frameworks (React, Vue, Angular) that may cause indexing issues
+- Verify dynamic rendering setup if applicable
+
+#### JavaScript SEO: Canonical & Indexing Guidance (December 2025)
+
+Google updated its JavaScript SEO documentation in December 2025 with critical clarifications:
+
+1. **Canonical conflicts:** If a canonical tag in raw HTML differs from one injected by JavaScript, Google may use EITHER one. Ensure canonical tags are identical between server-rendered HTML and JS-rendered output.
+2. **noindex with JavaScript:** If raw HTML contains `<meta name="robots" content="noindex">` but JavaScript removes it, Google MAY still honor the noindex from raw HTML. Serve correct robots directives in the initial HTML response.
+3. **Non-200 status codes:** Google does NOT render JavaScript on pages returning non-200 HTTP status codes. Any content or meta tags injected via JS on error pages will be invisible to Googlebot.
+4. **Structured data in JavaScript:** Product, Article, and other structured data injected via JS may face delayed processing. For time-sensitive structured data (especially e-commerce Product markup), include it in the initial server-rendered HTML.
+
+**Best practice:** Serve critical SEO elements (canonical, meta robots, structured data, title, meta description) in the initial server-rendered HTML rather than relying on JavaScript injection.
+
+### 9. IndexNow Protocol
+- Check if site supports IndexNow for Bing, Yandex, Naver
+- Supported by search engines other than Google
+- Recommend implementation for faster indexing on non-Google engines
+
+## Output
+
+### Technical Score: XX/100
+
+### Category Breakdown
+| Category | Status | Score |
+|----------|--------|-------|
+| Crawlability | pass/warn/fail | XX/100 |
+| Indexability | pass/warn/fail | XX/100 |
+| Security | pass/warn/fail | XX/100 |
+| URL Structure | pass/warn/fail | XX/100 |
+| Mobile | pass/warn/fail | XX/100 |
+| Core Web Vitals | pass/warn/fail | XX/100 |
+| Structured Data | pass/warn/fail | XX/100 |
+| JS Rendering | pass/warn/fail | XX/100 |
+| IndexNow | pass/warn/fail | XX/100 |
+
+### Critical Issues (fix immediately)
+### High Priority (fix within 1 week)
+### Medium Priority (fix within 1 month)
+### Low Priority (backlog)
+
+## DataForSEO Integration (Optional)
+
+If DataForSEO MCP tools are available, use `on_page_instant_pages` for real page analysis (status codes, page timing, broken links, on-page checks), `on_page_lighthouse` for Lighthouse audits (performance, accessibility, SEO scores), and `domain_analytics_technologies_domain_technologies` for technology stack detection.
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| URL unreachable | Report connection error with status code. Suggest verifying URL, checking DNS resolution, and confirming the site is publicly accessible. |
+| robots.txt not found | Note that no robots.txt was detected at the root domain. Recommend creating one with appropriate directives. Continue audit on remaining categories. |
+| HTTPS not configured | Flag as a critical issue. Report whether HTTP is served without redirect, mixed content exists, or SSL certificate is missing/expired. |
+| Core Web Vitals data unavailable | Note that CrUX data is not available (common for low-traffic sites). Suggest using Lighthouse lab data as a proxy and recommend increasing traffic before re-testing. |