How to find and add internal links with Claude Code

Claude Code finds and adds internal links in three passes. It crawls a copy of your site and builds a link map: every link, its anchor text and where it points. From that map it reports orphan pages, pages with few links in, generic anchors like "read more," and links that hit redirects or errors. Then it proposes new links as rows in a spreadsheet, each with the exact sentence, the anchor and the target. A person approves the rows, a script inserts them into the source files, and a second crawl confirms the result.

Claude does the crawl and drafts the proposals. The approval is where the quality comes from. Forced links read badly, and Google's own guidance warns against anchors stuffed with keywords. This guide gives the steps, example prompts, the check for each step and what a person reviews.

What Google says about internal links

Google's link best practices are short and practical. Links should be crawlable: an a element with an href, not a span with a click handler. Anchor text should make sense on its own: "Try reading only the anchor text (out of context) and check if it's specific enough to make sense by itself." Context matters too: "the words before and after links matter," and "Don't chain up links next to each other." For image links, "Google uses the alt attribute of the img element as anchor text."

It also warns against overdoing it. Cramming keywords into anchor text is keyword stuffing, which "is a violation of our spam policies." And on volume: "if you think it's too much, then it probably is." Those rules translate directly into checks Claude can run and instructions it can follow.

Step 1: Crawl a copy and build the link map

Work on a local build or staging site, on a git branch. Ask Claude to crawl it and record every internal link.

Example prompt: Crawl the local build and write links.csv with one row per internal link: source URL, target URL, anchor text, whether it's in the main content or in the header, footer or sidebar, and the target's status code. Then give me a summary per page: links in from main content, links out, and links in from navigation only.

Separating main-content links from navigation matters. A page linked only from a footer menu isn't an orphan, but it has no contextual support either.

The check: the number of pages in the map matches your sitemap or build count, and a page you know well shows the links you expect. If your site inserts links with JavaScript, the crawler needs a real browser. For JavaScript-inserted anchor text, Google suggests the URL Inspection Tool "to make sure it's present in the rendered HTML."

Step 2: Find orphans, weak pages and bad anchors

Ask Claude to turn the map into a short list of problems.

Broken and redirected links are their own job, covered in finding and fixing broken links with Claude Code. Fix those first, so new links don't point at bad targets.

The check: look at five orphan pages yourself. Some will be pages you meant to retire, which changes the fix.

Step 3: Decide the structure before adding links

Adding links is easy. Deciding which pages should support which is a strategy call, and a person makes it. Write down your topic clusters: a hub page per topic, the articles that belong under it, and which service or product page each cluster supports. Our guide to internal linking strategy and topic clusters covers how to choose them.

Then set house rules Claude will follow. A hypothetical example: each article links to its hub once, to two or three sibling articles, and to one relevant service page; each URL is linked at most once per page; no links in headings; no more than one link per paragraph. Put the rules in a project file or a skill so every session uses the same ones. A reusable skill is a good fit for this; see Claude Code skills explained.

Step 4: Have Claude propose links for review

Claude reads each source page, finds a sentence where a target page is the natural next step, and proposes an anchor inside that sentence. Ask for proposals, not edits.

Example prompt: Using clusters.csv and the house rules in linking-rules.md, propose internal links for the 40 pages in the weak-pages report. For each proposal give: source URL, the exact existing sentence, the anchor text (words already in that sentence), target URL and a one-line reason. Don't change sentences to fit a link. Skip a page if no sentence fits. Write proposals to link-proposals.csv.

"Words already in that sentence" keeps the copy intact. If a link needs a new sentence, that's a content edit, and it should be reviewed as one. For a large site, you can split the work across subagents by section, each reading its own pages; see subagents explained.

The check: every proposal's anchor appears word for word in its sentence, every target returns 200 and isn't redirected, and no source page exceeds your per-page rule. Ask Claude to verify these three things in a script and report failures.

Step 5: A person reviews the proposals

Read proposals in the spreadsheet, where they're easy to scan. For each one, the reviewer checks:

• Does the anchor make sense on its own and describe the target?
• Would a reader want to go there from this sentence?
• Is it a natural link, or a keyword dropped in for search engines?
• Does it send readers away from a page right before they would contact you?

Mark rows approved, edited or rejected. Rejection rates are useful feedback. If many proposals for one cluster are rejected, adjust the rules and regenerate that cluster instead of fixing rows one by one.

Step 6: Apply approved links in the source files

Ask Claude to write a script that inserts approved links into the source files: the CMS content, Markdown files or templates your pages are built from. Not the generated HTML, which the next build overwrites.

Example prompt: Write a script that applies only approved rows in link-proposals.csv. For each row, find the exact sentence in the source file and wrap the first occurrence of the anchor in a link to the target. If the sentence isn't found exactly once, skip the row and log it. Report counts of applied, skipped and already linked.

The check: the applied count matches the approved count minus logged skips. Read the second and last page the script changed, not only the first. Then run the script again. It should apply nothing, because every link is already in place.

Step 7: Re-crawl and confirm

Re-run the step 1 crawl and compare it with the first map.

The last row is the one to check in the git diff before a person approves the deploy. A link-insertion script should add markup, not rewrite copy.

What a person must review

• The cluster plan and house rules, before any proposals are generated.
• Every proposal on high-traffic pages and service pages, and a sample elsewhere.
• Any orphan page before deciding to link, merge or retire it.
• The final diff, to confirm only links changed.

Internal linking is one of several site-wide SEO jobs Claude Code handles well; the overview is in Claude Code for technical SEO, and the broader list of website jobs is in what Claude Code can do for a business website.

Conclusion

Claude Code makes internal linking practical on sites too big to link by hand: it maps every link, finds orphans and weak anchors, and proposes contextual links with the sentence and reason attached. Keep people in charge of the structure and the approvals, apply links only in source files, and confirm with a second crawl and a diff that shows nothing but new links. If you'd like help planning clusters or running the work, see our technical SEO service. More guides are in our Claude Code Guide.

Frequently asked questions