Skip to main content
skill CX Codex

seo · tech-leads-club — Claude Code skill: what it does, how to install

Walks Claude through technical and on-page SEO: crawl rules, canonicals, sitemaps, meta tags, JSON-LD. Useful when pages don't get indexed or snippets look broken.

MIT ★ 7,191 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add tech-leads-club/agent-skills --skill seo -a claude-code
Open on GitHub

What seo does

The seo skill gives Claude a working checklist for technical and on-page SEO, built on Lighthouse SEO audits and Google Search guidance. It covers crawl rules in robots.txt, meta robots, canonical links, sitemap.xml, URL shape, HTTPS, title and heading markup, image alt text, internal links and JSON-LD structured data.

All of it ships as one SKILL.md file: a ranking-factor table that marks what the skill handles, templates for robots.txt and a sitemap, plus HTML snippets for canonicals, robots meta and images. Link authority sits outside its scope — the table crosses it out. Accessibility and page speed belong to web-accessibility and core-web-vitals, so a request that mixes them in gets pointed elsewhere instead of answered.

Install it with npx skills add tech-leads-club/agent-skills --skill seo -a claude-code; the file lands at ~/.claude/skills/seo/SKILL.md. MIT licensed.

What it helps with

  • write a robots.txt that blocks admin and API paths
  • stop duplicate pages with canonical links
  • split a large sitemap.xml into an index
  • fit title tags and meta descriptions to snippet length
  • add Organization and Article JSON-LD

Example prompts for the agent

  • Audit the crawl setup: check robots.txt, canonical tags and sitemap.xml across the site.
  • Add Organization JSON-LD to the homepage and validate it.
  • Rewrite the duplicate title tags and meta descriptions on product pages.

How to install seo

1Skills CLI (Vercel)

npx skills add tech-leads-club/agent-skills --skill seo -a claude-code

2Manually: put the files in place

~/.claude/skills/seo/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/seo/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about seo

How to install seo in Claude Code?

Run npx skills add tech-leads-club/agent-skills --skill seo -a claude-code. The skill file ends up at ~/.claude/skills/seo/SKILL.md.

What does the seo skill do?

It steers the agent through technical and on-page SEO: crawling and indexing, canonicals, sitemaps, meta tags, headings, images, internal links and JSON-LD.

How is seo different from web-accessibility and core-web-vitals?

They are separate skills in the same catalog. seo handles search visibility, web-accessibility handles accessibility, and core-web-vitals covers page speed and page experience.

Source text

SKILL.md · MIT
---
name: seo
description: Optimize for search engine visibility and ranking. Use when asked to "improve SEO", "optimize for search", "fix meta tags", "add structured data", "sitemap optimization", or "search engine optimization". Do NOT use for accessibility (use web-accessibility), performance (use core-web-vitals), or comprehensive site audits covering multiple areas (use web-quality-audit).
license: MIT
metadata:
  author: web-quality-skills
  version: '1.0'
---

# SEO optimization

Search engine optimization based on Lighthouse SEO audits and Google Search guidelines. Focus on technical SEO, on-page optimization, and structured data.

## SEO fundamentals

Search ranking factors (approximate influence):

| Factor                            | Influence | This Skill                                         |
| --------------------------------- | --------- | -------------------------------------------------- |
| Content quality & relevance       | ~40%      | Partial (structure)                                |
| Backlinks & authority             | ~25%      | ✗                                                  |
| Technical SEO                     | ~15%      | ✓                                                  |
| Page experience (Core Web Vitals) | ~10%      | See [Core Web Vitals](../core-web-vitals/SKILL.md) |
| On-page SEO                       | ~10%      | ✓                                                  |

---

## Technical SEO

### Crawlability

**robots.txt:**

```text
# /robots.txt
User-agent: *
Allow: /

# Block admin/private areas
Disallow: /admin/
Disallow: /api/
Disallow: /private/

# Don't block resources needed for rendering
# ❌ Disallow: /static/

Sitemap: https://example.com/sitemap.xml
```

**Meta robots:**

```html
<!-- Default: indexable, followable -->
<meta name="robots" content="index, follow" />

<!-- Noindex specific pages -->
<meta name="robots" content="noindex, nofollow" />

<!-- Indexable but don't follow links -->
<meta name="robots" content="index, nofollow" />

<!-- Control snippets -->
<meta name="robots" content="max-snippet:150, max-image-preview:large" />
```

**Canonical URLs:**

```html
<!-- Prevent duplicate content issues -->
<link rel="canonical" href="https://example.com/page" />

<!-- Self-referencing canonical (recommended) -->
<link rel="canonical" href="https://example.com/current-page" />

<!-- For paginated content -->
<link rel="canonical" href="https://example.com/products" />
<!-- Or use rel="prev" / rel="next" for explicit pagination -->
```

### XML sitemap

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
    <lastmod>2024-01-15</lastmod>
    <changefreq>daily</changefreq>
    <priority>1.0</priority>
  </url>
  <url>
    <loc>https://example.com/products</loc>
    <lastmod>2024-01-14</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
  </url>
</urlset>
```

**Sitemap best practices:**

- Maximum 50,000 URLs or 50MB per sitemap
- Use sitemap index for larger sites
- Include only canonical, indexable URLs
- Update `lastmod` when content changes
- Submit to Google Search Console

### URL structure

```
✅ Good URLs:
https://example.com/products/blue-widget
https://example.com/blog/how-to-use-widgets

❌ Poor URLs:
https://example.com/p?id=12345
https://example.com/products/item/category/subcategory/blue-widget-2024-sale-discount
```

**URL guidelines:**

- Use hyphens, not underscores
- Lowercase only
- Keep short (< 75 characters)
- Include target keywords naturally
- Avoid parameters when possible
- Use HTTPS always

### HTTPS & security

```html
<!-- Ensure all resources use HTTPS -->
<img src="https://example.com/image.jpg" />

<!-- Not: -->
<img src="http://example.com/image.jpg" />
```

**Security headers for SEO trust signals:**

```
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
```

---

## On-page SEO

### Title tags

```html
<!-- ❌ Missing or generic -->
<title>Page</title>
<title>Home</title>

<!-- ✅ Descriptive with primary keyword -->
<title>Blue Widgets for Sale | Premium Quality | Example Store</title>
```

**Title tag guidelines:**

- 50-60 characters (Google truncates ~60)
- Primary keyword near the beginning
- Unique for every page
- Brand name at end (unless homepage)
- Action-oriented when appropriate

### Meta descriptions

```html
<!-- ❌ Missing or duplicate -->
<meta name="description" content="" />

<!-- ✅ Compelling and unique -->
<meta
  name="description"
  content="Shop premium blue widgets with free shipping. 30-day returns. Rated 4.9/5 by 10,000+ customers. Order today and save 20%."
/>
```

**Meta description guidelines:**

- 150-160 characters
- Include primary keyword naturally
- Compelling call-to-action
- Unique for every page
- Matches page content

### Heading structure

```html
<!-- ❌ Poor structure -->
<h2>Welcome to Our Store</h2>
<h4>Products</h4>
<h1>Contact Us</h1>

<!-- ✅ Proper hierarchy -->
<h1>Blue Widgets - Premium Quality</h1>
<h2>Product Features</h2>
<h3>Durability</h3>
<h3>Design</h3>
<h2>Customer Reviews</h2>
<h2>Pricing</h2>
```

**Heading guidelines:**

- Single `<h1>` per page (the main topic)
- Logical hierarchy (don't skip levels)
- Include keywords naturally
- Descriptive, not generic

### Image SEO

```html
<!-- ❌ Poor image SEO -->
<img src="IMG_12345.jpg" />

<!-- ✅ Optimized image -->
<img
  src="blue-widget-product-photo.webp"
  alt="Blue widget with chrome finish, side view showing control panel"
  width="800"
  height="600"
  loading="lazy"
/>
```

**Image guidelines:**

- Descriptive filenames with keywords
- Alt text describes the image content
- Compressed and properly sized
- WebP/AVIF with fallbacks
- Lazy load below-fold images

### Internal linking

```html
<!-- ❌ Non-descriptive -->
<a href="/products">Click here</a>
<a href="/widgets">Read more</a>

<!-- ✅ Descriptive anchor text -->
<a href="/products/blue-widgets">Browse our blue widget collection</a>
<a href="/guides/widget-maintenance">Learn how to maintain your widgets</a>
```

**Linking guidelines:**

- Descriptive anchor text with keywords
- Link to relevant internal pages
- Reasonable number of links per page
- Fix broken links promptly
- Use breadcrumbs for hierarchy

---

## Structured data (JSON-LD)

### Organization

```html
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Organization",
    "name": "Example Company",
    "url": "https://example.com",
    "logo": "https://example.com/logo.png",
    "sameAs": ["https://twitter.com/example", "https://linkedin.com/company/example"],
    "contactPoint": {
      "@type": "ContactPoint",
      "telephone": "+1-555-123-4567",
      "contactType": "customer service"
    }
  }
</script>
```

### Article

```html
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "How to Choose the Right Widget",
    "description": "Complete guide to selecting widgets for your needs.",
    "image": "https://example.com/article-image.jpg",
    "author": {
      "@type": "Person",
      "name": "Jane Smith",
      "url": "https://example.com/authors/jane-smith"
    },
    "publisher": {
      "@type": "Organization",
      "name": "Example Blog",
      "logo": {
        "@type": "ImageObject",
        "url": "https://example.com/logo.png"
      }
    },
    "datePublished": "2024-01-15",
    "dateModified": "2024-01-20"
  }
</script>
```

### Product

```html
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Product",
    "name": "Blue Widget Pro",
    "image": "https://example.com/blue-widget.jpg",
    "description": "Premium blue widget with advanced features.",
    "brand": {
      "@type": "Brand",
      "name": "WidgetCo"
    },
    "offers": {
      "@type": "Offer",
      "price": "49.99",
      "priceCurrency": "USD",
      "availability": "https://schema.org/InStock",
      "url": "https://example.com/products/blue-widget"
    },
    "aggregateRating": {
      "@type": "AggregateRating",
      "ratingValue": "4.8",
      "reviewCount": "1250"
    }
  }
</script>
```

### FAQ

```html
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "What colors are available?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Our widgets come in blue, red, and green."
        }
      },
      {
        "@type": "Question",
        "name": "What is the warranty?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "All widgets include a 2-year warranty."
        }
      }
    ]
  }
</script>
```

### Breadcrumbs

```html
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    "itemListElement": [
      {
        "@type": "ListItem",
        "position": 1,
        "name": "Home",
        "item": "https://example.com"
      },
      {
        "@type": "ListItem",
        "position": 2,
        "name": "Products",
        "item": "https://example.com/products"
      },
      {
        "@type": "ListItem",
        "position": 3,
        "name": "Blue Widgets",
        "item": "https://example.com/products/blue-widgets"
      }
    ]
  }
</script>
```

### Validation

Test structured data at:

- [Google Rich Results Test](https://search.google.com/test/rich-results)
- [Schema.org Validator](https://validator.schema.org/)

---

## Mobile SEO

### Responsive design

```html
<!-- ❌ Not mobile-friendly -->
<meta name="viewport" content="width=1024" />

<!-- ✅ Responsive viewport -->
<meta name="viewport" content="width=device-width, initial-scale=1" />
```

### Tap targets

```css
/* ❌ Too small for mobile */
.small-link {
  padding: 4px;
  font-size: 12px;
}

/* ✅ Adequate tap target */
.mobile-friendly-link {
  padding: 12px;
  font-size: 16px;
  min-height: 48px;
  min-width: 48px;
}
```

### Font sizes

```css
/* ❌ Too small on mobile */
body {
  font-size: 10px;
}

/* ✅ Readable without zooming */
body {
  font-size: 16px;
  line-height: 1.5;
}
```

---

## International SEO

### Hreflang tags

```html
<!-- For multi-language sites -->
<link rel="alternate" hreflang="en" href="https://example.com/page" />
<link rel="alternate" hreflang="es" href="https://example.com/es/page" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page" />
```

### Language declaration

```html
<html lang="en">
  <!-- or -->
  <html lang="es-MX"></html>
</html>
```

---

## SEO audit checklist

### Critical

- [ ] HTTPS enabled
- [ ] robots.txt allows crawling
- [ ] No `noindex` on important pages
- [ ] Title tags present and unique
- [ ] Single `<h1>` per page

### High priority

- [ ] Meta descriptions present
- [ ] Sitemap submitted
- [ ] Canonical URLs set
- [ ] Mobile-responsive
- [ ] Core Web Vitals passing

### Medium priority

- [ ] Structured data implemented
- [ ] Internal linking strategy
- [ ] Image alt text
- [ ] Descriptive URLs
- [ ] Breadcrumb navigation

### Ongoing

- [ ] Fix crawl errors in Search Console
- [ ] Update sitemap when content changes
- [ ] Monitor ranking changes
- [ ] Check for broken links
- [ ] Review Search Console insights

---

## Tools

| Tool                      | Use                           |
| ------------------------- | ----------------------------- |
| Google Search Console     | Monitor indexing, fix issues  |
| Google PageSpeed Insights | Performance + Core Web Vitals |
| Rich Results Test         | Validate structured data      |
| Lighthouse                | Full SEO audit                |
| Screaming Frog            | Crawl analysis                |

## References

- [Google Search Central](https://developers.google.com/search)
- [Schema.org](https://schema.org/)
- [Core Web Vitals](../core-web-vitals/SKILL.md)
- [Web Quality Audit](../web-quality-audit/SKILL.md)

© web-quality-skills · MIT · tech-leads-club/agent-skills

Similar skills

All skills for SEO and GEO →

seo by other authors comes first.

seo affaan-m Walks your coding agent through technical SEO, on-page fixes, structured data and Core Web Vitals, with page-level recommendations. CX Codex +1 6,900installs seo AgriciDaniel seo runs site audits, technical checks, Schema.org validation, and Generative Engine Optimization. Suitable for SaaS, e-commerce, and local business audits. CX Codex +1 10,500installs seo iannuttall seo is a Claude Code skill that connects live Search Console, web analytics, and site audit data to your coding agent. Runs on traffic diagnostics, crawl reviews, and indexing checks. CX Codex +1 34,500installs seo mblode This skill audits technical SEO, researches search demand, and tracks visibility in search and AI answers. Use it to diagnose indexing, plan a fix, or prepare a content brief. CX Codex +1 391installs seo a5c-ai seo configures meta tags and sitemaps directly in project files. Useful when preparing web applications for search indexing. CX Codex +1 3installs nextjs-seo laguagu The nextjs-seo Claude Code skill handles SEO implementation and audits for Next.js App Router. It covers metadata, indexing issues, structured data and crawler rules. CX Codex +1 2,600installs seo-local-business jezweb seo-local-business — a skill for Claude Code, Cursor, Codex and other platforms that builds a full SEO package for local business websites — <head> tags, JSON-LD LocalBusiness schema, robots.txt, and sitemap.xml. CX Codex +1 1,900installs seo-optimizer ailabs-393 The seo-optimizer skill scans HTML/CSS pages for SEO faults, then fixes meta tags, structured data and the sitemap. Handy when a site exists but search engines barely notice it. CX Codex +1 1,300installs seo-schema AgriciDaniel seo-schema — a skill for Claude Code and Codex that detects, validates, and generates Schema.org JSON-LD. It audits live pages or creates structured data from scratch. CX Codex +1 8,200installs blog-seo-check AgriciDaniel blog-seo-check audits one finished post against an on-page SEO checklist and returns prioritized fixes. Use it before publishing. CX Codex +1 2,800installs seo-best-practices Mindrally seo-best-practices provides search optimization guidelines for web apps. Helps configure metadata, JSON-LD schemas, rendering modes, and Core Web Vitals. CX Codex +1 906installs

From the same set130

The whole set →
mermaid-studio mermaid-studio — a skill that builds Mermaid diagrams, validates syntax and renders to SVG, PNG or ASCII. Useful when you need to document architecture or a database schema. CX Codex +1 344installs perf-lighthouse perf-lighthouse runs local Lighthouse audits via CLI or Node API, parses reports, and configures performance budgets. Useful for tracking Core Web Vitals and integrating speed checks into CI. CX Codex +1 341installs codenavi codenavi guides the AI through unfamiliar codebases, plans surgical edits, and stores project discoveries in .notebook/. Useful for debugging and refactoring without guesswork. CX Codex +1 327installs decomposition-planning-roadmap decomposition-planning-roadmap is a Claude Code skill that maps out monolith decomposition and migration. It activates for service extraction planning, work prioritization, and progress tracking. CX Codex +1 322installs best-practices best-practices is a Claude Code skill for checking web code security, browser compatibility, and code quality. It runs on requests for a security review or code modernization. CX Codex +1 ★ 7,191repo stars js-index-maps The js-index-maps rule replaces repeated .find() calls on one key with a Map index. Use it when array lookups happen many times. CX Codex +1 ★ 7,191repo stars rendering-hydration-suppress-warning rendering-hydration-suppress-warning silences hydration warnings where the two renders are meant to differ: timestamps, per-render IDs, dates formatted for the visitor's locale. CX Codex +1 ★ 7,191repo stars bundle-defer-third-party bundle-defer-third-party prevents third-party trackers from inflating the initial bundle. It instructs the assistant to load analytics and monitoring after hydration. CX Codex +1 ★ 7,191repo stars

Project sponsors

Companies that keep this analytics open