---
name: senior-frontend
description: Frontend development skill for React, Next.js, TypeScript, and Tailwind CSS applications. Use when building React components, optimizing Next.js performance, analyzing bundle sizes, scaffolding frontend projects, implementing accessibility, or reviewing frontend code quality.
risk: safe
source: https://github.com/alirezarezvani/claude-skills
date_added: "2026-03-07"
---

# Senior Frontend

Frontend development patterns, performance optimization, and automation tools for React/Next.js applications.

## When to Use
- Use when scaffolding a new React or Next.js project with TypeScript and Tailwind CSS.
- Use when generating new components or custom hooks.
- Use when analyzing and optimizing bundle sizes for frontend applications.
- Use to implement or review advanced React patterns like Compound Components or Render Props.
- Use to ensure accessibility compliance and implement robust testing strategies.

## Table of Contents

- [Project Scaffolding](#project-scaffolding)
- [Component Generation](#component-generation)
- [Bundle Analysis](#bundle-analysis)
- [React Patterns](#react-patterns)
- [Next.js Optimization](#nextjs-optimization)
- [Accessibility and Testing](#accessibility-and-testing)

---

## Project Scaffolding

Generate a new Next.js or React project with TypeScript, Tailwind CSS, and best practice configurations.

### Workflow: Create New Frontend Project

1. Run the scaffolder with your project name and template:

   ```bash
   python scripts/frontend_scaffolder.py my-app --template nextjs
   ```

2. Add optional features (auth, api, forms, testing, storybook):

   ```bash
   python scripts/frontend_scaffolder.py dashboard --template nextjs --features auth,api
   ```

3. Navigate to the project and install dependencies:

   ```bash
   cd my-app && npm install
   ```

4. Start the development server:
   ```bash
   npm run dev
   ```

### Scaffolder Options

| Option               | Description                                       |
| -------------------- | ------------------------------------------------- |
| `--template nextjs`  | Next.js 14+ with App Router and Server Components |
| `--template react`   | React + Vite with TypeScript                      |
| `--features auth`    | Add NextAuth.js authentication                    |
| `--features api`     | Add React Query + API client                      |
| `--features forms`   | Add React Hook Form + Zod validation              |
| `--features testing` | Add Vitest + Testing Library                      |
| `--dry-run`          | Preview files without creating them               |

### Generated Structure (Next.js)

```
my-app/
├── app/
│   ├── layout.tsx        # Root layout with fonts
│   ├── page.tsx          # Home page
│   ├── globals.css       # Tailwind + CSS variables
│   └── api/health/route.ts
├── components/
│   ├── ui/               # Button, Input, Card
│   └── layout/           # Header, Footer, Sidebar
├── hooks/                # useDebounce, useLocalStorage
├── lib/                  # utils (cn), constants
├── types/                # TypeScript interfaces
├── tailwind.config.ts
├── next.config.js
└── package.json
```

---

## Component Generation

Generate React components with TypeScript, tests, and Storybook stories.

### Workflow: Create a New Component

1. Generate a client component:

   ```bash
   python scripts/component_generator.py Button --dir src/components/ui
   ```

2. Generate a server component:

   ```bash
   python scripts/component_generator.py ProductCard --type server
   ```

3. Generate with test and story files:

   ```bash
   python scripts/component_generator.py UserProfile --with-test --with-story
   ```

4. Generate a custom hook:
   ```bash
   python scripts/component_generator.py FormValidation --type hook
   ```

### Generator Options

| Option          | Description                                  |
| --------------- | -------------------------------------------- |
| `--type client` | Client component with 'use client' (default) |
| `--type server` | Async server component                       |
| `--type hook`   | Custom React hook                            |
| `--with-test`   | Include test file                            |
| `--with-story`  | Include Storybook story                      |
| `--flat`        | Create in output dir without subdirectory    |
| `--dry-run`     | Preview without creating files               |

### Generated Component Example

```tsx
"use client";

import { useState } from "react";
import { cn } from "@/lib/utils";

interface ButtonProps {
  className?: string;
  children?: React.ReactNode;
}

export function Button({ className, children }: ButtonProps) {
  return <div className={cn("", className)}>{children}</div>;
}
```

---

## Bundle Analysis

Analyze package.json and project structure for bundle optimization opportunities.

### Workflow: Optimize Bundle Size

1. Run the analyzer on your project:

   ```bash
   python scripts/bundle_analyzer.py /path/to/project
   ```

2. Review the health score and issues:

   ```
   Bundle Health Score: 75/100 (C)

   HEAVY DEPENDENCIES:
     moment (290KB)
       Alternative: date-fns (12KB) or dayjs (2KB)

     lodash (71KB)
       Alternative: lodash-es with tree-shaking
   ```

3. Apply the recommended fixes by replacing heavy dependencies.

4. Re-run with verbose mode to check import patterns:
   ```bash
   python scripts/bundle_analyzer.py . --verbose
   ```

### Bundle Score Interpretation

| Score  | Grade | Action                         |
| ------ | ----- | ------------------------------ |
| 90-100 | A     | Bundle is well-optimized       |
| 80-89  | B     | Minor optimizations available  |
| 70-79  | C     | Replace heavy dependencies     |
| 60-69  | D     | Multiple issues need attention |
| 0-59   | F     | Critical bundle size problems  |

### Heavy Dependencies Detected

The analyzer identifies these common heavy packages:

| Package       | Size  | Alternative                    |
| ------------- | ----- | ------------------------------ |
| moment        | 290KB | date-fns (12KB) or dayjs (2KB) |
| lodash        | 71KB  | lodash-es with tree-shaking    |
| axios         | 14KB  | Native fetch or ky (3KB)       |
| jquery        | 87KB  | Native DOM APIs                |
| @mui/material | Large | shadcn/ui or Radix UI          |

---

## React Patterns

Reference: `references/react_patterns.md`

### Compound Components

Share state between related components:

```tsx
const Tabs = ({ children }) => {
  const [active, setActive] = useState(0);
  return (
    <TabsContext.Provider value={{ active, setActive }}>
      {children}
    </TabsContext.Provider>
  );
};

Tabs.List = TabList;
Tabs.Panel = TabPanel;

// Usage
<Tabs>
  <Tabs.List>
    <Tabs.Tab>One</Tabs.Tab>
    <Tabs.Tab>Two</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel>Content 1</Tabs.Panel>
  <Tabs.Panel>Content 2</Tabs.Panel>
</Tabs>;
```

### Custom Hooks

Extract reusable logic:

```tsx
function useDebounce<T>(value: T, delay = 500): T {
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(() => {
    const timer = setTimeout(() => setDebouncedValue(value), delay);
    return () => clearTimeout(timer);
  }, [value, delay]);

  return debouncedValue;
}

// Usage
const debouncedSearch = useDebounce(searchTerm, 300);
```

### Render Props

Share rendering logic:

```tsx
function DataFetcher({ url, render }) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch(url)
      .then((r) => r.json())
      .then(setData)
      .finally(() => setLoading(false));
  }, [url]);

  return render({ data, loading });
}

// Usage
<DataFetcher
  url="/api/users"
  render={({ data, loading }) =>
    loading ? <Spinner /> : <UserList users={data} />
  }
/>;
```

---

## Next.js Optimization

Reference: `references/nextjs_optimization_guide.md`

### Server vs Client Components

Use Server Components by default. Add 'use client' only when you need:

- Event handlers (onClick, onChange)
- State (useState, useReducer)
- Effects (useEffect)
- Browser APIs

```tsx
// Server Component (default) - no 'use client'
async function ProductPage({ params }) {
  const product = await getProduct(params.id); // Server-side fetch

  return (
    <div>
      <h1>{product.name}</h1>
      <AddToCartButton productId={product.id} /> {/* Client component */}
    </div>
  );
}

// Client Component
("use client");
function AddToCartButton({ productId }) {
  const [adding, setAdding] = useState(false);
  return <button onClick={() => addToCart(productId)}>Add</button>;
}
```

### Image Optimization

```tsx
import Image from 'next/image';

// Above the fold - load immediately
<Image
  src="/hero.jpg"
  alt="Hero"
  width={1200}
  height={600}
  priority
/>

// Responsive image with fill
<div className="relative aspect-video">
  <Image
    src="/product.jpg"
    alt="Product"
    fill
    sizes="(max-width: 768px) 100vw, 50vw"
    className="object-cover"
  />
</div>
```

### Data Fetching Patterns

```tsx
// Parallel fetching
async function Dashboard() {
  const [user, stats] = await Promise.all([getUser(), getStats()]);
  return <div>...</div>;
}

// Streaming with Suspense
async function ProductPage({ params }) {
  return (
    <div>
      <ProductDetails id={params.id} />
      <Suspense fallback={<ReviewsSkeleton />}>
        <Reviews productId={params.id} />
      </Suspense>
    </div>
  );
}
```

---

## Accessibility and Testing

Reference: `references/frontend_best_practices.md`

### Accessibility Checklist

1. **Semantic HTML**: Use proper elements (`<button>`, `<nav>`, `<main>`)
2. **Keyboard Navigation**: All interactive elements focusable
3. **ARIA Labels**: Provide labels for icons and complex widgets
4. **Color Contrast**: Minimum 4.5:1 for normal text
5. **Focus Indicators**: Visible focus states

```tsx
// Accessible button
<button
  type="button"
  aria-label="Close dialog"
  onClick={onClose}
  className="focus-visible:ring-2 focus-visible:ring-blue-500"
>
  <XIcon aria-hidden="true" />
</button>

// Skip link for keyboard users
<a href="#main-content" className="sr-only focus:not-sr-only">
  Skip to main content
</a>
```

### Testing Strategy

```tsx
// Component test with React Testing Library
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

test("button triggers action on click", async () => {
  const onClick = vi.fn();
  render(<Button onClick={onClick}>Click me</Button>);

  await userEvent.click(screen.getByRole("button"));
  expect(onClick).toHaveBeenCalledTimes(1);
});

// Test accessibility
test("dialog is accessible", async () => {
  render(<Dialog open={true} title="Confirm" />);

  expect(screen.getByRole("dialog")).toBeInTheDocument();
  expect(screen.getByRole("dialog")).toHaveAttribute("aria-labelledby");
});
```

---

## Quick Reference

### Common Next.js Config

```js
// next.config.js
const nextConfig = {
  images: {
    remotePatterns: [{ hostname: "cdn.example.com" }],
    formats: ["image/avif", "image/webp"],
  },
  experimental: {
    optimizePackageImports: ["lucide-react", "@heroicons/react"],
  },
};
```

### Tailwind CSS Utilities

```tsx
// Conditional classes with cn()
import { cn } from "@/lib/utils";

<button
  className={cn(
    "px-4 py-2 rounded",
    variant === "primary" && "bg-blue-500 text-white",
    disabled && "opacity-50 cursor-not-allowed",
  )}
/>;
```

### TypeScript Patterns

```tsx
// Props with children
interface CardProps {
  className?: string;
  children: React.ReactNode;
}

// Generic component
interface ListProps<T> {
  items: T[];
  renderItem: (item: T) => React.ReactNode;
}

function List<T>({ items, renderItem }: ListProps<T>) {
  return <ul>{items.map(renderItem)}</ul>;
}
```

---

## Resources

- React Patterns: `references/react_patterns.md`
- Next.js Optimization: `references/nextjs_optimization_guide.md`
- Best Practices: `references/frontend_best_practices.md`

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: senior-fullstack
description: "Complete toolkit for senior fullstack with modern tools and best practices."
risk: critical
source: community
date_added: "2026-02-27"
---

# Senior Fullstack

Complete toolkit for senior fullstack with modern tools and best practices.

## Quick Start

### Main Capabilities

This skill provides three core capabilities through automated scripts:

```bash
# Script 1: Fullstack Scaffolder
python scripts/fullstack_scaffolder.py [options]

# Script 2: Project Scaffolder
python scripts/project_scaffolder.py [options]

# Script 3: Code Quality Analyzer
python scripts/code_quality_analyzer.py [options]
```

## Core Capabilities

### 1. Fullstack Scaffolder

Automated tool for fullstack scaffolder tasks.

**Features:**
- Automated scaffolding
- Best practices built-in
- Configurable templates
- Quality checks

**Usage:**
```bash
python scripts/fullstack_scaffolder.py <project-path> [options]
```

### 2. Project Scaffolder

Comprehensive analysis and optimization tool.

**Features:**
- Deep analysis
- Performance metrics
- Recommendations
- Automated fixes

**Usage:**
```bash
python scripts/project_scaffolder.py <target-path> [--verbose]
```

### 3. Code Quality Analyzer

Advanced tooling for specialized tasks.

**Features:**
- Expert-level automation
- Custom configurations
- Integration ready
- Production-grade output

**Usage:**
```bash
python scripts/code_quality_analyzer.py [arguments] [options]
```

## Reference Documentation

### Tech Stack Guide

Comprehensive guide available in `references/tech_stack_guide.md`:

- Detailed patterns and practices
- Code examples
- Best practices
- Anti-patterns to avoid
- Real-world scenarios

### Architecture Patterns

Complete workflow documentation in `references/architecture_patterns.md`:

- Step-by-step processes
- Optimization strategies
- Tool integrations
- Performance tuning
- Troubleshooting guide

### Development Workflows

Technical reference guide in `references/development_workflows.md`:

- Technology stack details
- Configuration examples
- Integration patterns
- Security considerations
- Scalability guidelines

## Tech Stack

**Languages:** TypeScript, JavaScript, Python, Go, Swift, Kotlin
**Frontend:** React, Next.js, React Native, Flutter
**Backend:** Node.js, Express, GraphQL, REST APIs
**Database:** PostgreSQL, Prisma, NeonDB, Supabase
**DevOps:** Docker, Kubernetes, Terraform, GitHub Actions, CircleCI
**Cloud:** AWS, GCP, Azure

## Development Workflow

### 1. Setup and Configuration

```bash
# Install dependencies
npm install
# or
pip install -r requirements.txt

# Configure environment
cp .env.example .env
```

### 2. Run Quality Checks

```bash
# Use the analyzer script
python scripts/project_scaffolder.py .

# Review recommendations
# Apply fixes
```

### 3. Implement Best Practices

Follow the patterns and practices documented in:
- `references/tech_stack_guide.md`
- `references/architecture_patterns.md`
- `references/development_workflows.md`

## Best Practices Summary

### Code Quality
- Follow established patterns
- Write comprehensive tests
- Document decisions
- Review regularly

### Performance
- Measure before optimizing
- Use appropriate caching
- Optimize critical paths
- Monitor in production

### Security
- Validate all inputs
- Use parameterized queries
- Implement proper authentication
- Keep dependencies updated

### Maintainability
- Write clear code
- Use consistent naming
- Add helpful comments
- Keep it simple

## Common Commands

```bash
# Development
npm run dev
npm run build
npm run test
npm run lint

# Analysis
python scripts/project_scaffolder.py .
python scripts/code_quality_analyzer.py --analyze

# Deployment
docker build -t app:latest .
docker-compose up -d
kubectl apply -f k8s/
```

## Troubleshooting

### Common Issues

Check the comprehensive troubleshooting section in `references/development_workflows.md`.

### Getting Help

- Review reference documentation
- Check script output messages
- Consult tech stack documentation
- Review error logs

## Resources

- Pattern Reference: `references/tech_stack_guide.md`
- Workflow Guide: `references/architecture_patterns.md`
- Technical Guide: `references/development_workflows.md`
- Tool Scripts: `scripts/` directory

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: sentry-automation
description: "Automate Sentry tasks via Rube MCP (Composio): manage issues/events, configure alerts, track releases, monitor projects and teams. Always search tools first for current schemas."
risk: critical
source: community
date_added: "2026-02-27"
---

# Sentry Automation via Rube MCP

Automate Sentry error tracking and monitoring operations through Composio's Sentry toolkit via Rube MCP.

## Prerequisites

- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active Sentry connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `sentry`
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas

## Setup

**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `sentry`
3. If connection is not ACTIVE, follow the returned auth link to complete Sentry OAuth
4. Confirm connection status shows ACTIVE before running any workflows

## Core Workflows

### 1. Investigate Issues

**When to use**: User wants to find, inspect, or triage error issues

**Tool sequence**:
1. `SENTRY_LIST_AN_ORGANIZATIONS_ISSUES` - List issues across the organization [Required]
2. `SENTRY_GET_ORGANIZATION_ISSUE_DETAILS` - Get detailed info on a specific issue [Optional]
3. `SENTRY_LIST_AN_ISSUES_EVENTS` - View individual error events for an issue [Optional]
4. `SENTRY_RETRIEVE_AN_ISSUE_EVENT` - Get full event details with stack trace [Optional]
5. `SENTRY_RETRIEVE_ISSUE_TAG_DETAILS` - Inspect tag distribution for an issue [Optional]

**Key parameters**:
- `organization_id_or_slug`: Organization identifier
- `issue_id`: Numeric issue ID
- `query`: Search query (e.g., `is:unresolved`, `assigned:me`, `browser:Chrome`)
- `sort`: Sort order (`date`, `new`, `freq`, `priority`)
- `statsPeriod`: Time window for stats (`24h`, `14d`, etc.)

**Pitfalls**:
- `organization_id_or_slug` is the org slug (e.g., 'my-org'), not the display name
- Issue IDs are numeric; do not confuse with event IDs which are UUIDs
- Query syntax uses Sentry's search format: `is:unresolved`, `assigned:me`, `!has:release`
- Events within an issue can have different stack traces; inspect individual events for details

### 2. Manage Project Issues

**When to use**: User wants to view issues scoped to a specific project

**Tool sequence**:
1. `SENTRY_RETRIEVE_ORGANIZATION_PROJECTS` - List projects to find project slug [Prerequisite]
2. `SENTRY_RETRIEVE_PROJECT_ISSUES_LIST` - List issues for a specific project [Required]
3. `SENTRY_RETRIEVE_ISSUE_EVENTS_BY_ID` - Get events for a specific issue [Optional]

**Key parameters**:
- `organization_id_or_slug`: Organization identifier
- `project_id_or_slug`: Project identifier
- `query`: Search filter string
- `statsPeriod`: Stats time window

**Pitfalls**:
- Project slugs are different from project display names
- Always resolve project names to slugs via RETRIEVE_ORGANIZATION_PROJECTS first
- Project-scoped issue lists may have different pagination than org-scoped lists

### 3. Configure Alert Rules

**When to use**: User wants to create or manage alert rules for a project

**Tool sequence**:
1. `SENTRY_RETRIEVE_ORGANIZATION_PROJECTS` - Find project for the alert [Prerequisite]
2. `SENTRY_RETRIEVE_PROJECT_RULES_BY_ORG_AND_PROJECT_ID` - List existing rules [Optional]
3. `SENTRY_CREATE_PROJECT_RULE_FOR_ALERTS` - Create a new alert rule [Required]
4. `SENTRY_CREATE_ORGANIZATION_ALERT_RULE` - Create org-level metric alert [Alternative]
5. `SENTRY_UPDATE_ORGANIZATION_ALERT_RULES` - Update existing alert rules [Optional]
6. `SENTRY_RETRIEVE_ALERT_RULE_DETAILS` - Inspect specific alert rule [Optional]
7. `SENTRY_GET_PROJECT_RULE_DETAILS` - Get project-level rule details [Optional]

**Key parameters**:
- `name`: Alert rule name
- `conditions`: Array of trigger conditions
- `actions`: Array of actions to perform when triggered
- `filters`: Array of event filters
- `frequency`: How often to trigger (in minutes)
- `actionMatch`: 'all', 'any', or 'none' for condition matching

**Pitfalls**:
- Project-level rules (CREATE_PROJECT_RULE) and org-level metric alerts (CREATE_ORGANIZATION_ALERT_RULE) are different
- Conditions, actions, and filters use specific JSON schemas; check Sentry docs for valid types
- `frequency` is in minutes; setting too low causes alert fatigue
- `actionMatch` defaults may vary; explicitly set to avoid unexpected behavior

### 4. Manage Releases

**When to use**: User wants to create, track, or manage release versions

**Tool sequence**:
1. `SENTRY_LIST_ORGANIZATION_RELEASES` - List existing releases [Optional]
2. `SENTRY_CREATE_RELEASE_FOR_ORGANIZATION` - Create a new release [Required]
3. `SENTRY_UPDATE_RELEASE_DETAILS_FOR_ORGANIZATION` - Update release metadata [Optional]
4. `SENTRY_CREATE_RELEASE_DEPLOY_FOR_ORG` - Record a deployment for a release [Optional]
5. `SENTRY_UPLOAD_RELEASE_FILE_TO_ORGANIZATION` - Upload source maps or files [Optional]

**Key parameters**:
- `version`: Release version string (e.g., '1.0.0', commit SHA)
- `projects`: Array of project slugs this release belongs to
- `dateReleased`: Release timestamp (ISO 8601)
- `environment`: Deployment environment name (e.g., 'production', 'staging')

**Pitfalls**:
- Release versions must be unique within an organization
- Releases can span multiple projects; use the `projects` array
- Deploying a release is separate from creating it; use CREATE_RELEASE_DEPLOY
- Source map uploads require the release to exist first

### 5. Monitor Organization and Teams

**When to use**: User wants to view org structure, teams, or member lists

**Tool sequence**:
1. `SENTRY_GET_ORGANIZATION_DETAILS` or `SENTRY_GET_ORGANIZATION_BY_ID_OR_SLUG` - Get org info [Required]
2. `SENTRY_LIST_TEAMS_IN_ORGANIZATION` - List all teams [Optional]
3. `SENTRY_LIST_ORGANIZATION_MEMBERS` - List org members [Optional]
4. `SENTRY_GET_PROJECT_LIST` - List all accessible projects [Optional]

**Key parameters**:
- `organization_id_or_slug`: Organization identifier
- `cursor`: Pagination cursor for large result sets

**Pitfalls**:
- Organization slugs are URL-safe identifiers, not display names
- Member lists may be paginated; follow cursor pagination
- Team and member visibility depends on the authenticated user's permissions

### 6. Manage Monitors (Cron Monitoring)

**When to use**: User wants to update cron job monitoring configuration

**Tool sequence**:
1. `SENTRY_UPDATE_A_MONITOR` - Update monitor configuration [Required]

**Key parameters**:
- `organization_id_or_slug`: Organization identifier
- `monitor_id_or_slug`: Monitor identifier
- `name`: Monitor display name
- `schedule`: Cron schedule expression or interval
- `checkin_margin`: Grace period in minutes for late check-ins
- `max_runtime`: Maximum expected runtime in minutes

**Pitfalls**:
- Monitor slugs are auto-generated from the name; use slug for API calls
- Schedule changes take effect immediately
- Missing check-ins trigger alerts after the margin period

## Common Patterns

### ID Resolution

**Organization name -> Slug**:
```
1. Call SENTRY_GET_ORGANIZATION_DETAILS
2. Extract slug field from response
```

**Project name -> Slug**:
```
1. Call SENTRY_RETRIEVE_ORGANIZATION_PROJECTS
2. Find project by name, extract slug
```

### Pagination

- Sentry uses cursor-based pagination with `Link` headers
- Check response for cursor values
- Pass cursor in next request until no more pages

### Search Query Syntax

- `is:unresolved` - Unresolved issues
- `is:resolved` - Resolved issues
- `assigned:me` - Assigned to current user
- `assigned:team-slug` - Assigned to a team
- `!has:release` - Issues without a release
- `first-release:1.0.0` - Issues first seen in release
- `times-seen:>100` - Seen more than 100 times
- `browser:Chrome` - Filter by browser tag

## Known Pitfalls

**ID Formats**:
- Organization: use slug (e.g., 'my-org'), not display name
- Project: use slug (e.g., 'my-project'), not display name
- Issue IDs: numeric integers
- Event IDs: UUIDs (32-char hex strings)

**Permissions**:
- API token scopes must match the operations being performed
- Organization-level operations require org-level permissions
- Project-level operations require project access

**Rate Limits**:
- Sentry enforces per-organization rate limits
- Implement backoff on 429 responses
- Bulk operations should be staggered

## Quick Reference

| Task | Tool Slug | Key Params |
|------|-----------|------------|
| List org issues | SENTRY_LIST_AN_ORGANIZATIONS_ISSUES | organization_id_or_slug, query |
| Get issue details | SENTRY_GET_ORGANIZATION_ISSUE_DETAILS | organization_id_or_slug, issue_id |
| List issue events | SENTRY_LIST_AN_ISSUES_EVENTS | issue_id |
| Get event details | SENTRY_RETRIEVE_AN_ISSUE_EVENT | organization_id_or_slug, event_id |
| List project issues | SENTRY_RETRIEVE_PROJECT_ISSUES_LIST | organization_id_or_slug, project_id_or_slug |
| List projects | SENTRY_RETRIEVE_ORGANIZATION_PROJECTS | organization_id_or_slug |
| Get org details | SENTRY_GET_ORGANIZATION_DETAILS | organization_id_or_slug |
| List teams | SENTRY_LIST_TEAMS_IN_ORGANIZATION | organization_id_or_slug |
| List members | SENTRY_LIST_ORGANIZATION_MEMBERS | organization_id_or_slug |
| Create alert rule | SENTRY_CREATE_PROJECT_RULE_FOR_ALERTS | organization_id_or_slug, project_id_or_slug |
| Create metric alert | SENTRY_CREATE_ORGANIZATION_ALERT_RULE | organization_id_or_slug |
| Create release | SENTRY_CREATE_RELEASE_FOR_ORGANIZATION | organization_id_or_slug, version |
| Deploy release | SENTRY_CREATE_RELEASE_DEPLOY_FOR_ORG | organization_id_or_slug, version |
| List releases | SENTRY_LIST_ORGANIZATION_RELEASES | organization_id_or_slug |
| Update monitor | SENTRY_UPDATE_A_MONITOR | organization_id_or_slug, monitor_id_or_slug |

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo
description: "Run a broad SEO audit across technical SEO, on-page SEO, schema, sitemaps, content quality, AI search readiness, and GEO. Use as the umbrella skill when the user asks for a full SEO analysis or strategy."
risk: critical
source: "https://github.com/AgriciDaniel/claude-seo"
date_added: "2026-03-21"
user-invokable: true
argument-hint: "[command] [url]"
---

# SEO: Universal SEO Analysis Skill

Comprehensive SEO analysis across all industries (SaaS, local services,
e-commerce, publishers, agencies). Orchestrates 12 specialized sub-skills and 7 subagents
(+ optional extension sub-skills like seo-dataforseo).

## When to Use
- Use when the user asks for a full SEO audit or broad SEO strategy.
- Use as the umbrella entry point when multiple SEO dimensions are in scope.
- Use when the task spans technical SEO, content, schema, sitemaps, and AI search readiness together.

## Quick Reference

| Command | What it does |
|---------|-------------|
| `/seo audit <url>` | Full website audit with parallel subagent delegation |
| `/seo page <url>` | Deep single-page analysis |
| `/seo sitemap <url or generate>` | Analyze or generate XML sitemaps |
| `/seo schema <url>` | Detect, validate, and generate Schema.org markup |
| `/seo images <url>` | Image optimization analysis |
| `/seo technical <url>` | Technical SEO audit (9 categories) |
| `/seo content <url>` | E-E-A-T and content quality analysis |
| `/seo geo <url>` | AI Overviews / Generative Engine Optimization |
| `/seo plan <business-type>` | Strategic SEO planning |
| `/seo programmatic [url\|plan]` | Programmatic SEO analysis and planning |
| `/seo competitor-pages [url\|generate]` | Competitor comparison page generation |
| `/seo hreflang [url]` | Hreflang/i18n SEO audit and generation |
| `/seo dataforseo [command]` | Live SEO data via DataForSEO (extension) |
| `/seo image-gen [use-case] <description>` | AI image generation for SEO assets (extension) |

## Orchestration Logic

When the user invokes `/seo audit`, delegate to subagents in parallel:
1. Detect business type (SaaS, local, ecommerce, publisher, agency, other)
2. Spawn subagents: seo-technical, seo-content, seo-schema, seo-sitemap, seo-performance, seo-visual, seo-geo
3. Collect results and generate unified report with SEO Health Score (0-100)
4. Create prioritized action plan (Critical -> High -> Medium -> Low)

For individual commands, load the relevant sub-skill directly.

## Industry Detection

Detect business type from homepage signals:
- **SaaS**: pricing page, /features, /integrations, /docs, "free trial", "sign up"
- **Local Service**: phone number, address, service area, "serving [city]", Google Maps embed
- **E-commerce**: /products, /collections, /cart, "add to cart", product schema
- **Publisher**: /blog, /articles, /topics, article schema, author pages, publication dates
- **Agency**: /case-studies, /portfolio, /industries, "our work", client logos

## Quality Gates

Read `references/quality-gates.md` for thin content thresholds per page type.
Hard rules:
- WARNING at 30+ location pages (enforce 60%+ unique content)
- HARD STOP at 50+ location pages (require user justification)
- Never recommend HowTo schema (deprecated Sept 2023)
- FAQ schema for Google rich results: only government and healthcare sites (Aug 2023 restriction); existing FAQPage on commercial sites -> flag Info priority (not Critical), noting AI/LLM citation benefit; adding new FAQPage -> not recommended for Google benefit
- All Core Web Vitals references use INP, never FID

## Reference Files

Load these on-demand as needed (do NOT load all at startup):
- `references/cwv-thresholds.md`: Current Core Web Vitals thresholds and measurement details
- `references/schema-types.md`: All supported schema types with deprecation status
- `references/eeat-framework.md`: E-E-A-T evaluation criteria (Sept 2025 QRG update)
- `references/quality-gates.md`: Content length minimums, uniqueness thresholds

## Scoring Methodology

### SEO Health Score (0-100)
Weighted aggregate of all categories:

| Category | Weight |
|----------|--------|
| Technical SEO | 22% |
| Content Quality | 23% |
| On-Page SEO | 20% |
| Schema / Structured Data | 10% |
| Performance (CWV) | 10% |
| AI Search Readiness | 10% |
| Images | 5% |

### Priority Levels
- **Critical**: Blocks indexing or causes penalties (immediate fix required)
- **High**: Significantly impacts rankings (fix within 1 week)
- **Medium**: Optimization opportunity (fix within 1 month)
- **Low**: Nice to have (backlog)

## Sub-Skills

This skill orchestrates 12 specialized sub-skills (+ 2 extensions):

1. **seo-audit** -- Full website audit with parallel delegation
2. **seo-page** -- Deep single-page analysis
3. **seo-technical** -- Technical SEO (9 categories)
4. **seo-content** -- E-E-A-T and content quality
5. **seo-schema** -- Schema markup detection and generation
6. **seo-images** -- Image optimization
7. **seo-sitemap** -- Sitemap analysis and generation
8. **seo-geo** -- AI Overviews / GEO optimization
9. **seo-plan** -- Strategic planning with templates
10. **seo-programmatic** -- Programmatic SEO analysis and planning
11. **seo-competitor-pages** -- Competitor comparison page generation
12. **seo-hreflang** -- Hreflang/i18n SEO audit and generation
13. **seo-dataforseo** -- Live SEO data via DataForSEO MCP (extension)
14. **seo-image-gen** -- AI image generation for SEO assets via Gemini (extension)

## Subagents

For parallel analysis during audits:
- `seo-technical` -- Crawlability, indexability, security, CWV
- `seo-content` -- E-E-A-T, readability, thin content
- `seo-schema` -- Detection, validation, generation
- `seo-sitemap` -- Structure, coverage, quality gates
- `seo-performance` -- Core Web Vitals measurement
- `seo-visual` -- Screenshots, mobile testing, above-fold
- `seo-geo` -- AI crawler access, llms.txt, citability, brand mention signals
- `seo-dataforseo` -- Live SERP, keyword, backlink, local SEO data (extension, optional)
- `seo-image-gen` -- SEO image audit and generation plan (extension, optional)

## Error Handling

| Scenario | Action |
|----------|--------|
| Unrecognized command | List available commands from the Quick Reference table. Suggest the closest matching command. |
| URL unreachable | Report the error and suggest the user verify the URL. Do not attempt to guess site content. |
| Sub-skill fails during audit | Report partial results from successful sub-skills. Clearly note which sub-skill failed and why. Suggest re-running the failed sub-skill individually. |
| Ambiguous business type detection | Present the top two detected types with supporting signals. Ask the user to confirm before proceeding with industry-specific recommendations. |

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-aeo-blog-writer
description: "Writes long-form blog posts with TL;DR block, definition sentence, comparison table, and 5-question FAQ for SEO ranking and AEO citation. Activate when the user wants to write a blog post, article, or long-form content piece."
risk: safe
source: community
date_added: "2026-04-01"
---

# SEO-AEO Blog Writer

## Overview

Writes structured long-form blog posts (800–3000 words) that satisfy both SEO ranking signals and AEO citation requirements. Every post includes a TL;DR direct-answer block, a definition sentence, structured H2/H3 hierarchy, a comparison table where relevant, and exactly 5 FAQ entries written for AI extraction.

Part of the [SEO-AEO Engine](https://github.com/mrprewsh/seo-aeo-engine).

## When to Use This Skill

- Use when writing a cluster article from a content cluster map
- Use when creating a long-form guide to build topical authority
- Use when you need content that can be cited by AI engines like Perplexity or ChatGPT
- Use when you need a blog post that follows a consistent, auditable structure

## How It Works

### Step 1: Write the TL;DR Block First
Write a 2–3 sentence direct answer to the article's core question. Place it immediately after the H1 in a blockquote. This is the first block AI engines attempt to extract.

### Step 2: Build the Heading Skeleton
Set H1, H2s (4–6), and H3s before writing any body content. The first H2 must be a "What Is" section with a clean definition sentence as its opening line.

### Step 3: Write Body Sections
Follow the section order: What Is → Why It Matters → How It Works (with H3 sub-concepts) → Practical Steps → Common Mistakes → FAQ → Conclusion.

### Step 4: Write 5 FAQ Entries
Use long-tail and secondary keywords as questions. Each answer must be under 50 words and self-contained — readable without any surrounding context.

### Step 5: Run AEO and SEO Checklists
Verify TL;DR presence, definition sentence, FAQ count, keyword placement, and heading structure before outputting.

## Examples

### Example: TL;DR Block
How to Manage a Remote Engineering Team

TL;DR: Managing a remote engineering team requires async
communication tools, clear documentation standards, and
timezone-aware sprint planning. Teams that nail these three
areas ship consistently regardless of where members are located.

### Example: FAQ Section
Q: What is the biggest challenge of remote engineering teams?
A: Async communication. Without shared hours, decisions slow down
and context gets lost. Teams that document decisions in writing
and use structured standup tools close this gap fastest.
Q: How do you run a daily standup with a remote team?
A: Use async video or text standups posted at the start of each
member's day. Tools like Loom or Slack threads work well.
Avoid live calls across more than 2 timezones.

## Best Practices

- ✅ **Do:** Write the TL;DR block before writing anything else — it anchors the article
- ✅ **Do:** Make the "What Is" definition sentence extractable on its own — one clean sentence
- ✅ **Do:** Use secondary keywords as FAQ questions to capture long-tail traffic
- ❌ **Don't:** Write FAQ answers longer than 50 words — AI engines skip long answers
- ❌ **Don't:** Use duplicate H2 headings anywhere in the article
- ❌ **Don't:** Skip the comparison table if the topic involves comparing options

## Common Pitfalls

- **Problem:** TL;DR block is too vague to be extracted as a direct answer
  **Solution:** The TL;DR must answer the article's core question in 2–3 sentences. If it doesn't answer a specific question, rewrite it.

- **Problem:** FAQ answers reference "as mentioned above" or other context
  **Solution:** Every FAQ answer must stand completely alone — no references to other parts of the article.

## Related Skills

- `@seo-aeo-content-cluster` — provides the topic and keyword for this article
- `@seo-aeo-content-quality-auditor` — audits the completed post for SEO and AEO signals
- `@seo-aeo-internal-linking` — maps links between this post and related pages

## Additional Resources

- [SEO-AEO Engine Repository](https://github.com/mrprewsh/seo-aeo-engine)
- [Full Blog Writer SKILL.md](https://github.com/mrprewsh/seo-aeo-engine/blob/main/.agent/skills/blog-writer/SKILL.md)

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-aeo-content-cluster
description: "Builds a topical authority map with a pillar page, prioritised cluster articles, content types, internal link map, and content gap analysis. Activate when the user wants to build a content cluster, topic map, or content strategy."
risk: safe
source: community
date_added: "2026-04-01"
---

# SEO-AEO Content Cluster

## Overview

Maps out a complete topical authority structure around a pillar keyword. Produces a pillar page definition, 8–15 cluster articles sorted into Priority 1/2/3 tiers, a content type for each, an internal link map, and a content gap analysis identifying AEO opportunities competitors are missing.

Part of the [SEO-AEO Engine](https://github.com/mrprewsh/seo-aeo-engine).

## When to Use This Skill

- Use when building topical authority around a new subject
- Use when you need to know what to write next to support a pillar page
- Use when planning a content calendar for a niche
- Use when you want to identify AEO content gaps competitors are missing

## How It Works

### Step 1: Define the Pillar Page
Set the primary keyword, target audience, and word count target (2500–4000 words) for the pillar page that anchors the cluster.

### Step 2: Generate Cluster Articles
Produce 8–15 subtopics sorted into three priority tiers:
- **Priority 1** — High volume, clear intent. Write these first.
- **Priority 2** — Medium volume, long-tail focus. Write second.
- **Priority 3** — Low volume, high conversion intent. Write last.

Assign each article a unique keyword, content type, search intent, and link map.

### Step 3: Build Internal Link Map
Every cluster article must link back to the pillar page. No orphan articles. Show the full tree of relationships.

### Step 4: Run Content Gap Analysis
Identify angles that competitors likely miss — especially question-based AEO opportunities that AI engines commonly surface.

## Examples

### Example: Automated Budgeting Cluster
Pillar: The Complete Guide to Automated Budgeting
Priority 1:

How to Build a Budget That Actually Works | how-to guide
Best Budgeting Apps Compared | comparison
What Is Zero-Based Budgeting? | explainer ← AEO priority

Priority 2:
4. How to Automate Your Savings in 3 Steps | how-to guide
5. Budgeting for Millennials: What Nobody Tells You | opinion
Link Map:
Pillar ← Article 1, 2, 3, 4, 5
Article 1 ↔ Article 4
Article 2 → Article 3
AEO Priority:
★ Article 3 — "What Is" format has highest AI extraction probability
★ Article 2 — comparison table will be lifted for product queries

## Best Practices

- ✅ **Do:** Assign every cluster article a unique target keyword — no overlap
- ✅ **Do:** Include at least one FAQ page and one comparison article in every cluster
- ✅ **Do:** Flag the 2 highest AEO-opportunity articles for priority writing
- ❌ **Don't:** Let any article become an orphan — every article links to at least one other
- ❌ **Don't:** Target the same keyword on both the pillar and a cluster article

## Common Pitfalls

- **Problem:** Cluster articles all target similar keywords and cannibalise each other
  **Solution:** Run a uniqueness check — every article needs a distinct keyword with no semantic overlap.

- **Problem:** No AEO content in the cluster
  **Solution:** At least 2 articles must be structured as direct-answer pages (FAQ or "What Is" explainer).

## Related Skills

- `@seo-aeo-keyword-research` — provides the keyword foundation for the cluster
- `@seo-aeo-blog-writer` — writes the Priority 1 cluster articles
- `@seo-aeo-internal-linking` — builds the detailed link map from cluster output

## Additional Resources

- [SEO-AEO Engine Repository](https://github.com/mrprewsh/seo-aeo-engine)
- [Full Content Cluster SKILL.md](https://github.com/mrprewsh/seo-aeo-engine/blob/main/.agent/skills/content-cluster/SKILL.md)

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-aeo-content-quality-auditor
description: "Audits content for SEO and AEO performance with scored reports, severity-ranked fix lists, and projected scores after fixes. Activate when the user wants to audit, review, or score content for SEO or AEO compliance."
risk: safe
source: community
date_added: "2026-04-01"
---

# SEO-AEO Content Quality Auditor

## Overview

Runs a dual SEO + AEO audit on any landing page or blog post. Produces an overall score, SEO score, AEO score, and readability score — each out of 100 — with severity-ranked issue lists (Critical / Warning / Polish), exact fix instructions for every issue, and projected scores after all fixes are applied.

Part of the [SEO-AEO Engine](https://github.com/mrprewsh/seo-aeo-engine).

## When to Use This Skill

- Use when auditing a landing page or blog post before publishing
- Use after the blog-writer or landing-page-writer skill outputs content
- Use when diagnosing why existing content is underperforming in search
- Use when you need a scored, actionable SEO and AEO report

## How It Works

### Step 1: Run SEO Checks
Verify keyword density, H1/H2/H3 structure, meta elements, word count, sentence length, and paragraph density. Flag every issue with its severity.

### Step 2: Run AEO Checks
Check for TL;DR block, definition sentence, FAQ section (minimum 4 entries), bullet and numbered lists, comparison table, and extractable direct answers. Score each signal as found or missing.

### Step 3: Run Readability Checks
Check passive voice ratio, transition word presence, wall-of-text paragraphs, subheading frequency, and reading level.

### Step 4: Score and Prioritise
Calculate three scores out of 100. Sort all issues into Critical (fix before publishing), Important (fix soon), and Polish (optional improvements). Generate projected scores after all fixes are applied.

## Scoring System

| Score | Status | Label |
|-------|--------|-------|
| 85–100 | ✅ Pass | Strong |
| 70–84 | ⚠ Warn | Acceptable |
| 50–69 | 🔶 Weak | Needs work |
| 0–49 | ❌ Fail | Do not publish |

## Examples

### Example: Audit Summary
Overall Score:    84/100  ⚠ Acceptable
SEO Score:        88/100  ✅ Pass
AEO Score:        74/100  ⚠ Acceptable
Readability:      91/100  ✅ Pass
Verdict: Strong SEO foundation. AEO needs a TL;DR block
and one more FAQ entry before publishing.
🔴 Critical (fix before publishing):

AEO: No TL;DR block found
Fix: Add a 2–3 sentence direct-answer block in a
blockquote immediately after the H1.

🟡 Important (fix soon):
2. AEO: FAQ has 3 entries — minimum is 4
Fix: Add one more FAQ entry using a secondary keyword
as the question.
Projected score after fixes: 93/100 ✅

## Best Practices

- ✅ **Do:** Fix all Critical issues before publishing — they block AEO extraction
- ✅ **Do:** Use the projected score to prioritise which fixes to make first
- ✅ **Do:** Run the audit on both the landing page and blog post in the same session
- ❌ **Don't:** Publish content scoring below 50/100 overall
- ❌ **Don't:** Ignore AEO warnings — they directly affect AI engine citation probability

## Common Pitfalls

- **Problem:** SEO score is high but AEO score is low
  **Solution:** Traditional SEO tools miss AEO signals entirely. Run the AEO checklist separately and treat it as equally important.

- **Problem:** Fix list is long and overwhelming
  **Solution:** Work through Critical issues only first, re-run the audit, then tackle Important issues.

## Related Skills

- `@seo-aeo-blog-writer` — produces the content this skill audits
- `@seo-aeo-landing-page-writer` — produces landing pages this skill audits
- `@seo-aeo-schema-generator` — uses audit output to determine schema priorities

## Additional Resources

- [SEO-AEO Engine Repository](https://github.com/mrprewsh/seo-aeo-engine)
- [Full Content Quality Auditor SKILL.md](https://github.com/mrprewsh/seo-aeo-engine/blob/main/.agent/skills/content-quality-auditor/SKILL.md)

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-aeo-internal-linking
description: "Maps internal link opportunities between pages with anchor text, placement instructions, orphan page detection, and cannibalization checks. Activate when the user wants to build an internal linking strategy or find link opportunities."
risk: safe
source: community
date_added: "2026-04-01"
---

# SEO-AEO Internal Linking

## Overview

Analyses a set of pages and produces a prioritised list of internal link opportunities with exact anchor text, a context sentence showing where each link should appear, orphan page detection, anchor text cannibalization warnings, and a link equity map showing how authority flows across the content.

Part of the [SEO-AEO Engine](https://github.com/mrprewsh/seo-aeo-engine).

## When to Use This Skill

- Use when building internal links between a new pillar page and its cluster articles
- Use when auditing an existing site for orphan pages
- Use after content-cluster generates a topic map
- Use when you need anchor text suggestions with placement context

## How It Works

### Step 1: Detect Orphan Pages
Flag any page with zero incoming internal links. These are invisible to search engines and must be linked immediately.

### Step 2: Build Semantic Overlap Matrix
Match pages by primary keyword similarity and content summary to identify natural linking opportunities.

### Step 3: Assign Link Types
Every suggestion gets one of four labels:
- **Cluster → Pillar** — highest priority, consolidates authority upward
- **Pillar → Cluster** — distributes authority downward
- **Cluster → Cluster** — builds semantic depth
- **Contextual Boost** — concentrates equity on a focus page

### Step 4: Write Context Sentences
For every link opportunity, write the sentence the anchor text should appear in — naturally placed, not forced.

### Step 5: Check Anchor Text
Flag any exact-match anchor used more than once for the same target page as a cannibalization risk. Never use generic anchors like "click here".

## Examples

### Example: Link Opportunity Output
🔴 High Priority — Link 1
Type: Cluster → Pillar
Source: "How to Build a Budget That Actually Works"
Target: "The Complete Guide to Automated Budgeting"
Anchor: "automated budgeting guide"
Context: "For a full breakdown of every method available,
see our [automated budgeting guide]."
Impact: Consolidates topical authority on pillar page.
Orphan Alert:
"PennyWise Pricing Page" has no incoming links.
Fix: Add link from comparison table in Article 2.

## Best Practices

- ✅ **Do:** Every cluster article must have at least one Cluster → Pillar link
- ✅ **Do:** Write a context sentence for every suggestion — anchor text needs natural placement
- ✅ **Do:** Fix orphan pages before adding any new links
- ❌ **Don't:** Use the same exact-match anchor for the same target page more than once
- ❌ **Don't:** Use "click here", "read more", or "learn more" as anchor text — ever
- ❌ **Don't:** Add more than 100 outgoing internal links on any single page

## Common Pitfalls

- **Problem:** All cluster articles link to the pillar but not to each other
  **Solution:** Add Cluster → Cluster links between semantically related articles to build depth.

- **Problem:** Same anchor text used across multiple pages for the same target
  **Solution:** Use partial match and branded anchors for subsequent links after the first exact-match use.

## Related Skills

- `@seo-aeo-content-cluster` — generates the cluster map this skill links together
- `@seo-aeo-schema-generator` — uses link map output for BreadcrumbList schema

## Additional Resources

- [SEO-AEO Engine Repository](https://github.com/mrprewsh/seo-aeo-engine)
- [Full Internal Linking SKILL.md](https://github.com/mrprewsh/seo-aeo-engine/blob/main/.agent/skills/internal-linking/SKILL.md)

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-aeo-keyword-research
description: "Researches and prioritises SEO keywords with AEO question queries, difficulty tiers, cannibalization checks, and a content map. Activate when the user wants to find keywords, research search terms, or build a keyword strategy."
risk: safe
source: community
date_added: "2026-04-01"
---

# SEO-AEO Keyword Research

## Overview

Identifies high-value SEO keywords and AEO question-based queries for a topic. Produces keyword tiers (easy wins to long-term goals), search intent classification, cannibalization checks, and a content production map — all from a single topic input.

Part of the [SEO-AEO Engine](https://github.com/mrprewsh/seo-aeo-engine) — an open-source AI-powered content growth system.

## When to Use This Skill

- Use when you need to build a keyword strategy for a new topic or niche
- Use when you want to find AEO question queries for AI engine citation
- Use when you need to prioritise which keywords to target first
- Use when you want to check for keyword cannibalization before writing content

## How It Works

### Step 1: Extract Seed Keywords
Identify 3–5 core terms that anchor the topic's search territory. Go beyond the obvious head term to include adjacent terms the audience actually uses.

### Step 2: Expand Into Tiers
Sort all keywords into three tiers:
- **Tier 1** — Low-to-moderate difficulty. Target first.
- **Tier 2** — Medium difficulty. Build toward after Tier 1 content is live.
- **Tier 3** — High difficulty. Long-term goals only.

### Step 3: Generate AEO Keywords
Produce question-based keywords that AI engines surface in direct answers and People Also Ask boxes. For each AEO keyword, specify the answer format to use (definition sentence, numbered steps, comparison table, direct number).

### Step 4: Run Cannibalization Check
Flag any two keywords similar enough to split traffic if targeted on separate pages. Recommend which page should own which term.

### Step 5: Build Content Map
Recommend content type and production order for all Tier 1 and Tier 2 keywords.

## Examples

### Example 1: SaaS Product
Input: topic = "remote project management software"
audience = "engineering managers and startup founders"
goal = "convert"
Output:
Tier 1 Keywords:

"remote project management software" | Medium volume | Difficulty: 38
"project management tool remote teams" | Low volume | Difficulty: 29

AEO Keywords:

"What is the best project management software for remote teams?"
→ Answer format: Comparison table
"How does remote project management work?"
→ Answer format: Numbered steps

Content Map:

Landing page → "remote project management software"
Pillar blog → "complete guide to remote project management"
Cluster article → "how to manage remote engineering teams"

### Example 2: Fintech App
Input: topic = "automated budgeting app"
audience = "millennials managing personal finances"
goal = "all"
Output:
Tier 1 Keywords:

"automated budgeting app" | Medium volume | Difficulty: 33
"automatic savings app" | Low volume | Difficulty: 24

AEO Keywords:

"What is the best budgeting app for millennials?"
→ Answer format: Comparison table
"How does automated budgeting work?"
→ Answer format: Numbered steps

## Best Practices

- ✅ **Do:** Target Tier 1 keywords first — build authority before going after competitive terms
- ✅ **Do:** Use AEO keywords in FAQ sections and definition blocks for AI engine citation
- ✅ **Do:** Validate estimated volume and difficulty with a live tool (Ahrefs, SEMrush) before committing
- ❌ **Don't:** Target two keywords on the same page if cannibalization is flagged
- ❌ **Don't:** Use volume as the only prioritisation signal — difficulty and intent matter more

## Common Pitfalls

- **Problem:** High-volume keyword chosen but impossible to rank for early on
  **Solution:** Always cross-check volume with difficulty. Tier 1 should have difficulty under 45.

- **Problem:** AEO keywords ignored in favour of traditional search terms
  **Solution:** AEO keywords drive AI engine citation — include at least 5 in every research run.

## Related Skills

- `@seo-aeo-content-cluster` — uses keyword research output to build topic cluster
- `@seo-aeo-landing-page-writer` — consumes primary keyword to generate landing page
- `@seo-aeo-blog-writer` — uses secondary keywords for cluster article targeting

## Additional Resources

- [SEO-AEO Engine Repository](https://github.com/mrprewsh/seo-aeo-engine)
- [Full Keyword Research SKILL.md](https://github.com/mrprewsh/seo-aeo-engine/blob/main/.agent/skills/keyword-research/SKILL.md)

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-aeo-landing-page-writer
description: "Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer."
risk: safe
source: community
date_added: "2026-04-01"
---

# SEO-AEO Landing Page Writer

## Overview

Generates a full, publish-ready landing page following a defined section order with SEO heading structure, AEO extraction blocks, FAQ section, comparison table, social proof, and conversion-focused CTAs. Every section serves a specific purpose in a narrative arc that moves the visitor from awareness to action.

Part of the [SEO-AEO Engine](https://github.com/mrprewsh/seo-aeo-engine).

## When to Use This Skill

- Use when building a landing page for a new product or service
- Use when an existing landing page needs a full SEO and AEO rewrite
- Use when you need a page that can be cited by AI engines like Perplexity or ChatGPT
- Use when you want conversion copy that leads with pain before pitching the product

## How It Works

### Step 1: Map Inputs
Extract product name, audience, primary keyword, pain points, features, benefits, USPs, social proof, and CTAs. Map every feature to a user outcome before writing any copy.

### Step 2: Write AEO Extraction Sentence
Write one 25–40 word sentence that answers "What is [product]?" — standalone, no jargon, placed in a blockquote immediately after the H1. This is the sentence AI engines extract.

### Step 3: Follow the Narrative Arc
Write sections in this exact order:
1. Hero — H1 + AEO sentence + CTA
2. Problem — audience pain, no product mention yet
3. Solution — introduce product as the answer
4. Features as Benefits — table format
5. Social Proof — testimonials, logos, stats
6. Mid-page CTA
7. How It Works — numbered steps
8. Comparison — table with honest competitor comparison
9. FAQ — minimum 6 entries, each under 50 words
10. Trust Signals
11. Final CTA

### Step 4: Run SEO and AEO Checklists
Verify keyword placement, heading hierarchy, FAQ count, AEO block presence, and meta description placeholder before outputting.

## Examples

### Example 1: Hero Section Output
Ship Faster With Your Remote Team

Syncro is a remote-first project management platform that helps
distributed engineering teams track work, communicate
asynchronously, and ship without the chaos of email and
scattered spreadsheets.

[Start Free Trial]  [See How It Works]
"4,000+ remote teams" · "40% fewer status meetings" · "4.8/5 on G2"

### Example 2: FAQ Section Output
Q: What is Syncro?
A: Syncro is a remote-first project management platform for
distributed engineering teams. It centralises task tracking,
async communication, and sprint planning in one tool.
Q: How much does Syncro cost?
A: Syncro offers a flat-rate plan at $49/month for unlimited
users. A 14-day free trial is available — no credit card required.

## Best Practices

- ✅ **Do:** Write the problem section before mentioning the product — empathy first
- ✅ **Do:** Place the AEO extraction sentence in a blockquote immediately after H1
- ✅ **Do:** Write FAQ answers as standalone — each must make sense without context
- ✅ **Do:** Include at least one honest point in the comparison table where the alternative wins
- ❌ **Don't:** Use "revolutionary", "game-changing", or "best-in-class" anywhere
- ❌ **Don't:** Use "Submit" or "Click Here" as CTA button text
- ❌ **Don't:** Write paragraphs longer than 4 lines

## Common Pitfalls

- **Problem:** Product mentioned in the pain section
  **Solution:** The pain section exists to build empathy. Save the product introduction for the solution section.

- **Problem:** FAQ answers are too long to be extracted by AI engines
  **Solution:** Every FAQ answer must be under 50 words and self-contained.

## Related Skills

- `@seo-aeo-keyword-research` — provides the primary keyword and AEO queries
- `@seo-aeo-meta-description-generator` — writes title and meta description from page output
- `@seo-aeo-content-quality-auditor` — audits the completed landing page

## Additional Resources

- [SEO-AEO Engine Repository](https://github.com/mrprewsh/seo-aeo-engine)
- [Full Landing Page Writer SKILL.md](https://github.com/mrprewsh/seo-aeo-engine/blob/main/.agent/skills/landing-page-writer/SKILL.md)

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-aeo-meta-description-generator
description: "Writes 3 title tag variants and 3 meta description variants per page with SERP preview, OG tags, and Twitter Card tags. Activate when the user wants to write meta tags, title tags, or social sharing tags for any page."
risk: safe
source: community
date_added: "2026-04-01"
---

# SEO-AEO Meta Description Generator

## Overview

Produces 3 title tag variants and 3 meta description variants for any page, each using a different CTR mechanic (benefit lead, question hook, social proof). Also generates Open Graph and Twitter Card tags. Includes a SERP preview block and a variant comparison table with a recommended selection.

Part of the [SEO-AEO Engine](https://github.com/mrprewsh/seo-aeo-engine).

## When to Use This Skill

- Use when a page needs a title tag and meta description written or optimised
- Use when preparing social sharing tags for LinkedIn, X, or WhatsApp
- Use when A/B testing CTR on search results
- Use after the landing-page-writer or blog-writer skill completes

## How It Works

### Step 1: Identify CTR Angle Per Variant
- **V1 Benefit Lead** — leads with the outcome or benefit
- **V2 Question Hook** — opens with the question the searcher is asking
- **V3 Social Proof / Specificity** — leads with a number, stat, or specific claim

### Step 2: Apply Character Limits
- Title tag: 50–60 characters (hard limit: 60)
- Meta description: 140–155 characters (hard limit: 160)
- Never end a description mid-sentence near the limit

### Step 3: Apply CTR Rules
- Primary keyword in first 3 words of every title variant
- Primary keyword in first half of every description variant
- At least one power word per description
- Every description ends with a CTA verb
- Never use "click here", passive openers, or all-caps

### Step 4: Write Social Tags
OG and Twitter tags can be more conversational than SERP tags. Write them as distinct copy — not copy-pastes of the meta description.

## Examples

### Example 1: Landing Page Variants
Title V1: Remote Project Management Software | Syncro
(51 chars) — Keyword first, brand at end
Title V2: Manage Remote Teams Without the Chaos | Syncro
(54 chars) — Pain-point led with power word
Description V1 (Benefit Lead):
Ship faster with your distributed team. Syncro centralises
tasks, async updates, and sprints in one tool. Start free today.
(141 chars) ✅
Description V2 (Question Hook):
Struggling to keep your remote team aligned? Syncro replaces
scattered tools with one async-first workspace. Try it free.
(140 chars) ✅

## Best Practices

- ✅ **Do:** Write 3 variants — always give the user options to test
- ✅ **Do:** Keep OG and Twitter descriptions more conversational than SERP versions
- ✅ **Do:** Verify character count on every variant before outputting
- ❌ **Don't:** Use the same exact-match anchor or keyword more than once per description
- ❌ **Don't:** Copy-paste the meta description into the OG description
- ❌ **Don't:** Let any description end mid-sentence near the character limit

## Common Pitfalls

- **Problem:** Description truncates mid-word in search results
  **Solution:** Always trim a clause rather than letting natural truncation cut the sentence.

- **Problem:** All 3 variants sound identical
  **Solution:** Each variant must use a genuinely different CTR mechanic — not just rearranged words.

## Related Skills

- `@seo-aeo-landing-page-writer` — provides the page content this skill writes tags for
- `@seo-aeo-content-quality-auditor` — verifies meta elements as part of the full audit

## Additional Resources

- [SEO-AEO Engine Repository](https://github.com/mrprewsh/seo-aeo-engine)
- [Full Meta Description Generator SKILL.md](https://github.com/mrprewsh/seo-aeo-engine/blob/main/.agent/skills/meta-description-generator/SKILL.md)

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-aeo-schema-generator
description: "Generates valid JSON-LD structured data for 10 schema types with rich result eligibility validation and implementation-ready script blocks. Activate when the user wants to generate schema markup, JSON-LD, or structured data for any page."
risk: safe
source: community
date_added: "2026-04-01"
---

# SEO-AEO Schema Generator

## Overview

Generates implementation-ready JSON-LD schema markup for 10 schema types including FAQPage, Article, Product, HowTo, and BreadcrumbList. Validates all required fields against Google rich result eligibility rules, flags missing fields with exact fix instructions, and outputs one clean `<script>` block per schema type ready to paste into the page `<head>`.

Part of the [SEO-AEO Engine](https://github.com/mrprewsh/seo-aeo-engine).

## When to Use This Skill

- Use when adding structured data to a new landing page or blog post
- Use when a page needs FAQ rich results or product star ratings in search
- Use when validating existing schema for Google rich result eligibility
- Use after the content-quality-auditor flags missing schema

## Supported Schema Types

| Type | Rich Result Unlocked |
|------|---------------------|
| FAQPage | FAQ accordion in SERP — AEO critical |
| Article | Article rich result, Top Stories |
| Product | Price, availability, rating in SERP |
| HowTo | Step-by-step rich result |
| Review | Star rating in SERP |
| AggregateRating | Star rating with review count |
| BreadcrumbList | Breadcrumb path in SERP URL |
| Organization | Brand knowledge panel signals |
| WebPage | Enhanced page understanding |
| WebSite | Sitelinks Searchbox |

## How It Works

### Step 1: Recommend Schema Types
If schema types are not specified, recommend the appropriate types based on the page type. Landing pages get FAQPage + Product + BreadcrumbList. Blog posts get Article + FAQPage + BreadcrumbList.

### Step 2: Use Built-In Schema Templates
Using your knowledge of schema.org and Google's rich result requirements, construct the JSON-LD template for each requested schema type. Use the required and recommended fields listed in the Google Rich Results documentation for that type.

### Step 3: Populate Fields
Map all page data to template placeholders. Check every required field against the rich result eligibility rules.

### Step 4: Validate
Flag any missing required field as a Critical issue. Flag missing recommended fields as warnings. Do not output schema with missing required fields.

### Step 5: Output Script Blocks
Write one `<script type="application/ld+json">` block per schema type. Include implementation instructions and testing tool links.

## Examples

### Example: FAQPage Schema Output
```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is Syncro?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Syncro is a remote-first project management platform for distributed engineering teams. It centralises task tracking, async communication, and sprint planning in one tool."
      }
    }
  ]
}
</script>
```

## Best Practices

- ✅ **Do:** Always include FAQPage schema on any page with a FAQ section — it is the strongest AEO signal
- ✅ **Do:** Use one `<script>` block per schema type — never combine multiple types
- ✅ **Do:** Test every output in Google's Rich Results Test before deploying
- ❌ **Don't:** Use relative URLs anywhere in schema — all URLs must start with `https://`
- ❌ **Don't:** Leave placeholder text in any field before deploying
- ❌ **Don't:** Use HTML tags inside JSON-LD string values

## Common Pitfalls

- **Problem:** Schema passes validation but rich result doesn't appear in search
  **Solution:** Rich results can take weeks to appear after deployment. Request re-indexing in Google Search Console immediately after adding schema.

- **Problem:** Product schema missing star rating display
  **Solution:** Add AggregateRating object with ratingValue, reviewCount, bestRating, and worstRating — all four fields required.

## Related Skills

- `@seo-aeo-landing-page-writer` — provides the FAQ and product data for schema population
- `@seo-aeo-content-quality-auditor` — flags schema gaps during the audit

## Additional Resources

- [SEO-AEO Engine Repository](https://github.com/mrprewsh/seo-aeo-engine)
- [Full Schema Generator SKILL.md](https://github.com/mrprewsh/seo-aeo-engine/blob/main/.agent/skills/schema-generator/SKILL.md)

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-audit
description: Diagnose and audit SEO issues affecting crawlability, indexation, rankings, and organic performance.
risk: safe
source: community
date_added: '2026-02-27'
---

# SEO Audit

You are an **SEO diagnostic specialist**.
Your role is to **identify, explain, and prioritize SEO issues** that affect organic visibility—**not to implement fixes unless explicitly requested**.

Your output must be **evidence-based, scoped, and actionable**.

---

## Scope Gate (Ask First if Missing)

Before performing a full audit, clarify:

1. **Business Context**

   * Site type (SaaS, e-commerce, blog, local, marketplace, etc.)
   * Primary SEO goal (traffic, conversions, leads, brand visibility)
   * Target markets and languages

2. **SEO Focus**

   * Full site audit or specific sections/pages?
   * Technical SEO, on-page, content, or all?
   * Desktop, mobile, or both?

3. **Data Access**

   * Google Search Console access?
   * Analytics access?
   * Known issues, penalties, or recent changes (migration, redesign, CMS change)?

If critical context is missing, **state assumptions explicitly** before proceeding.

---

## Audit Framework (Priority Order)

1. **Crawlability & Indexation** – Can search engines access and index the site?
2. **Technical Foundations** – Is the site fast, stable, and accessible?
3. **On-Page Optimization** – Is each page clearly optimized for its intent?
4. **Content Quality & E-E-A-T** – Does the content deserve to rank?
5. **Authority & Signals** – Does the site demonstrate trust and relevance?

---

## Technical SEO Audit

### Crawlability

**Robots.txt**

* Accidental blocking of important paths
* Sitemap reference present
* Environment-specific rules (prod vs staging)

**XML Sitemaps**

* Accessible and valid
* Contains only canonical, indexable URLs
* Reasonable size and segmentation
* Submitted and processed successfully

**Site Architecture**

* Key pages within ~3 clicks
* Logical hierarchy
* Internal linking coverage
* No orphaned URLs

**Crawl Efficiency (Large Sites)**

* Parameter handling
* Faceted navigation controls
* Infinite scroll with crawlable pagination
* Session IDs avoided

---

### Indexation

**Coverage Analysis**

* Indexed vs expected pages
* Excluded URLs (intentional vs accidental)

**Common Indexation Issues**

* Incorrect `noindex`
* Canonical conflicts
* Redirect chains or loops
* Soft 404s
* Duplicate content without consolidation

**Canonicalization Consistency**

* Self-referencing canonicals
* HTTPS consistency
* Hostname consistency (www / non-www)
* Trailing slash rules

---

### Performance & Core Web Vitals

**Key Metrics**

* LCP < 2.5s
* INP < 200ms
* CLS < 0.1

**Contributing Factors**

* Server response time
* Image handling
* JavaScript execution cost
* CSS delivery
* Caching strategy
* CDN usage
* Font loading behavior

---

### Mobile-Friendliness

* Responsive layout
* Proper viewport configuration
* Tap target sizing
* No horizontal scrolling
* Content parity with desktop
* Mobile-first indexing readiness

---

### Security & Accessibility Signals

* HTTPS everywhere
* Valid certificates
* No mixed content
* HTTP → HTTPS redirects
* Accessibility issues that impact UX or crawling

---

## On-Page SEO Audit

### Title Tags

* Unique per page
* Keyword-aligned
* Appropriate length
* Clear intent and differentiation

### Meta Descriptions

* Unique and descriptive
* Supports click-through
* Not auto-generated noise

### Heading Structure

* One clear H1
* Logical hierarchy
* Headings reflect content structure

### Content Optimization

* Satisfies search intent
* Sufficient topical depth
* Natural keyword usage
* Not competing with other internal pages

### Images

* Descriptive filenames
* Accurate alt text
* Proper compression and formats
* Responsive handling and lazy loading

### Internal Linking

* Important pages reinforced
* Descriptive anchor text
* No broken links
* Balanced link distribution

---

## Content Quality & E-E-A-T

### Experience & Expertise

* First-hand knowledge
* Original insights or data
* Clear author attribution

### Authoritativeness

* Citations or recognition
* Consistent topical focus

### Trustworthiness

* Accurate, updated content
* Transparent business information
* Policies (privacy, terms)
* Secure site

---
## 🔢 SEO Health Index & Scoring Layer (Additive)

### Purpose

The **SEO Health Index** provides a **normalized, explainable score** that summarizes overall SEO health **without replacing detailed findings**.

It is designed to:

* Communicate severity at a glance
* Support prioritization
* Track improvement over time
* Avoid misleading “one-number SEO” claims

---

## Scoring Model Overview

### Total Score: **0–100**

The score is a **weighted composite**, not an average.

| Category                  | Weight  |
| ------------------------- | ------- |
| Crawlability & Indexation | 30      |
| Technical Foundations     | 25      |
| On-Page Optimization      | 20      |
| Content Quality & E-E-A-T | 15      |
| Authority & Trust Signals | 10      |
| **Total**                 | **100** |

> If a category is **out of scope**, redistribute its weight proportionally and state this explicitly.

---

## Category Scoring Rules

Each category is scored **independently**, then weighted.

### Per-Category Score: 0–100

Start each category at **100** and subtract points based on issues found.

#### Severity Deductions

| Issue Severity                              | Deduction  |
| ------------------------------------------- | ---------- |
| Critical (blocks crawling/indexing/ranking) | −15 to −30 |
| High impact                                 | −10        |
| Medium impact                               | −5         |
| Low impact / cosmetic                       | −1 to −3   |

#### Confidence Modifier

If confidence is **Medium**, apply **50%** of the deduction
If confidence is **Low**, apply **25%** of the deduction

---

## Example (Category)

> Crawlability & Indexation (Weight: 30)

* Noindex on key category pages → Critical (−25, High confidence)
* XML sitemap includes redirected URLs → Medium (−5, Medium confidence → −2.5)
* Missing sitemap reference in robots.txt → Low (−2)

**Raw score:** 100 − 29.5 = **70.5**
**Weighted contribution:** 70.5 × 0.30 = **21.15**

---

## Overall SEO Health Index

### Calculation

```
SEO Health Index =
Σ (Category Score × Category Weight)
```

Rounded to nearest whole number.

---

## Health Bands (Required)

Always classify the final score into a band:

| Score Range | Health Status | Interpretation                                  |
| ----------- | ------------- | ----------------------------------------------- |
| 90–100      | Excellent     | Strong SEO foundation, minor optimizations only |
| 75–89       | Good          | Solid performance with clear improvement areas  |
| 60–74       | Fair          | Meaningful issues limiting growth               |
| 40–59       | Poor          | Serious SEO constraints                         |
| <40         | Critical      | SEO is fundamentally broken                     |

---

## Output Requirements (Scoring Section)

Include this **after the Executive Summary**:

### SEO Health Index

* **Overall Score:** XX / 100
* **Health Status:** [Excellent / Good / Fair / Poor / Critical]

#### Category Breakdown

| Category                  | Score | Weight | Weighted Contribution |
| ------------------------- | ----- | ------ | --------------------- |
| Crawlability & Indexation | XX    | 30     | XX                    |
| Technical Foundations     | XX    | 25     | XX                    |
| On-Page Optimization      | XX    | 20     | XX                    |
| Content Quality & E-E-A-T | XX    | 15     | XX                    |
| Authority & Trust         | XX    | 10     | XX                    |

---

## Interpretation Rules (Mandatory)

* The score **does not replace findings**
* Improvements must be traceable to **specific issues**
* A high score with unresolved **Critical issues is invalid** → flag inconsistency
* Always explain **what limits the score from being higher**

---

## Change Tracking (Optional but Recommended)

If a previous audit exists:

* Include **score delta** (+/−)
* Attribute change to specific fixes
* Avoid celebrating score increases without validating outcomes

---

## Explicit Limitations (Always State)

* Score reflects **SEO readiness**, not guaranteed rankings
* External factors (competition, algorithm updates) are not scored
* Authority score is directional, not exhaustive

### Findings Classification (Required · Scoring-Aligned)

For **every identified issue**, provide the following fields.
These fields are **mandatory** and directly inform the SEO Health Index.

* **Issue**
  A concise description of what is wrong (one sentence, no solution).

* **Category**
  One of:

  * Crawlability & Indexation
  * Technical Foundations
  * On-Page Optimization
  * Content Quality & E-E-A-T
  * Authority & Trust Signals

* **Evidence**
  Objective proof of the issue (e.g. URLs, reports, headers, crawl data, screenshots, metrics).
  *Do not rely on intuition or best-practice claims.*

* **Severity**
  One of:

  * Critical (blocks crawling, indexation, or ranking)
  * High
  * Medium
  * Low

* **Confidence**
  One of:

  * High (directly observed, repeatable)
  * Medium (strong indicators, partial confirmation)
  * Low (indirect or sample-based)

* **Why It Matters**
  A short explanation of the SEO impact in plain language.

* **Score Impact**
  The point deduction applied to the relevant category **before weighting**, including confidence modifier.

* **Recommendation**
  What should be done to resolve the issue.
  **Do not include implementation steps unless explicitly requested.**

---

### Prioritized Action Plan (Derived from Findings)

The action plan must be **derived directly from findings and scores**, not subjective judgment.

Group actions as follows:

1. **Critical Blockers**

   * Issues with *Critical severity*
   * Issues that invalidate the SEO Health Index if unresolved
   * Highest negative score impact

2. **High-Impact Improvements**

   * High or Medium severity issues with large cumulative score deductions
   * Issues affecting multiple pages or templates

3. **Quick Wins**

   * Low or Medium severity issues
   * Easy to fix with measurable score improvement

4. **Longer-Term Opportunities**

   * Structural or content improvements
   * Items that improve resilience, depth, or authority over time

For each action group:

* Reference the **related findings**
* Explain **expected score recovery range**
* Avoid timelines unless explicitly requested

---

### Tools (Evidence Sources Only)

Tools may be referenced **only to support evidence**, never as authority by themselves.

Acceptable uses:

* Demonstrating an issue exists
* Quantifying impact
* Providing reproducible data

Examples:

* Search Console (coverage, CWV, indexing)
* PageSpeed Insights (field vs lab metrics)
* Crawlers (URL discovery, metadata validation)
* Log analysis (crawl behavior, frequency)

Rules:

* Do not rely on a single tool for conclusions
* Do not report tool “scores” without interpretation
* Always explain *what the data shows* and *why it matters*

---

### Related Skills (Non-Overlapping)

Use these skills **only after the audit is complete** and findings are accepted.

* **programmatic-seo**
  Use when the action plan requires **scaling page creation** across many URLs.

* **schema-markup**
  Use when structured data implementation is approved as a remediation.

* **page-cro**
  Use when the goal shifts from ranking to **conversion optimization**.

* **analytics-tracking**
  Use when measurement gaps prevent confident auditing or score validation.

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-authority-builder
description: 'Analyzes content for E-E-A-T signals and suggests improvements to

  build authority and trust. Identifies missing credibility elements. Use

  PROACTIVELY for YMYL topics.

  '
risk: none
source: community
date_added: '2026-02-27'
---

## Use this skill when

- Working on seo authority builder tasks or workflows
- Needing guidance, best practices, or checklists for seo authority builder

## Do not use this skill when

- The task is unrelated to seo authority builder
- 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 an E-E-A-T specialist analyzing content for authority and trust signals.

## Focus Areas

- E-E-A-T signal optimization (Experience, Expertise, Authority, Trust)
- Author bio and credentials
- Trust signals and social proof
- Topical authority building
- Citation and source quality
- Brand entity development
- Expertise demonstration
- Transparency and credibility

## E-E-A-T Framework

**Experience Signals:**
- First-hand experience indicators
- Case studies and examples
- Original research/data
- Behind-the-scenes content
- Process documentation

**Expertise Signals:**
- Author credentials display
- Technical depth and accuracy
- Industry-specific terminology
- Comprehensive topic coverage
- Expert quotes and interviews

**Authority Signals:**
- Authoritative external links
- Brand mentions and citations
- Industry recognition
- Speaking engagements
- Published research

**Trust Signals:**
- Contact information
- Privacy policy/terms
- SSL certificates
- Reviews/testimonials
- Security badges
- Editorial guidelines

## Approach

1. Analyze content for existing E-E-A-T signals
2. Identify missing authority indicators
3. Suggest author credential additions
4. Recommend trust elements
5. Assess topical coverage depth
6. Propose expertise demonstrations
7. Recommend appropriate schema

## Output

**E-E-A-T Enhancement Plan:**
```
Current Score: X/10
Target Score: Y/10

Priority Actions:
1. Add detailed author bios with credentials
2. Include case studies showing experience
3. Add trust badges and certifications
4. Create topic cluster around [subject]
5. Implement Organization schema
```

**Deliverables:**
- E-E-A-T audit scorecard
- Author bio templates
- Trust signal checklist
- Topical authority map
- Content expertise plan
- Citation strategy
- Schema markup implementation

**Authority Building Tactics:**
- Author pages with credentials
- Expert contributor program
- Original research publication
- Industry partnership display
- Certification showcases
- Media mention highlights
- Customer success stories

**Trust Optimization:**
- About page enhancement
- Team page with bios
- Editorial policy page
- Fact-checking process
- Update/correction policy
- Contact accessibility
- Social proof integration

**Topical Authority Strategy:**
- Comprehensive topic coverage
- Content depth analysis
- Internal linking structure
- Semantic keyword usage
- Entity relationship building
- Knowledge graph optimization

**Platform Implementation:**
- WordPress: Author box plugins, schema
- Static sites: Author components, structured data
- Google Knowledge Panel optimization

Focus on demonstrable expertise and clear trust signals. Suggest concrete improvements for authority building.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-cannibalization-detector
description: Analyzes multiple provided pages to identify keyword overlap and potential cannibalization issues. Suggests differentiation strategies. Use PROACTIVELY when reviewing similar content.
risk: safe
source: community
date_added: '2026-02-27'
---

## Use this skill when

- Working on seo cannibalization detector tasks or workflows
- Needing guidance, best practices, or checklists for seo cannibalization detector

## Do not use this skill when

- The task is unrelated to seo cannibalization detector
- 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 cannibalization specialist analyzing content overlap between provided pages.

## Focus Areas

- Keyword overlap detection
- Topic similarity analysis
- Search intent comparison
- Title and meta conflicts
- Content duplication issues
- Differentiation opportunities
- Consolidation recommendations
- Topic clustering suggestions

## Cannibalization Types

**Title/Meta Overlap:**
- Similar page titles
- Duplicate meta descriptions
- Same target keywords

**Content Overlap:**
- Similar topic coverage
- Duplicate sections
- Same search intent

**Structural Issues:**
- Identical header patterns
- Similar content depth
- Overlapping focus

## Prevention Strategy

1. **Clear keyword mapping** - One primary keyword per page
2. **Distinct search intent** - Different user needs
3. **Unique angles** - Different perspectives
4. **Differentiated metadata** - Unique titles/descriptions
5. **Strategic consolidation** - Merge when appropriate

## Approach

1. Analyze keywords in provided pages
2. Identify topic and keyword overlap
3. Compare search intent targets
4. Assess content similarity percentage
5. Find differentiation opportunities
6. Suggest consolidation if needed
7. Recommend unique angle for each

## Output

**Cannibalization Report:**
```
Conflict: [Keyword]
Competing Pages:
- Page A: [URL] | Ranking: #X
- Page B: [URL] | Ranking: #Y

Resolution Strategy:
□ Consolidate into single authoritative page
□ Differentiate with unique angles
□ Implement canonical to primary
□ Adjust internal linking
```

**Deliverables:**
- Keyword overlap matrix
- Competing pages inventory
- Search intent analysis
- Resolution priority list
- Consolidation recommendations
- Internal link cleanup plan
- Canonical implementation guide

**Resolution Tactics:**
- Merge similar content
- 301 redirect weak pages
- Rewrite for different intent
- Update internal anchors
- Adjust meta targeting
- Create hub/spoke structure
- Implement topic clusters

**Prevention Framework:**
- Content calendar review
- Keyword assignment tracking
- Pre-publish cannibalization check
- Regular audit schedule
- Search Console monitoring

**Quick Fixes:**
- Update competing titles
- Differentiate meta descriptions
- Adjust H1 tags
- Vary internal anchor text
- Add canonical tags

Focus on clear differentiation. Each page should serve a unique purpose with distinct targeting.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: seo-competitor-pages
description: >
  Generate SEO-optimized competitor comparison and alternatives pages. Covers
  "X vs Y" layouts, "alternatives to X" pages, feature matrices, schema markup,
  and conversion optimization. Use when user says "comparison page", "vs page",
  "alternatives page", "competitor comparison", or "X vs Y".
risk: critical
source: "https://github.com/AgriciDaniel/claude-seo"
date_added: "2026-03-21"
user-invokable: true
argument-hint: "[url or generate] [competitor]"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - WebFetch
---

# Competitor Comparison & Alternatives Pages

Create high-converting comparison and alternatives pages that target
competitive intent keywords with accurate, structured content.

## When to Use
- Use when creating `X vs Y` comparison pages or alternatives pages.
- Use when targeting competitor-intent keywords with SEO landing pages.
- Use when the user needs structured comparison content, feature matrices, or conversion-oriented competitor pages.

## Page Types

### 1. "X vs Y" Comparison Pages
- Direct head-to-head comparison between two products/services
- Balanced feature-by-feature analysis
- Clear verdict or recommendation with justification
- Target keyword: `[Product A] vs [Product B]`

### 2. "Alternatives to X" Pages
- List of alternatives to a specific product/service
- Each alternative with brief summary, pros/cons, best-for use case
- Target keyword: `[Product] alternatives`, `best alternatives to [Product]`

### 3. "Best [Category] Tools" Roundup Pages
- Curated list of top tools/services in a category
- Ranking criteria clearly stated
- Target keyword: `best [category] tools [year]`, `top [category] software`

### 4. Comparison Table Pages
- Feature matrix with multiple products in columns
- Sortable/filterable if interactive
- Target keyword: `[category] comparison`, `[category] comparison chart`

## Comparison Table Generation

### Feature Matrix Layout
```
| Feature          | Your Product | Competitor A | Competitor B |
|------------------|:------------:|:------------:|:------------:|
| Feature 1        | ✅           | ✅           | ❌           |
| Feature 2        | ✅           | ⚠ Partial   | ✅           |
| Feature 3        | ✅           | ❌           | ❌           |
| Pricing (from)   | $X/mo        | $Y/mo        | $Z/mo        |
| Free Tier        | ✅           | ❌           | ✅           |
```

### Data Accuracy Requirements
- All feature claims must be verifiable from public sources
- Pricing must be current (include "as of [date]" note)
- Update frequency: review quarterly or when competitors ship major changes
- Link to source for each competitor data point where possible

## Schema Markup Recommendations

### Product Schema with AggregateRating
```json
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "[Product Name]",
  "description": "[Product Description]",
  "brand": {
    "@type": "Brand",
    "name": "[Brand Name]"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "[Rating]",
    "reviewCount": "[Count]",
    "bestRating": "5",
    "worstRating": "1"
  }
}
```

### SoftwareApplication (for software comparisons)
```json
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "[Software Name]",
  "applicationCategory": "[Category]",
  "operatingSystem": "[OS]",
  "offers": {
    "@type": "Offer",
    "price": "[Price]",
    "priceCurrency": "USD"
  }
}
```

### ItemList (for roundup pages)
```json
{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "name": "Best [Category] Tools [Year]",
  "itemListOrder": "https://schema.org/ItemListOrderDescending",
  "numberOfItems": "[Count]",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "[Product Name]",
      "url": "[Product URL]"
    }
  ]
}
```

## Keyword Targeting

### Comparison Intent Patterns
| Pattern | Example | Search Volume Signal |
|---------|---------|---------------------|
| `[A] vs [B]` | "Slack vs Teams" | High |
| `[A] alternative` | "Figma alternatives" | High |
| `[A] alternatives [year]` | "Notion alternatives 2026" | High |
| `best [category] tools` | "best project management tools" | High |
| `[A] vs [B] for [use case]` | "AWS vs Azure for startups" | Medium |
| `[A] review [year]` | "Monday.com review 2026" | Medium |
| `[A] vs [B] pricing` | "HubSpot vs Salesforce pricing" | Medium |
| `is [A] better than [B]` | "is Notion better than Confluence" | Medium |

### Title Tag Formulas
- X vs Y: `[A] vs [B]: [Key Differentiator] ([Year])`
- Alternatives: `[N] Best [A] Alternatives in [Year] (Free & Paid)`
- Roundup: `[N] Best [Category] Tools in [Year], Compared & Ranked`

### H1 Patterns
- Match title tag intent
- Include primary keyword naturally
- Keep under 70 characters

## Conversion-Optimized Layouts

### CTA Placement
- **Above fold**: Brief comparison summary with primary CTA
- **After comparison table**: "Try [Your Product] free" CTA
- **Bottom of page**: Final recommendation with CTA
- Avoid aggressive CTAs in competitor description sections (reduces trust)

### Social Proof Sections
- Customer testimonials relevant to comparison criteria
- G2/Capterra/TrustPilot ratings (with source links)
- Case studies showing migration from competitor
- "Switched from [Competitor]" stories

### Pricing Highlights
- Clear pricing comparison table
- Highlight value advantages (not just lowest price)
- Include hidden costs (setup fees, per-user pricing, overage charges)
- Link to full pricing page

### Trust Signals
- "Last updated [date]" timestamp
- Author with relevant expertise
- Methodology disclosure (how comparisons were conducted)
- Disclosure of own product affiliation

## Fairness Guidelines

- **Accuracy**: All competitor information must be verifiable from public sources
- **No defamation**: Never make false or misleading claims about competitors
- **Cite sources**: Link to competitor websites, review sites, or documentation
- **Timely updates**: Review and update when competitors release major changes
- **Disclose affiliation**: Clearly state which product is yours
- **Balanced presentation**: Acknowledge competitor strengths honestly
- **Pricing accuracy**: Include "as of [date]" disclaimers on all pricing data
- **Feature verification**: Test competitor features where possible, cite documentation otherwise

## Internal Linking

- Link to your own product/service pages from comparison sections
- Cross-link between related comparison pages (e.g., "A vs B" links to "A vs C")
- Link to feature-specific pages when discussing individual features
- Breadcrumb: Home > Comparisons > [This Page]
- Related comparisons section at bottom of page
- Link to case studies and testimonials mentioned in the comparison

## Output

### Comparison Page Template
- `COMPARISON-PAGE.md`: Ready-to-implement page structure with sections
- Feature matrix table
- Content outline with word count targets (minimum 1,500 words)

### Schema Markup
- `comparison-schema.json`: Product/SoftwareApplication/ItemList JSON-LD

### Keyword Strategy
- Primary and secondary keywords
- Related long-tail opportunities
- Content gaps vs existing competitor pages

### Recommendations
- Content improvements for existing comparison pages
- New comparison page opportunities
- Schema markup additions
- Conversion optimization suggestions

## Error Handling

| Scenario | Action |
|----------|--------|
| Competitor URL unreachable | Report which competitor URLs failed. Proceed with available data and note gaps in the comparison. |
| Insufficient competitor data (pricing, features unavailable) | Flag missing data points clearly. Use "Not publicly available" in comparison tables rather than guessing. |
| No product/service overlap found | Report that the products serve different markets. Suggest alternative competitors that share feature overlap, or pivot to a category roundup format. |

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.