utm-link-skill
YoriHan/utm-link-skill
Claude Code slash command to auto-generate UTM tracking links for KOL campaigns — Bitly + Notion integration
Instalação
npx convez-ai YoriHan/utm-link-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
utm-link — Claude Code Slash Command
在 Helio 安装(推荐)
在 Helio 里直接粘贴这个仓库链接即可:
https://github.com/YoriHan/utm-link-skill
或命令行:
heliox skill install YoriHan/utm-link-skill --description "粘贴 KOL 链接自动生成 UTM 短链并写入 Notion"
Helio 读取的是 repo 根目录的
SKILL.md。仓库里的utm-link.md是给 Claude Code slash command 用的,内容相同。
A Claude Code slash command that automates UTM link generation for KOL (Key Opinion Leader) campaigns. Paste a KOL's profile URL, and Claude will auto-detect the platform, build a UTM tracking URL, shorten it with Bitly, and write the complete record into your Notion database — no manual copy-pasting required.
What it does
- New KOL mode: Paste one or more KOL profile URLs → auto-detect platform → build UTM long URL → generate Bitly short link → create Notion row
- Backfill mode: Find existing Notion rows missing UTM links and fill them in
- Stats mode: Pull Bitly click counts for all tracked links and update Notion
Prerequisites
- Claude Code installed
- Notion MCP configured in Claude Code
- A Bitly account with API access (free Core plan: 100 links/month)
- A Notion database with these fields:
- Title field (KOL name)
- A
渠道(channel) select field - An
原链接(original URL) url field - A
UTM Linkurl field - A
备注(notes) text field
Field names are configurable — see the config section below.
Installation
- Copy
utm-link.mdto your Claude Code commands folder:
cp utm-link.md ~/.claude/commands/utm-link.md
- That's it. The first time you run
/utm-link, the setup wizard will guide you through configuring your Bitly token and Notion database.
First-time setup
Run /utm-link in Claude Code. You'll be prompted to:
- Bitly API Token — get it from Bitly → Settings → Developer settings → API
- Notion database URL — paste the URL of your UTM tracking database (e.g.
https://www.notion.so/xxxxxxxx?v=yyyyyyyy) - UTM templates (optional) — customize the UTM parameter structure per platform, or use the defaults
Config is saved to ~/.claude/utm-link/config.json. You only do this once.
Usage
Add new KOL(s)
Paste one or more social profile URLs (space-separated):
/utm-link https://x.com/rohanpaul_ai
/utm-link https://x.com/rohanpaul_ai https://youtube.com/@SomeChannel https://linkedin.com/in/john-doe
Claude will:
- Auto-detect the platform from the URL
- Extract the KOL name (handle, channel name, or slug)
- Show a preview table and ask you to confirm
- Check for duplicates in Notion
- Generate the Bitly short link
- Create the Notion row with all fields filled in
Supported platforms:
| URL pattern | Platform | Name extracted |
|---|---|---|
x.com/handle or twitter.com/handle | handle (e.g. rohanpaul_ai) | |
youtube.com/@ChannelName | YouTube | channel name (e.g. SomeChannel) |
discord.gg/invitecode | Discord | asks you to specify (invite links don't contain KOL identity) |
reddit.com/u/username | username | |
reddit.com/r/subreddit | subreddit name | |
linkedin.com/in/profile-slug | profile slug |
Backfill existing records
Run without arguments to find existing Notion rows missing UTM links:
/utm-link
For each row:
- If
原链接is already filled: goes straight to Bitly shortening - If
原链接is empty but channel is set: builds the UTM URL from template first, then shortens - If both are empty: skips with a note
Pull click stats
/utm-link stats
Queries Bitly for all-time click counts on every tracked short link and writes them back to the 备注 (notes) field in Notion.
Format: 点击: 42 | 更新: 2024-03-15
Configuration
After first-time setup, your config lives at ~/.claude/utm-link/config.json. You can edit it directly to change any settings.
See config.example.json for the full structure with all options.
UTM templates
Each platform has a URL template with a {NAME} placeholder that gets replaced with the KOL's handle/name:
"utm_templates": {
"twitter": "https://yoursite.com/?utm_source=x&utm_medium=thread&utm_campaign=beta&utm_id={NAME}",
"youtube": "https://yoursite.com/?utm_source=youtube&utm_medium=video&utm_campaign=beta&utm_id={NAME}",
"discord": "https://discord.gg/yourcode?utm_source=Discord&utm_medium=invite&utm_campaign={NAME}",
"reddit": "https://yoursite.com/?utm_source=Reddit&utm_medium=community&utm_campaign=beta&utm_id={NAME}",
"linkedin": "https://yoursite.com/?utm_source=Linkedin&utm_medium=comment&utm_campaign={NAME}"
}
Replace yoursite.com with your actual domain. For Discord, replace yourcode with your server's invite code.
Channel options
Maps platform keys to the exact select option values in your Notion database:
"channel_options": {
"twitter": "2. Twitter",
"youtube": "3. YouTube",
"discord": "4. Discord",
"reddit": "5. Reddit",
"linkedin": "Linkedin KOL"
}
Change these to match your Notion select field values exactly.
Field name mapping
If your Notion database uses different field names:
"notion_field_map": {
"title": "",
"channel": "渠道",
"original_url": "原链接",
"utm_link": "UTM Link",
"notes": "备注"
}
Set "title": "" (empty string) for the title field — Notion always uses an empty-string key for the title property.
Notion database setup
Your Notion database needs these fields:
| Field | Type | Description |
|---|---|---|
| Title | Title | KOL name / handle |
| 渠道 | Select | Platform channel (Twitter, YouTube, etc.) |
| 原链接 | URL | Full UTM long URL |
| UTM Link | URL | Bitly short link |
| 备注 | Text | Notes / click stats |
You can rename the fields — just update notion_field_map in your config.
To get the notion_db_id, open your database in Notion and copy the page URL. The setup wizard extracts the UUID automatically.
Bitly plan limits
- Core plan ($10/mo): 100 links/month
- Growth plan ($29/mo): 500 links/month
The skill tracks usage and will stop immediately if you hit the monthly limit, with a clear message about which plan to upgrade to.
Reset config
To reconfigure from scratch (e.g. new Bitly token or new Notion database):
rm ~/.claude/utm-link/config.json
Then run /utm-link again to go through the setup wizard.
How it works
- Reads config from
~/.claude/utm-link/config.json - Parses the input URL(s) using pattern matching
- Calls the Notion MCP server to check for duplicates and fetch existing records
- Calls the Bitly API (
POST /v4/shorten) to generate short links - Calls the Notion MCP server to create or update rows
No server required. Everything runs locally through Claude Code's tool calls.
License
MIT