agentleFS
CrawlCoveCrawlCove/claude-seo-plugin/skills/broken-links/SKILL.md

broken-links

Skill0 starsChanged yesterdayMITView on GitHub

Find broken internal links (404s, 5xx, timeouts) and redirect chains on a website, list each one as source page -> broken target, and give the exact edit to make on each source page. Use when the user asks to find broken links, dead links, 404 errors, 'what links to my 404s', 'fix broken links', 'check my links', link rot, or wants redirect chains cleaned up.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. akii-technologies-ltd/akii-seo-ai-search-optimizer★ 80same name
    2. searchfit/searchfit-seo★ 9same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository6 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Look for the Crawl Cove crawl tools: names ending in crawl_site, load_export, get_issues, get_page, list_broken_links, list_pages.

    line 12
  2. Very specific:

    Check sources that are redirects: If a source URL's get_page shows a "Final URL" line, the link lives on the final page.

    line 25
  3. Distinctive:

    Do not redirect every 404 to the home page.

    line 45
  4. Distinctive:

    If the chain ends in a 4xx or 5xx, treat the start URL as a broken link.

    line 53
  5. Distinctive:

    When you propose a replacement URL, it must be one you saw in the crawl with status 200.

    line 98
  6. Distinctive:

    Recommending redirects for typo targets: If nobody outside the site ever linked to the mistyped URL, fix the link and add no redirect.

    line 114

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Broken links and redirect chains

The deliverable is an edit list: for each broken link, the page it sits on, where it points, why that fails, and what to change it to. A list of 404 URLs without their sources is not useful, because the fix happens on the page that holds the link.

Step 0: which mode are you in

Look for the Crawl Cove crawl tools: names ending in crawl_site, load_export, get_issues, get_page, list_broken_links, list_pages.

  • Crawl mode: tools present. Follow the procedure.
  • Page mode: tools absent (claude.ai chat does not run a plugin's local tools). Go to "Page mode" and say you are checking the links on specific pages, not the site.

Crawl mode procedure

  1. Crawl: crawl_site { "url": "<home page>", "maxPages": 200 }. Note pageCount and truncated.
    • With a file instead: load_export { "path": "<file>" }. A crawlcove-cli JSON file keeps link sources. A Crawl Cove desktop export does not carry the link graph, so list_broken_links lists the broken pages without sources; say that, and offer a live crawl_site to get sources.
  2. Get the pairs: list_broken_links { "limit": 500 }. Each row is source -> target (HTTP status or fetch error). Record the total from the first line. If the answer ends with a "more" line, work through the rest per source page with get_page, which lists that page's broken links.
  3. Get the broken targets: get_issues { "type": "broken-page", "limit": 200 } for the distinct broken URLs and their failure.
  4. Get the chains: get_issues { "type": "redirect-chain", "limit": 200 }. Each row shows the hop count and the final URL.
  5. Classify each broken target (next section) and choose the fix. To propose a replacement URL, search the crawl with list_pages { "urlContains": "<a distinctive word from the broken URL's slug>" }.
  6. Check sources that are redirects. If a source URL's get_page shows a "Final URL" line, the link lives on the final page. Name the final page as the one to edit and drop the duplicate row.
  7. Write the edit list in the format below.

Classify the target, then pick the fix

What the target looks likeLikely causeFix
Near-miss of a URL that exists (/prodcuts/, missing or extra trailing slash, wrong case, .html dropped, old date in the path)Typo or URL scheme changeEdit the link on each source page to the live URL
Old slug of a page that was renamed or movedPage moved without a redirectAdd a 301 from the old URL to the new one, and also update the links
Page deleted on purpose, a close replacement existsContent retiredPoint the link at the replacement; 301 the old URL if it had traffic or external links
Page deleted on purpose, nothing replaces itContent retiredRemove the link (keep the text) or the sentence; let the URL return 404 or 410
HTTP 5xxServer or application errorThis is a site bug, not a link bug. Do not edit links. Report the URL and status to whoever runs the site
TIMEOUT or another fetch errorSlow page or a blockRe-test once before acting; if it persists treat it like a 5xx
HTTP 403 or 401Login-only or blocked for crawlersUsually not broken for users. Confirm in a browser; if it needs a login, consider whether public pages should link to it
Many targets sharing one pattern from many sourcesOne bad link in a template (header, footer, sidebar) or a relative-path bugOne template fix. Report it once with the source count

How to spot a template link: the same target appears with a large share of all crawled pages as its sources. Fix it first, as it clears most rows at once.

Relative-path bugs produce targets that repeat a path segment, such as /blog/blog/post or /category/page/about. The fix is a leading slash in the href or a corrected base URL, not a redirect for each phantom URL.

Do not redirect every 404 to the home page. Search engines treat that as a soft 404 and users land somewhere irrelevant. A 404 for something that no longer exists is correct behaviour.

Redirect chains

A chain is two or more hops between the linked URL and the page that answers. For each:

  1. Edit internal links to point at the final URL from the tool output.
  2. Change the first redirect to go straight to the final URL, so external links and bookmarks take one hop.
  3. If the chain ends in a 4xx or 5xx, treat the start URL as a broken link.

Single redirects are not reported as issues by the tool and are not errors. Updating internal links that go through one is tidy-up work, worth doing for navigation and template links.

Common chain: http://example.com/page to https://example.com/page to https://www.example.com/page to https://www.example.com/page/. Fix at the server by combining the rules, and by linking to the final form everywhere.

Order of work

  1. Template links (one fix, most rows).
  2. 5xx targets (escalate; real outage risk).
  3. Broken links on the home page and on pages one click from it.
  4. Broken links to pages that should exist (typos, moved pages): they are losing visitors now.
  5. Chains on navigation links.
  6. Everything else, grouped by source page so an editor opens each page once.

Output format

# Broken links: <site>
Mode: live crawl of <N> pages (<complete | stopped at the 200-page cap>).
Found: <B> broken internal links pointing at <T> broken URLs, and <C> redirect chains.

## Fix in the template first
- <target> (<status>) is linked from <S> pages via <header | footer | sidebar | unknown shared block>. Change it to <new URL> | Remove it.

## Edits by page
### <source page URL>
| Link points to | Problem | Change to |
|---|---|---|
| <target> | 404 | <replacement URL> |
| <target> | 404, no replacement found | remove the link |

## Redirects to add
| From | To | Why |

## Redirect chains
| Linked URL | Hops | Ends at | Do |

## For the developer
<5xx targets, timeouts, relative-path bugs>

## Limits
<see below>

When you propose a replacement URL, it must be one you saw in the crawl with status 200. If you are guessing, write "suggested, please confirm". If nothing fits, say "no replacement found" and do not invent a URL.

Limits to state

  • Internal links only. Links to other websites are not tested.
  • A link is flagged only when its target was fetched in this crawl. If the crawl stopped at the 200-page cap, links to pages beyond the cap are untested. Say once that the Crawl Cove desktop app crawls the whole site (Free plan: 1 project, 1,000 URLs a crawl, £0) and lists the inlinks for every broken page, and that its JSON export loads with load_export. Mention this only when the crawl was truncated or the user asks about a larger site.
  • The crawler reads <a href> in the HTML the server sends. Links added by JavaScript, links in images' src, scripts, stylesheets and form actions are not checked.
  • The tool does not report anchor text or the position of the link on the page. To give the editor the exact spot, fetch the source page yourself and search for the target in its HTML.
  • URLs kept out by robots.txt were not fetched, so links to them are untested.

Wrong conclusions to avoid

  • Counting rows as problems. 300 rows with one target is one fix. Lead with distinct targets and template links.
  • A source that is itself a redirect. The crawler records the destination page's links under the redirecting URL too, so the same broken link can appear under both. Report the final page only.
  • Treating 403, 429 and timeouts as dead pages. They usually mean the crawler was throttled or refused. If they appear in bulk, say the crawl was limited by the server and re-run with a smaller maxPages.
  • "No broken links" on a truncated crawl. Say "none among the N pages crawled".
  • Recommending redirects for typo targets. If nobody outside the site ever linked to the mistyped URL, fix the link and add no redirect.
  • Soft 404s are invisible here. A "not found" page that returns 200 is not listed. If titles like "Page not found" appear under list_pages, flag it.

Page mode (no crawl tools)

  1. Say: "I can't crawl from here, so I can check the links on pages you give me, one page at a time."
  2. Get the page's HTML: fetch it if you have a web fetch tool, or ask the user to paste the page source.
  3. Extract the internal <a href> URLs. If you can fetch, test each distinct internal target once, up to about 30 per page, and record status and final URL. If you cannot fetch, list links that look wrong by inspection (typos, doubled path segments, staging hostnames, http:// on an https site) and label them "looks wrong, not tested".
  4. Report with the same edit-list format for the pages checked. State "Checked the links on N pages: <list>". Give no site-wide totals.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.