Linkloom

LinkLoom

Overview

Use this skill to turn a website's article inventory into a topical internal linking plan and, when requested, apply the approved links. Prefer a report-first workflow; write links into copied local files first, then use a dry run before any live CMS update.

Workflow

1. Confirm the content source:

• Local Markdown/HTML articles, static site repository, or CMS export: work on local files.
• Sitemap or URL list only: collect URLs, then fetch public HTML with scripts/fetch_url_content.py or ask for article exports before scoring link opportunities.
• WordPress site: read references/website-access.md, export through REST API, work locally, then apply updates through REST API only after approval.

1. Build a content inventory with URL, title, topic, page type, and existing links.
2. Read references/internal-linking-rules.md before finalizing recommendations.
3. Score link opportunities and generate CSV plus optional Markdown/JSON reports.
4. Review high-impact suggestions manually for intent, anchor naturalness, and destination quality.
5. Apply links to a copied output directory, or run a dry run with diff output first.
6. Require explicit user approval before live CMS updates.

Local Content Quick Start

Normalize a sitemap or URL list when the user provides one:

python3 scripts/extract_urls.py --source sitemap.xml --out urls.csv

Fetch public article HTML from the URL list when no CMS export exists:

python3 scripts/fetch_url_content.py \
  --urls urls.csv \
  --out-dir ./site-export

Score link opportunities from local content:

python3 scripts/score_link_opportunities.py \
  --content-dir ./content \
  --site-base https://example.com \
  --topic-map topic-map.csv \
  --out internal-link-suggestions.csv \
  --inventory-out content-inventory.csv \
  --markdown-out internal-link-summary.md

Apply approved suggestions into a copied output directory:

python3 scripts/insert_internal_links.py \
  --content-dir ./content \
  --suggestions internal-link-suggestions.csv \
  --out-dir ./content-linked \
  --diff-dir ./link-diffs \
  --report applied-links.csv

Use --in-place only when the user explicitly asks for direct file edits and a backup is acceptable. Inspect the changed files or diff before delivery.

WordPress Quick Start

Use application passwords or a scoped token, not a user's normal admin password. Read references/website-access.md first.

export WP_APP_PASSWORD='xxxx xxxx xxxx xxxx xxxx xxxx'

python3 scripts/wordpress_rest_sync.py export \
  --base-url https://example.com \
  --username editor@example.com \
  --app-password-env WP_APP_PASSWORD \
  --out-dir ./wp-export \
  --types posts pages \
  --status publish

python3 scripts/score_link_opportunities.py \
  --content-dir ./wp-export/content \
  --url-map ./wp-export/url_map.csv \
  --out ./wp-export/internal-link-suggestions.csv \
  --inventory-out ./wp-export/content-inventory.csv \
  --markdown-out ./wp-export/internal-link-summary.md

python3 scripts/insert_internal_links.py \
  --content-dir ./wp-export/content \
  --suggestions ./wp-export/internal-link-suggestions.csv \
  --out-dir ./wp-linked/content \
  --diff-dir ./wp-linked/diffs \
  --report ./wp-linked/applied-links.csv

python3 scripts/wordpress_rest_sync.py apply \
  --base-url https://example.com \
  --username editor@example.com \
  --app-password-env WP_APP_PASSWORD \
  --url-map ./wp-export/url_map.csv \
  --linked-dir ./wp-linked/content \
  --original-dir ./wp-export/content \
  --applied-report ./wp-linked/applied-links.csv \
  --summary-json ./wp-linked/wp-dry-run-summary.json \
  --dry-run

Run the final apply command with --apply only after the user approves the dry-run summary.

Recommendation Standards

Use internal links to clarify topical relationships, not to maximize link count. Prefer links that help a reader move from a supporting article to the best pillar page, from a pillar page to its most important cluster articles, or between closely related cluster articles.

Report columns should include: source_url, source_title, source_topic, source_page_type, target_url, target_title, target_topic, target_page_type, anchor_text, anchor_source, context, score, reason, link_direction, and review_required. Add source_path and target_path when local files are involved.

Mark a suggestion as review_required when the anchor is inferred, the target page intent may not match, the target is commercial, the source already has many links, or the exact anchor text does not already appear naturally in the article.

Safety Rules

• Do not add more than 3 to 5 new links per article unless the user asks for a broader pass.
• Do not link the same target URL more than once from the same article.
• Do not edit headings, navigation, footer, breadcrumbs, scripts, style blocks, code blocks, or image alt text.
• Do not rewrite article meaning to force a link.
• Do not use exact-match anchors repeatedly across many articles.
• Do not update a live CMS without a backup/export, a dry run, and explicit approval.
• Do not use generic browser admin automation for live updates when an official CMS API or local export workflow exists.

Resources

• references/internal-linking-rules.md: topical authority model, scoring, anchor rules, and manual review checklist.
• references/website-access.md: safe access patterns for WordPress, static sites, and other CMSs.
• scripts/extract_urls.py: convert sitemaps, URL lists, and simple exports into a normalized URL CSV.
• scripts/fetch_url_content.py: fetch public URLs into local HTML files and a URL map for read-only audits.
• scripts/score_link_opportunities.py: score local Markdown/HTML articles and produce recommendation reports.
• scripts/insert_internal_links.py: insert approved links into copied local content files.
• scripts/wordpress_rest_sync.py: export and apply WordPress posts/pages through REST API with dry-run defaults.
• scripts/validate_skill.py: validate the skill folder without third-party dependencies.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: publicusdijital-ai
• Source: publicusdijital-ai/linkloom
• License: MIT
• Homepage: https://publicus.com.tr

Install and usage instructions live in the source repository linked above.