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.jsonindex 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.jsonindex 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.mdindex 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### Fixeddiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 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.mdindex 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-Modeldiff --git a/VERSION b/VERSIONindex c317a918..9beb74d4 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.13.1+0.13.2diff --git a/log/pytest_configs.json b/log/pytest_configs.jsonnew file mode 100644index 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 filediff --git a/seo/broken-link-checker/SKILL.md b/seo/broken-link-checker/SKILL.mdnew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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()