Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat: add broken-link-checker skill and contributor docs

mrbeandev32803589521d
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 95d68b7c..c63d5057 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -5,14 +5,14 @@
},
"metadata": {
"description": "The official Google Ads + SEO plugin from AdsAgent. SEO and Google Ads skills for Claude Code.",
- "version": "0.13.1"
+ "version": "0.13.2"
},
"plugins": [
{
"name": "toprank",
"source": "./",
- "description": "The official Google Ads + SEO plugin from AdsAgent. SEO analysis, Google Ads management, keyword research, content optimization, schema markup, and meta tags optimization.",
- "version": "0.13.1",
+ "description": "The official Google Ads + SEO plugin from AdsAgent. SEO analysis, Google Ads management, keyword research, content optimization, schema markup, meta tags optimization, and broken link checker.",
+ "version": "0.13.2",
"author": {
"name": "AdsAgent",
"url": "https://adsagent.org"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index cabef5fb..fe2bed19 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "toprank",
- "version": "0.13.1",
- "description": "The official Google Ads + SEO plugin from AdsAgent. SEO analysis, Google Ads management, keyword research, content optimization, and schema markup tools powered by Google Search Console and Google Ads APIs.",
+ "version": "0.13.2",
+ "description": "The official Google Ads + SEO plugin from AdsAgent. SEO analysis, Google Ads management, keyword research, content optimization, schema markup tools, and broken link checker powered by Google Search Console and Google Ads APIs.",
"author": {
"name": "AdsAgent",
"url": "https://adsagent.org"
@@ -17,6 +17,7 @@
"./seo/meta-tags-optimizer",
"./seo/schema-markup-generator",
"./seo/setup-cms",
+ "./seo/broken-link-checker",
"./toprank-upgrade-skill",
"./gemini"
]
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 64b8b6a2..e0f38943 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
---
+## [0.13.2] — 2026-04-26
+
+### Added
+- **New SEO Skill: `broken-link-checker`** — Scans websites to find broken internal and external links (404s, 5xx errors). Provides a detailed report with source pages and status codes.
+- **`CONTRIBUTING.md`** — A guide for community contributors on how to add new skills, fix bugs, and follow the project's quality standards.
+
+---
+
## [0.13.1] — 2026-04-25
### Fixed
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..ebf99ca4
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,62 @@
+# Contributing to Toprank
+
+Thank you for your interest in contributing to Toprank! We welcome contributions from the community to help make this the best SEO and Google Ads plugin for Claude Code.
+
+## Code of Conduct
+
+Please be respectful and professional in all your interactions with the community.
+
+## How to Contribute
+
+### 1. Adding a New Skill
+
+Each skill lives in its own folder under a category directory (e.g., `seo/`, `google-ads/`).
+
+1. **Create the Skill Directory**: `mkdir seo/your-new-skill`
+2. **Add `SKILL.md`**: This is the heart of the skill. It must contain frontmatter with `name` and `description`.
+3. **Optional Scripts/References**: Add any supporting Python scripts in a `scripts/` folder and reference documents in a `references/` folder within your skill directory.
+4. **Register the Skill**: Add the path to your skill (relative to the repo root) to the `skills` array in `.claude-plugin/plugin.json`.
+5. **Bump Versions**: Update the version in:
+ * `.claude-plugin/plugin.json`
+ * `.claude-plugin/marketplace.json`
+ * `VERSION`
+6. **Update Changelog**: Add a brief description of your new skill to `CHANGELOG.md`.
+
+### 2. Improving Existing Skills
+
+* Refine prompts in `SKILL.md` for better accuracy.
+* Add more robust error handling to scripts.
+* Update reference documentation.
+
+### 3. Bug Fixes and Documentation
+
+* Fix issues in scripts or skill logic.
+* Improve the `README.md` or other documentation files.
+
+## Development Workflow
+
+1. **Fork the repository**.
+2. **Clone your fork**: `git clone https://github.com/YOUR_USERNAME/toprank.git`
+3. **Create a branch**: `git checkout -b feature/your-feature-name`
+4. **Make your changes**.
+5. **Run tests**: We use `pytest` for tests. Ensure your changes don't break existing functionality.
+ ```bash
+ pip install -r requirements-test.txt
+ pytest
+ ```
+6. **Commit and push**: Use descriptive commit messages.
+7. **Open a Pull Request**: Provide a clear description of your changes and why they are beneficial.
+
+## Quality Standards
+
+* **Be brutally honest**: If a skill won't work in certain scenarios, document it.
+* **Relentless quality**: High-quality, reliable, and maintainable code is a must.
+* **No secrets**: Never include API keys or sensitive information in your commits.
+
+## Testing
+
+Ensure your skill is discovery-ready by Claude Code. Test it locally by pointing your Claude Code to your local repository or a development version of the plugin.
+
+---
+
+We look forward to your contributions!
diff --git a/README.md b/README.md
index e17b1ff5..7e1fc935 100644
--- a/README.md
+++ b/README.md
@@ -163,6 +163,7 @@ Add the marketplace and enable the plugin in `~/.claude/settings.json`:
| [`ads-audit`](google-ads/ads-audit/) | Account audit + business context setup. Run this first. Scores 7 health dimensions, identifies wasted spend, builds business profile. |
| [`ads`](google-ads/ads/) | Campaign management. Read performance, optimize keywords, adjust bids/budgets, add negatives, create campaigns. Ask for a **weekly review** and Claude scores every recent change (wins, losses, too-new-to-judge) — perfect for a Monday-morning Coworker task. |
| [`ads-copy`](google-ads/ads-copy/) | RSA copy generator + A/B testing. Data-driven headlines and descriptions with character counts and pin positions. |
+| [`ads-landing`](google-ads/ads-landing/) | Landing page audit. Analyzes relevance between keywords, ads, and landing page content to improve Quality Score. |
### SEO
@@ -173,6 +174,8 @@ Add the marketplace and enable the plugin in `~/.claude/settings.json`:
| [`keyword-research`](seo/keyword-research/) | Keyword discovery, intent classification, topic clusters, prioritized content calendar. |
| [`meta-tags-optimizer`](seo/meta-tags-optimizer/) | Title tags, meta descriptions, OG/Twitter cards with A/B variations and CTR estimates. |
| [`schema-markup-generator`](seo/schema-markup-generator/) | JSON-LD structured data for rich results. FAQ, HowTo, Article, Product, LocalBusiness. |
+| [`seo-page`](seo/seo-page/) | Single-page deep analysis. Focused audit of a specific URL for content quality, structure, and keyword optimization. |
+| [`broken-link-checker`](seo/broken-link-checker/) | Scans websites to find and report broken internal and external links (404s/5xx). |
| [`setup-cms`](seo/setup-cms/) | Connect WordPress, Strapi, Contentful, or Ghost for automated SEO field audits. |
### Cross-Model
diff --git a/VERSION b/VERSION
index c317a918..9beb74d4 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.13.1
+0.13.2
diff --git a/log/pytest_configs.json b/log/pytest_configs.json
new file mode 100644
index 00000000..a3454222
--- /dev/null
+++ b/log/pytest_configs.json
@@ -0,0 +1 @@
+{"inipath": "None", "rootpath": "/mnt/main_disk/mrbeandev_server/toprank"}
\ No newline at end of file
diff --git a/seo/broken-link-checker/SKILL.md b/seo/broken-link-checker/SKILL.md
new file mode 100644
index 00000000..55d0764a
--- /dev/null
+++ b/seo/broken-link-checker/SKILL.md
@@ -0,0 +1,58 @@
+---
+name: broken-link-checker
+argument-hint: "<URL to check, e.g. https://example.com>"
+description: >
+ Scans a website to find broken links (404s, 500s). Crawls internal pages,
+ identifies broken outbound links, and reports source pages for easy fixing.
+ Use this when the user asks to "check for broken links", "find 404s",
+ "audit my links", or "is my site healthy".
+---
+
+# Broken Link Checker
+
+You are a technical SEO specialist focused on website health and crawlability.
+Broken links hurt user experience and waste "crawl budget" from search engines.
+
+Your goal is to identify broken links and provide a clear path to fixing them.
+
+---
+
+## Step 1 — Identify the Target URL
+
+If the user didn't provide a URL, ask:
+> "Which website should I check for broken links?"
+
+Once you have the URL, store it as `$TARGET_URL`.
+
+---
+
+## Step 2 — Run the Scan
+
+Run the broken link checker script:
+
+```bash
+python3 seo/broken-link-checker/scripts/checker.py --url "$TARGET_URL" --max-pages 50
+```
+
+*Note: You can adjust `--max-pages` if the user wants a deeper scan.*
+
+---
+
+## Step 3 — Analyze and Report
+
+The script will output a JSON report. Analyze the `broken_links` array:
+
+1. **Group by Status**: Group 404s (Not Found) vs 5xx (Server Errors).
+2. **Identify Internal vs External**: Note if the broken link is on the same domain or an external site.
+3. **Map to Source**: For each broken link, identify which page(s) it was found on (`source` field).
+
+### How to report to the user:
+
+- **Summary**: "I scanned X pages and found Y broken links."
+- **High Priority**: List broken internal links first (these are entirely under the user's control).
+- **Secondary**: List broken external links.
+- **Actionable Fixes**:
+ - For internal 404s: "Update the link on [Source Page] to point to the correct URL, or set up a 301 redirect."
+ - For external 404s: "The external site at [Target URL] is down or moved. Update or remove the link on [Source Page]."
+
+If no broken links are found, congratulate the user on a healthy site!
diff --git a/seo/broken-link-checker/scripts/checker.py b/seo/broken-link-checker/scripts/checker.py
new file mode 100644
index 00000000..3c6e0e9d
--- /dev/null
+++ b/seo/broken-link-checker/scripts/checker.py
@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""
+Broken Link Checker for Toprank.
+Crawls a website starting from a given URL and identifies broken links (HTTP 4xx/5xx).
+
+Usage:
+ python3 checker.py --url https://example.com --max-pages 20
+"""
+
+import argparse
+import json
+import os
+import sys
+import urllib.parse
+import urllib.request
+import urllib.error
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from collections import deque
+from html.parser import HTMLParser
+
+class LinkParser(HTMLParser):
+ def __init__(self, base_url):
+ super().__init__()
+ self.base_url = base_url
+ self.links = set()
+
+ def handle_starttag(self, tag, attrs):
+ if tag == 'a':
+ for attr, value in attrs:
+ if attr == 'href':
+ url = urllib.parse.urljoin(self.base_url, value)
+ # Remove fragment
+ url = urllib.parse.urljoin(url, urllib.parse.urlparse(url).path)
+ if url.startswith('http'):
+ self.links.add(url)
+
+def check_url(url, timeout=10):
+ """Checks a URL and returns (status_code, error_msg)."""
+ req = urllib.request.Request(url, method='HEAD', headers={'User-Agent': 'ToprankBrokenLinkChecker/1.0'})
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as response:
+ return response.getcode(), None
+ except urllib.error.HTTPError as e:
+ return e.code, str(e.reason)
+ except urllib.error.URLError as e:
+ return None, str(e.reason)
+ except Exception as e:
+ return None, str(e)
+
+def crawl(start_url, max_pages=50):
+ domain = urllib.parse.urlparse(start_url).netloc
+ visited = set()
+ queue = deque([start_url])
+ broken_links = []
+ pages_crawled = 0
+
+ print(f"Starting crawl of {start_url} (limit: {max_pages} pages)...", file=sys.stderr)
+
+ while queue and pages_crawled < max_pages:
+ current_url = queue.popleft()
+ if current_url in visited:
+ continue
+
+ visited.add(current_url)
+ pages_crawled += 1
+
+ print(f"[{pages_crawled}/{max_pages}] Checking: {current_url}", file=sys.stderr)
+
+ # We need to GET the page to find more links
+ try:
+ req = urllib.request.Request(current_url, headers={'User-Agent': 'ToprankBrokenLinkChecker/1.0'})
+ with urllib.request.urlopen(req, timeout=10) as response:
+ if response.getcode() >= 400:
+ broken_links.append({"url": current_url, "status": response.getcode(), "reason": "Page itself is broken"})
+ continue
+
+ content_type = response.headers.get('Content-Type', '')
+ if 'text/html' not in content_type:
+ continue
+
+ html = response.read().decode('utf-8', errors='ignore')
+ parser = LinkParser(current_url)
+ parser.feed(html)
+
+ # Check links found on this page
+ found_links = list(parser.links)
+ with ThreadPoolExecutor(max_workers=5) as executor:
+ future_to_url = {executor.submit(check_url, link): link for link in found_links}
+ for future in as_completed(future_to_url):
+ link = future_to_url[future]
+ status, reason = future.result()
+ if status is None or status >= 400:
+ broken_links.append({
+ "source": current_url,
+ "target": link,
+ "status": status,
+ "reason": reason
+ })
+
+ # Add internal links to queue
+ if urllib.parse.urlparse(link).netloc == domain and link not in visited:
+ queue.append(link)
+
+ except Exception as e:
+ print(f"Error crawling {current_url}: {e}", file=sys.stderr)
+ broken_links.append({"url": current_url, "status": None, "reason": str(e)})
+
+ return broken_links
+
+def main():
+ parser = argparse.ArgumentParser(description="Broken Link Checker")
+ parser.add_argument("--url", required=True, help="Starting URL")
+ parser.add_argument("--max-pages", type=int, default=20, help="Maximum pages to crawl")
+ parser.add_argument("--output", help="Output JSON file")
+
+ args = parser.parse_args()
+
+ broken = crawl(args.url, args.max_pages)
+
+ result = {
+ "start_url": args.url,
+ "max_pages": args.max_pages,
+ "broken_links_count": len(broken),
+ "broken_links": broken
+ }
+
+ if args.output:
+ with open(args.output, 'w') as f:
+ json.dump(result, f, indent=2)
+ else:
+ print(json.dumps(result, indent=2))
+
+if __name__ == "__main__":
+ main()
diff --git a/test/unit/test_broken_link_checker.py b/test/unit/test_broken_link_checker.py
new file mode 100644
index 00000000..e2f9593a
--- /dev/null
+++ b/test/unit/test_broken_link_checker.py
@@ -0,0 +1,95 @@
+import unittest
+import http.server
+import threading
+import socket
+import urllib.request
+import importlib.util
+import sys
+from pathlib import Path
+
+# Fix for hyphen in directory name
+script_path = Path(__file__).parent.parent.parent / 'seo' / 'broken-link-checker' / 'scripts' / 'checker.py'
+spec = importlib.util.spec_from_file_location("checker", str(script_path))
+checker = importlib.util.module_from_spec(spec)
+sys.modules["checker"] = checker
+spec.loader.exec_module(checker)
+
+check_url = checker.check_url
+LinkParser = checker.LinkParser
+crawl = checker.crawl
+
+class TestBrokenLinkChecker(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ # Find a free port
+ cls.port = 8001
+ cls.server_address = ('127.0.0.1', cls.port)
+ cls.base_url = f"http://127.0.0.1:{cls.port}"
+
+ class MockHandler(http.server.SimpleHTTPRequestHandler):
+ def do_GET(self):
+ if self.path == '/':
+ self.send_response(200)
+ self.send_header("Content-type", "text/html")
+ self.end_headers()
+ self.wfile.write(b"<html><body><a href='/valid'>Valid</a><a href='/broken'>Broken</a><a href='http://google.com'>External</a></body></html>")
+ elif self.path == '/valid':
+ self.send_response(200)
+ self.send_header("Content-type", "text/html")
+ self.end_headers()
+ self.wfile.write(b"Valid page")
+ elif self.path == '/broken':
+ self.send_response(404)
+ self.end_headers()
+ else:
+ super().do_GET()
+
+ def do_HEAD(self):
+ if self.path == '/valid':
+ self.send_response(200)
+ self.end_headers()
+ elif self.path == '/broken':
+ self.send_response(404)
+ self.end_headers()
+ else:
+ self.send_response(200)
+ self.end_headers()
+
+ def log_message(self, format, *args):
+ pass
+
+ cls.httpd = http.server.HTTPServer(cls.server_address, MockHandler)
+ cls.server_thread = threading.Thread(target=cls.httpd.serve_forever)
+ cls.server_thread.daemon = True
+ cls.server_thread.start()
+
+ @classmethod
+ def tearDownClass(cls):
+ cls.httpd.shutdown()
+ cls.server_thread.join()
+
+ def test_check_url_valid(self):
+ status, reason = check_url(f"{self.base_url}/valid")
+ self.assertEqual(status, 200)
+ self.assertIsNone(reason)
+
+ def test_check_url_broken(self):
+ status, reason = check_url(f"{self.base_url}/broken")
+ self.assertEqual(status, 404)
+
+ def test_link_parser(self):
+ parser = LinkParser(self.base_url)
+ html = "<html><body><a href='/test'>Test</a><a href='https://external.com'>Ext</a></body></html>"
+ parser.feed(html)
+ self.assertIn(f"{self.base_url}/test", parser.links)
+ self.assertIn("https://external.com", parser.links)
+
+ def test_crawl_integration(self):
+ # Test the crawl function logic
+ broken = crawl(self.base_url, max_pages=2)
+ # It should find the broken link /broken
+ targets = [b.get('target') for b in broken if 'target' in b]
+ self.assertIn(f"{self.base_url}/broken", targets)
+
+if __name__ == '__main__':
+ unittest.main()