browser-backlink-submission— agent skill

Overview

Given a qualified prospect list and a single source-of-truth site profile, drive each target's submission form to completion, capture evidence, and emit an auditable log. This skill is execution-only — it assumes prospects are already vetted upstream and assumes anchor / description copy is either pre-supplied or fetched via the agent's main loop.

Outcome: a submission-log.json with one row per attempt (status, evidence, live URL once verified) plus screenshots under ./out/backlinks/. No fabricated successes, no fire-and-forget, no link-farm targets ever.

Mental model

A submission run is a pipeline: profile → per-target field mapping → form drive → evidence capture → verification follow-up. Most failures are not bugs — they are signals: captcha walls, login-required, paid-only, dead form, off-topic category. The skill's job is to detect, classify, and log these honestly so the user gets a reliable picture of what shipped.

Three immovable invariants:

1. Never submit to a target the prospect list did not qualify. If a target looks shady mid-run (hidden links, casino/pharma neighbours, "1000 directories for $5" footer), skip and log skipped:quality.
2. One identity per run. Reuse the same email, brand name, contact, anchor pool — directories that detect inconsistency flag listings. The profile is the source of truth.
3. Evidence or it didn't happen. Every submitted row needs a post-submit screenshot and either a confirmation URL or a confirmation-email subject line.

Rules

The site profile (input contract)

The user (or an upstream step) supplies one JSON file. If any required field is missing, stop and ask — do not invent values.

Target classification (per prospect, before driving the form)

Field-mapping rules

• name → "Site Name", "Title", "Project", "Tool name", "Company". Match what the form asks; never invent prefixes/suffixes.
• url → "URL", "Website", "Homepage". Always canonical https; never with tracking params.
• description_short → "Tagline", "Short description", "Pitch", fields with ≤ 160 char limit.
• description_long / description_alt → "Description", "About", "Details" (300+ chars). Rotate variants across the run; don't paste the identical paragraph 50 times.
• category → match to directory taxonomy by exact label first, then nearest synonym. If nothing fits, pick the closest and log category_mapping.
• tags → split into the form's expected separator (comma, space, enter-per-tag). Trim to the form's max count.
• anchors → only used when the target lets you choose anchor text on the link. Rotate per-target from anchors[]; track usage to keep brand-anchor share ≥ 50%.
• logo / screenshot → upload via setInputFiles on the file input; verify the upload preview appears before submit.

Drive protocol (per target)

1. Pre-flight — open URL, confirm it's the submission form (not 404, not paywall, not "submissions closed"). If wrong, log and move on.
2. Account check — if the form requires an account: look up cached creds for that domain in this session's profile vault; if absent, ask user once, then proceed. Never store creds to disk.
3. Captcha check — if a captcha is on the submit page, stop. Do not iterate.
4. Field walk — accessibility-tree first; fill in the order the form lays them out; verify each value sticks (re-read the input).
5. Category mapping — if a select / radio is required, pick by label match; if no match, pick the nearest sibling and record the mapping in the log row.
6. Upload check — for image fields, confirm the preview thumbnail rendered before submit.
7. Submit — click the actual submit button; wait for a success state: redirect, success message, confirmation page selector, or verification email.
8. Evidence — screenshot the post-submit state (full page) to ./out/backlinks/<domain>-<UTC>.png; capture the confirmation URL or message text.
9. Verification — if the target sends a confirmation email, poll the user's mailbox via the supplied flow (out of scope of this skill — escalate if no flow available); record the verified URL when it goes live.
10. Log — append one row to ./out/backlinks/submission-log.json.

Throttling and identity hygiene

• Spread across time: never submit to more than 5 targets in a row from the same IP without a 60-second cool-off.
• Pace per day: cap free-directory submissions at 20 per day per identity; business directories at 5; web2.0 publishes at 2.
• Rotate anchor variants — track use counts in-memory; never let one anchor exceed 30% of the run.
• Rotate description variants — alternate description_long and description_alt per target.
• One profile, one email, one contact name across the entire run. Inconsistency is a flag.

Submission log schema

./out/backlinks/submission-log.json is an array of rows. Append-only.

{
  "target_url": "https://example-directory.com/submit",
  "target_domain": "example-directory.com",
  "target_type": "saas-directory",
  "submitted_at": "2026-05-10T18:32:11Z",
  "status": "submitted | pending:email | pending:ownership-verify | live | rejected | skipped:captcha | skipped:paid | skipped:quality | skipped:auth | skipped:not-a-form | failed:selector | failed:timeout",
  "anchor_used": "the brand name",
  "description_variant": "long | alt",
  "category_mapping": { "requested": "Developer Tools", "selected": "Tools / Dev" },
  "live_url": null,
  "screenshot_path": "./out/backlinks/example-directory-com-20260510T183211Z.png",
  "confirmation_url": null,
  "confirmation_email_subject": null,
  "notes": "Selector for category was a custom dropdown; mapped Tools → Tools / Dev."
}

Out-of-scope handling

• Need fresh, on-topic descriptions per niche → stop; copy authoring is an upstream concern, do NOT write copy here.
• Need to qualify fresh prospects mid-run → stop. This skill does not vet new targets on the fly; prospect vetting is an upstream concern.
• Q&A / forum / community work → out of scope. Persona / on-topic answers are not this skill's job.

Examples

Example 1: Bad → Good (description handling)

❌ Bad:

For all 50 directories, paste description_long verbatim. Reuse "TheBrand" anchor every time.

✅ Good:

Alternate description_long and description_alt across submissions.
Rotate anchors from profile.anchors[]; track use, cap brand-anchor share at 50%, naked-URL at 20%, generic at 30%.

What changed: identical copy + identical anchor across many targets is the duplicate-footprint signal Google uses to discount or penalize.

Example 2: Edge case — category not in taxonomy

The site is a Developer Tools SaaS but the directory only offers Software / Other, Business / Productivity, Lifestyle. Pick Software / Other, record category_mapping: { requested: "Developer Tools", selected: "Software / Other" }, do not pick Business / Productivity because it's slightly broader — closer is better than larger.

Example 3: Edge case — captcha on submit

Form filled cleanly, "Submit" button reveals an hCaptcha challenge. Stop. Screenshot. Log skipped:captcha. Do not refresh and retry; do not attempt an OCR/solver. Move to the next target.

Checklist

• [ ] Site profile JSON validated — all required fields present, anchors[] has ≥ 3 entries, logo file exists if any target needs it
• [ ] Prospect list classified — each target has a target_type; link-farm / unrelated targets pre-filtered out
• [ ] Output directory ./out/backlinks/ exists; previous submission-log.json either rotated or appended to deliberately
• [ ] Per submission: post-submit screenshot saved, log row appended, status reflects reality (no "submitted" without evidence)
• [ ] Anchor and description rotation is enforced — no anchor or description variant exceeds its share cap
• [ ] Throttling respected — pace caps and cool-offs honored
• [ ] Captcha / paid / login-required targets skipped, not faked
• [ ] No credentials persisted to disk after the run
• [ ] Final report summarizes: total attempted, submitted, pending verification, skipped (by reason), failed (by reason)

Composition / References

• Pairs with browser-form-filling-patterns (selector resilience, file uploads, multi-step forms) — base layer.
• Runs only after an upstream prospect-vetting step has produced a qualified list — this skill does not discover or qualify prospects.
• Copy generation (descriptions, anchor variants) is an upstream concern — do not author copy inside this skill.
• Google Search Essentials — Link spam
• Google: Qualifying outbound links to your site