Url Utils
URL hygiene for AI agents — parse, normalize, strip tracking, build GA4-correct UTM links, validate, canonicalize, infer platform, compare, expand short-links, and trace redirect chains. Guidance-only: the agent's own runtime executes the pure-logic patterns taught in SKILL.md, backed by 22 installable registry assets (UTM templates, per-platform tracking-param sets, CMS canonical rules) and 3 deterministic enforcement scripts (verify-url, strip-tracking, lint-utm).
My agents kept treating "this URL parsed" as "this URL is safe." Those are different verdicts. A Cyrillic letter inside paypal.com parses fine and points somewhere else. %2541 survives one decode pass and breaks your dedup. And adding tidy utm tags to a Google Ads link overrides the gclid, which kills cost data in GA4. Nothing errors. You just get wrong numbers on the channel where most of your spend goes.
This skill is guidance-only. There is no backend and nothing to 404. Your agent runs all 13 operations itself.
What it installs are 22 evidence-backed assets: 8 UTM channel templates, 6 per-platform tracking-param sets, 4 CMS canonical patterns, plus fixtures and a homograph allowlist. The param sets catch the whole click-ID family, not just utm_*.
Three scripts turn judgment calls into verdicts. verify-url.mjs FAILs homographs and double-encoding, and passes real domains like muenchen.de. strip-tracking.mjs reports "42/57 URLs cleaned, 3.2 params each" and never strips a param you marked as yours. lint-utm.mjs FAILs any medium outside the GA4 list. That one matters: standard naming measured +29% attribution accuracy (CXL Institute, 2025).
Features5
Mixed-script domain labels FAIL via UTS #46 and UTS #39, while single-script domains like muenchen.de and the Han IDNs still pass.
6 snapshot-dated per-platform sets cover gclid, gbraid, fbclid, msclkid, ttclid, li_fat_id and yclid.
Manual utm tags on an auto-tagged Google Ads URL are a hard FAIL, because they override the gclid and kill GA4 cost import.
A hard gate protects any parameter declared attribution-authoritative, and audit mode shows the diff before anything changes.
8 UTM channel templates, 6 tracking-param sets, 4 CMS canonical patterns, plus fixtures and a homograph allowlist.
Videos1 video
DemoUrl Utils · Demo video
Demo · SpiderMediaArticles about Url Utils1 article
Videos1 video
DemoUrl Utils · Demo video
Demo · SpiderMediaArticles about Url Utils1 article
Showing all 1
SKILL.mdthe file your agent reads
SKILL.md loads when you open this tab.
What's new6 releases · newest first · from the package's CHANGELOG
v0.3.32026-11-10Latest
Marketplace listing update: added the launch explainer film (`media.demo_video_url`). No code, schema, copy or guidance changes; hero and screenshots unchanged from 0.3.2.
v0.3.22026-07-21
Marketplace-card release. No behaviour change: the SKILL.md guidance, the 22 registry assets, the 3 enforcement scripts, the references and the recipes are byte-identical to 0.3.1. - **Added** the SPEC-3 card asset kit: a top-level `media:` block with `hero_image_url` + 3 `screenshots` (dark-board chalk house style, rendered via SpiderGate). `demo_video_url` is deliberately omitted — no real video exists and an empty string fails validation. - **Added** `marketing.long_description` (first-person, ~180 words) + 5 `marketing.features[]` with icons. Both slots were empty on the published card. - **Declared** `tier: beta` in the manifest so the packaged tier matches the live registry tier (0.3.1's manifest still said `internal`). - **Synced** the version string across `package.yaml`, both `SKILL.md` copies and `skills/url-utils/schema.yaml` — they had drifted to 0.3.0/0.3.1 in the published bundle. - **Removed** `BRIEF.md`, `tests/`, `propagation/`, `creatives/` and `source/` from the shipped tarball. Those are workbench artifacts and 0.3.1 was shipping them to customers.
v0.3.12026-06-22
Packaging fix. Moved from the flat `skills: []` shape to the nested, co-located `skills: [{id, schema}]` shape with `SKILL.md` + the layer directories under `skills/url-utils/`, so `skill_read` resolves the guide instead of 404ing on a root-level lookup.v0.3.02026-06-17
Converted to **guidance-only** per the OPVS DEFINITIVE rule (2026-06-17: "does the skill DO something? — NO → guidance-only"):
- **Removed** the typed-method surface. `client/schema.yaml` (13 methods + `provider_config` `base_url: OPVS_API_URL`) declared a backend url-utils never had — the OPVS gateway would HTTP-call those phantom endpoints and 404. url-utils' operations are pure-logic the agent's own runtime executes. Schema retired to `source/legacy/client-v0.2.0/schema.yaml` for provenance.
- **Added** `skills: []` + 4 `peer_dependencies` (the upstream OPVS coordination skills: agentdocs / agentmemory / agentboard / opvs-protocol) — the canonical guidance-only shape. No `@di-atomic` peers (url-utils is a leaf utility).
- **Added** `README.md` (marketplace listing) + `CHANGELOG.md` (this file) at bundle root + `docs.{readme,skill_guide,changelog}` block (satisfies security check 7 / required-docs).
- **Rewrote** `SKILL.md` as guidance: the 13 operations are now patterns the agent runs itself (WHATWG URL / urllib / regex) + invocations of the 3 bundled scripts (`node scripts/<name>.mjs`). Added the v2.2 `## Coordination` cross-references section.
- **Added** `scripts/verify-coordination.mjs` (Layer 7 — v2.2 coordination gate).
- **Access pattern:** agents now reach url-utils via `skill_search` → `skill_read` (reads SKILL.md out of the .tgz). No HTTP call. Nothing to 404.
The 3 enforcement scripts (`verify-url.mjs`, `strip-tracking.mjs`, `lint-utm.mjs`), the 22 registry assets, the 3 references, the 3 recipes, and the 9 learnings are unchanged from 0.2.0 — agents run the scripts directly.v0.2.02026-06-15
7-layer v2.1 retrofit (published 2026-06-15, package_id 8457ab01, 100/100). Added `references/`, `recipes/`, `instructions/`, `learnings/` (9), `registry/` (22 evidence-bundled assets), `scripts/` (3 enforcement verifiers). SKILL.md became a router. Method surface expanded to the full 13 (incl. network expandShortUrl / detectRedirectChain). **Superseded by 0.3.0** — 0.2.0's typed-method surface was a phantom backend.
v0.1.02026-05-13
Initial release. 3 pure-Python methods (parseUrl / normalizeUrl / stripUtm), 1-layer SKILL.md. 100/100, installed into DI-ATOMIC brand 2. Judged "not useful at all" — the founding incident for the v2.1 layer format (see `learnings/2026-05-24-v01-shipped-not-useful/`).
Showing all 6
