diagnose-seo
Structured diagnostic for technical SEO problems. Use when the user asks about crawl issues, indexation problems, why pages aren't being indexed, robots.txt questions, canonical errors, sitemap issues, rendering problems, or general technical SEO troubleshooting. For Core Web Vitals and page speed, see audit-speed.
- Installs
- 2.1K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/calm-north/seojuice-skills --skill diagnose-seo- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads diagnose-seo automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Diagnose SEO
Structured diagnostic framework for crawl issues, canonicalization errors, indexation problems, and rendering failures.
Diagnostic Approach
Technical SEO problems fall into four categories. Diagnose in this order — each layer depends on the previous one working correctly:
- Crawlability — Can search engines find and access the pages?
- Indexability — Are the pages allowed to be indexed?
- Renderability — Can search engines see the full content?
- Signals — Are the right signals (titles, structured data, links) in place?
Layer 1: Crawlability
Check these in order:
robots.txt
- Fetch
[domain]/robots.txtand review the rules - Look for overly broad
Disallowrules blocking important paths - Verify
Sitemap:directive points to the correct sitemap URL - Check for different rules per user-agent (Googlebot vs others)
Common mistakes:
Disallow: /blocking the entire site (often left from staging)- Blocking CSS/JS files that Googlebot needs for rendering
- Blocking API or AJAX endpoints that load dynamic content
- Staging robots.txt accidentally deployed to production
XML Sitemap
- Fetch the sitemap URL(s) and check:
- Does it return 200? Is it valid XML?
- Does it list all important pages?
- Does it exclude pages that shouldn't be indexed (404s, redirects, noindex pages)?
- Are
<lastmod>dates accurate and recent? - For large sites: is there a sitemap index?
Site Architecture
- Pages should be reachable within 3 clicks from the homepage
- Check for orphan pages (no internal links pointing to them)
- Check for redirect chains (page A → B → C — should be A → C)
- Check for redirect loops
Server Response
- Do all important pages return HTTP 200?
- Check for unexpected 301/302 redirects
- Check for soft 404s (page returns 200 but shows "not found" content)
- Verify HTTPS is enforced (HTTP should 301 to HTTPS)
Layer 2: Indexability
Meta Robots / X-Robots-Tag
- Check for
<meta name="robots" content="noindex">on pages that should be indexed - Check HTTP headers for
X-Robots-Tag: noindex - Common cause: CMS accidentally applying noindex to pagination, tag pages, or new pages
Canonical Tags
- Every page should have a
<link rel="canonical">pointing to itself (self-referencing canonical) - Check for canonical tags pointing to wrong pages (common in paginated content, filtered URLs)
- Check for conflicting signals: canonical says page A, but noindex is set, or the page redirects
Canonical diagnosis checklist:
- Does the canonical URL match the actual URL?
- Is the canonical URL accessible (returns 200)?
- Does the canonical URL have the same content?
- Is there only one canonical tag on the page?
Duplicate Content
- Check for the same content accessible at multiple URLs:
- With and without trailing slash (
/pagevs/page/) - With and without
www(example.comvswww.example.com) - HTTP vs HTTPS
- URL parameters creating duplicate pages (
?sort=price,?page=1)
- With and without trailing slash (
- Each duplicate set needs one canonical URL; all others should redirect or use canonical tags
Layer 3: Renderability
JavaScript Rendering
- Does the page content appear in the raw HTML source? Or is it loaded via JavaScript?
- If JS-rendered: does Googlebot see the full content? (Use URL Inspection tool in Search Console)
- Check for content hidden behind click events, tabs, or accordions
- Check for lazy-loaded content that only appears on scroll
Core Content Visibility
- Is the main content in the initial HTML? Or loaded async after page load?
- Are important elements (titles, headings, product details) in the DOM on first render?
- Check for content that requires login or cookies to view
Layer 4: Signals
Title Tags
- Every page has a unique
<title> - Title includes the primary keyword
- Under 60 characters (to avoid truncation in SERPs)
- Descriptive and click-worthy
Meta Descriptions
- Every important page has a meta description
- 150-160 characters
- Includes target keyword and a value proposition
- Unique per page
Heading Structure
- One H1 per page containing the primary keyword
- Logical heading hierarchy (H1 → H2 → H3, no skips)
- Headings describe section content (not decorative)
Structured Data
- Check for JSON-LD structured data appropriate to the page type
- Validate with Google's Rich Results Test
- Common types: Article, Product, FAQ, HowTo, BreadcrumbList, Organization
Hreflang (multilingual sites)
- Check for correct
hreflangtags linking language variants - Verify reciprocal tags (page A points to B, B points back to A)
- Check for
x-defaulttag
Output Format
Technical SEO Diagnosis: [domain]
Summary
- Critical issues: [count]
- Warnings: [count]
- Passed checks: [count]
Findings by Layer
For each issue found:
| Layer | Issue | Severity | Affected Pages | Fix |
|---|---|---|---|---|
| Crawlability | robots.txt blocks /blog/ | Critical | All blog pages | Remove Disallow: /blog/ from robots.txt |
| Indexability | Missing canonical tags | Warning | 15 pages | Add self-referencing canonicals |
| ... | ... | ... | ... | ... |
Priority Fix List
Ordered by impact:
- [Critical fix] — affects [n] pages, blocks [crawling/indexing/ranking]
- [Warning fix] — affects [n] pages, reduces [signal quality]
- ...
Pro Tip: Run the free SEO Audit for a quick technical check, the Broken Link Checker to find dead links, and the Robots.txt Generator to fix crawl directives. SEOJuice MCP users can run
/seojuice:site-healthfor a full technical report and/seojuice:page-audit [domain] [url]to drill into specific pages.
FAQ
What does the diagnose-seo skill do?
Structured diagnostic for technical SEO problems. Use when the user asks about crawl issues, indexation problems, why pages aren't being indexed, robots.txt questions, canonical errors, sitemap issues, rendering problems, or general technical SEO troubleshooting. For Core Web Vitals and page speed, see audit-speed.
How do I install diagnose-seo?
Run npx skills add https://github.com/calm-north/seojuice-skills --skill diagnose-seo in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/diagnose-seo/ (personal) or .claude/skills/diagnose-seo/ (project).
Which AI agents can use diagnose-seo?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is diagnose-seo safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains diagnose-seo?
It is published by calm-north in calm-north/seojuice-skills. It has 2,148 recorded installs.
More from calm-north/seojuice-skills
find-keywords
calm-north/seojuice-skills
Build a prioritized keyword list for a website, topic, or campaign. Use when the user asks about keyword research, finding keywords to target, building a keyword list, search demand, keyword difficulty, intent mapping, or which keywords to prioritize. For writing content around keywords, see brief. For grouping keywords into clusters, see build-clusters.
optimize-for-ai
calm-north/seojuice-skills
Optimize content for AI search engines — ChatGPT, Perplexity, Claude, Gemini, Google AI Overviews. Use when the user asks about AI SEO, AISO, getting cited by AI, appearing in AI answers, answer engine optimization, AEO, GEO, LLMO, AI Overviews, zero-click search, or how to appear in ChatGPT/Perplexity results. For traditional SEO, see diagnose-seo.
build-links
calm-north/seojuice-skills
Design a link building campaign with prospect identification, asset creation, and outreach strategy. Use when the user asks about link building, backlinks, domain authority, how to get backlinks, outreach campaigns, digital PR, guest posting, or link acquisition. For internal linking, see fix-linking.
brief
calm-north/seojuice-skills
Produce an editor-ready content brief for a target keyword or topic. Use when the user asks for a content brief, writing guidelines, article outline, SEO brief, what to include in a blog post, or how to structure content for a keyword. For choosing which topics to write about, see find-keywords. For a full site-wide SEO audit, see audit.
audit
calm-north/seojuice-skills
Run a comprehensive SEO audit on a website covering technical health, on-page optimization, content quality, and backlink profile. Use when the user asks for an SEO audit, site review, SEO health check, "what's wrong with my SEO", website analysis, or a full diagnostic of their site's search performance. For speed-specific issues, see audit-speed. For technical crawl/index issues only, see diagnose-seo.
rank-local
calm-north/seojuice-skills
Build a local SEO strategy covering Google Business Profile, local citations, reviews, and NAP consistency. Use when the user asks about local SEO, Google Business Profile, Google Maps ranking, local pack, NAP consistency, local citations, review strategy, or ranking for "[service] near me" searches.
Popular marketing & seo skills
reddit-automation
flowkit-labs/skills
Find Reddit threads where people are genuinely asking for what you offer, then draft short, genuinely helpful replies — disclosing your affiliation honestly and naming your product only when it truly answers the question. Two moves: discovery — scan the right subreddits for real needs (recommendation asks, expressed pain, competitor mentions) and rank the few threads where you can actually help; drafting — write from real experience, respect each community's self-promo rules, and keep a human in the loop to review and post. This markets on Reddit the honest way: contribute value, disclose who you are, never astroturf. Distilled from the playbook behind doany.ai's Reddit agent. Triggers on "find reddit opportunities", "reddit marketing", "reddit automation", "reply on reddit for my product", "reddit community engagement", "reddit lead gen", or any ask to turn Reddit threads into genuine, disclosed marketing replies.
twitter-automation
101-skills/superpowers
Automate Twitter/X with posting, engagement, and user management via inference.sh CLI. Apps: x/post-tweet, x/post-create (with media), x/post-like, x/post-retweet, x/dm-send, x/user-follow. Capabilities: post tweets, schedule content, like posts, retweet, send DMs, follow users, get profiles. Use for: social media automation, content scheduling, engagement bots, audience growth, X API. Triggers: twitter api, x api, tweet automation, post to twitter, twitter bot, social media automation, x automation, tweet scheduler, twitter integration, post tweet, twitter post, x post, send tweet
twitter-automation
magentosh/superpowers
Automate Twitter/X with posting, engagement, and user management via inference.sh CLI. Apps: x/post-tweet, x/post-create (with media), x/post-like, x/post-retweet, x/dm-send, x/user-follow. Capabilities: post tweets, schedule content, like posts, retweet, send DMs, follow users, get profiles. Use for: social media automation, content scheduling, engagement bots, audience growth, X API. Triggers: twitter api, x api, tweet automation, post to twitter, twitter bot, social media automation, x automation, tweet scheduler, twitter integration, post tweet, twitter post, x post, send tweet
twitter-automation
qu-skills/superpowers
Automate Twitter/X with posting, engagement, and user management via inference.sh CLI. Apps: x/post-tweet, x/post-create (with media), x/post-like, x/post-retweet, x/dm-send, x/user-follow. Capabilities: post tweets, schedule content, like posts, retweet, send DMs, follow users, get profiles. Use for: social media automation, content scheduling, engagement bots, audience growth, X API. Triggers: twitter api, x api, tweet automation, post to twitter, twitter bot, social media automation, x automation, tweet scheduler, twitter integration, post tweet, twitter post, x post, send tweet
product-launch-video
heygen-com/hyperframes
Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Site tours / showcases of a website route here too — the brief carries the show-it-as-is intent. Unclear → /hyperframes.
twitter-automation
skills-shell/superpowers
Automate Twitter/X with posting, engagement, and user management via inference.sh CLI. Apps: x/post-tweet, x/post-create (with media), x/post-like, x/post-retweet, x/dm-send, x/user-follow. Capabilities: post tweets, schedule content, like posts, retweet, send DMs, follow users, get profiles. Use for: social media automation, content scheduling, engagement bots, audience growth, X API. Triggers: twitter api, x api, tweet automation, post to twitter, twitter bot, social media automation, x automation, tweet scheduler, twitter integration, post tweet, twitter post, x post, send tweet