mpm-url-shortener/SKILL.md

---
name: mpm-url-shortener
description: Manages short URLs on MPM's mpm.to YOURLS instance. Use this skill whenever the user wants to create, look up, expand, update, or delete short links at mpm.to. Triggers on phrases like "create a short link", "make a short URL for", "what does mpm.to/X go to", "delete the mpm.to link", "update the short code", "list our short URLs", "add a short link", "mpm link", "short code", "shortcode", "shorten this URL", or any mention of mpm.to URLs. Also use when the user says things like "can you shorten that" or "set up a link for the new campaign".
---

# MPM URL Shortener

Manages short URLs on MPM's YOURLS instance at `https://mpm.to`. Supports full CRUD — create, read/list, update, and delete — using only the API signature token. No username or password is stored.

## How it works

- **Create & Read** always use the YOURLS API with the signature token — no password needed.
- **Update & Delete** use one of two methods, tried in order:
  1. **API + plugin** (preferred): If the `mpm-api-extras` plugin is active on the server, the signature token handles everything.
  2. **Admin session fallback**: If the plugin isn't installed, the script logs into the YOURLS admin interface using a stored username + password.

The bundled script `scripts/yourls_manager.py` handles the switching automatically — you don't need to think about which method is in use.

---

## One-time plugin installation (recommended)

Installing the plugin means only the signature token is ever needed. No passwords in Keychain.

See `plugin/INSTALL.md` for instructions to pass to your server admin.

---

## First-time credential setup

Run once:

```bash
python3 <SKILL_DIR>/scripts/yourls_manager.py setup
```

- **Signature token** — always required
- **Admin username + password** — optional; only needed if the plugin is not installed

Credentials are stored in macOS Keychain under service `mpm.to-yourls`. To verify and test the live connection:

```bash
python3 <SKILL_DIR>/scripts/yourls_manager.py check
```

The `check` command also tells you whether the plugin is active.

---

## Operations

Replace `<SKILL_DIR>` with the actual path to this skill's directory.

### Create a short URL

```bash
python3 <SKILL_DIR>/scripts/yourls_manager.py create \
  --url "https://the-long-url.com/path" \
  [--keyword "mycode"] \
  [--title "Human-readable title"]
```

- `--keyword` is optional; YOURLS auto-generates one if omitted
- `--title` is optional but good practice
- Returns the new short URL and confirmation

### Read / look up a short URL

```bash
python3 <SKILL_DIR>/scripts/yourls_manager.py read --keyword "mycode"
```

Returns: long URL, title, click count, date created.

### List short URLs

```bash
python3 <SKILL_DIR>/scripts/yourls_manager.py list [--limit 50] [--filter top|bottom|last|rand]
```

Defaults to the 50 most-clicked links. Use `--filter last` to see the most recently created.

### Update a short URL

```bash
python3 <SKILL_DIR>/scripts/yourls_manager.py update \
  --keyword "mycode" \
  [--url "https://new-destination.com"] \
  [--newkeyword "newcode"] \
  [--title "Updated Title"]
```

Requires admin credentials. At least one of `--url`, `--newkeyword`, or `--title` must be provided.

### Delete a short URL

```bash
python3 <SKILL_DIR>/scripts/yourls_manager.py delete --keyword "mycode"
```

Requires admin credentials. Asks for confirmation before deleting unless `--force` is passed.

---

## Presenting results

After running any operation, present results conversationally:

- **Create**: "Done! `mpm.to/mycode` now points to [long URL]."
- **Read**: Show short URL, destination, title, click count, and age.
- **List**: Render as a clean table with columns: Short Code | Destination | Clicks | Created.
- **Update**: Confirm what changed.
- **Delete**: Confirm deletion.

If an operation fails, read the error output and explain it clearly to the user — don't just dump the raw error.

---

## Troubleshooting

| Error | Likely cause | Fix |
|---|---|---|
| `No signature token` | First-time use | Run `setup` |
| `'delete'/'update' action not recognised` | Plugin not installed | Script will auto-fall back to admin session if credentials are stored |
| `Plugin not active; no admin credentials` | Neither method available | Install plugin OR run `setup` to add username + password |
| `Admin login failed` | Wrong password | Re-run `setup` to update stored credentials |
| `Keyword already exists` | Short code taken | Choose a different `--keyword` |
| `Short URL not found` | Keyword doesn't exist | Check spelling; use `list` to browse |
| `requests` module not found | Missing dependency | Run `pip3 install requests --break-system-packages` |