# Url Manager

> Save, organize, search, and share URLs as structured cards.

- **Type:** Skill
- **Install:** `agentstack add skill-piccolo123-url-manager-hermes-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Piccolo123](https://agentstack.voostack.com/s/piccolo123)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Piccolo123](https://github.com/Piccolo123)
- **Source:** https://github.com/Piccolo123/url-manager/tree/main/hermes-agent
- **Website:** https://ai.ocean94.com

## Install

```sh
agentstack add skill-piccolo123-url-manager-hermes-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# URL Manager Skill

URL Manager lets users save any link or text note into a structured, searchable library of card-based collections. Save from any platform — YouTube, Amazon, GitHub, Twitter. Organize with categories and tags. Share curated collections via invite links, and deliver organized results to users with a single magic link.

## When to Use

| Scenario | Action |
|----------|--------|
| User says "save/bookmark/collect/remember this" | `add` the URL with a title |
| User asks "what did I save about X" | `search` by keyword |
| User wants to organize their links | `categories` + `update` with category_ids |
| User wants to share a collection | `create-shared-category` + `create-invite-link` |
| User asks to bulk-reorganize | `batch-update` (max 50 per call) |
| Done organizing — deliver to user | `agent_magic_link` → send link |

**Do not** paste saved URLs into chat. Always write them into URL Manager and deliver via magic link.

## Prerequisites

- Python 3.10+
- Network access to `https://ai.ocean94.com`
- A registered account and auth token

The helper script at `scripts/footprints.py` handles token management and all API calls. All commands use the form:

```
python {baseDir}/scripts/footprints.py  [--json]
```

Add `--json` for machine-parseable output.

## How to Run

### First-time setup (account registration)

Before using this skill for the first time, the user needs an account. **Never auto-register without explicit consent.**

1. Tell the user: "This skill connects to ai.ocean94.com to store your saved links and data. It requires creating an account. Review the [Terms](https://ai.ocean94.com/terms.html) and [Privacy Policy](https://ai.ocean94.com/privacy.html). Shall I create an account for you?"
2. Wait for explicit "yes/ok/go ahead" from the user.
3. Run: `python {baseDir}/scripts/footprints.py agent_register`
4. The token is saved to your Hermes profile directory (`~/.hermes/profiles//.footprints_token` with `chmod 600`). Subsequent commands use it automatically.

If the user already has an account, ask them to get their token from https://ai.ocean94.com (Profile → Agent Access → Access Token) and run `python {baseDir}/scripts/footprints.py me` to verify it works.

### Returning user

Run `python {baseDir}/scripts/footprints.py me` to confirm identity. Then use any command below.

## Quick Reference

### Core commands

| Command | Purpose |
|---------|---------|
| `add "" --title "" [--description ""] [--content-type ""] [--category-ids ] [--tags ","]` | Save a link or text note (url can be empty) |
| `get ` | View full details of a footprint |
| `search ` | Full-text search across title, description, AI summary |
| `list [--category-id ] [--limit ] [--offset ]` | List footprints (limit max 100) |
| `update  [--title ""] [--description ""] [--category-ids ] [--tags ","]` | Modify a footprint |
| `batch-update ''` | Bulk update up to 50 footprints |

### Organization

| Command | Purpose |
|---------|---------|
| `categories` | List all categories grouped by category set |
| `create-category "" [--category-set-id ]` | Create a new category |
| `category-sets` | List all category sets (workspaces) |
| `create-category-set ""` | Create a new category set |
| `tags` | List all used tags |
| `content-types` | List content types in your library |

### Sharing

| Command | Purpose |
|---------|---------|
| `create-shared-category "" --mode cocreate\|subscribe` | Create a shared category |
| `create-invite-link  [--duration-hours 24]` | Generate invite code |
| `join-shared-category ` | Join via invite code |
| `add-to-shared  --collection-id ` | Add footprint to shared category |
| `remove-from-shared  --collection-id ` | Remove from shared category |
| `copy  --category-ids ` | Copy shared footprint to personal |

### Utilities

| Command | Purpose |
|---------|---------|
| `me` | Confirm current identity |
| `agent_magic_link` | Generate magic link for user delivery (valid 30 days, reusable) |
| `agent_register` | Create new account ⚠️ requires explicit user consent |

## Procedure

### New user workflow

```
1. Get explicit consent → agent_register
2. add "" → save the user's links
3. categories → discover existing structure
4. create-category "" → create organizational buckets
5. update  --category-ids  → categorize items
6. agent_magic_link → send link: "Done! View your collection → [link]"
```

### Daily use workflow

```
1. me → confirm identity
2. categories + tags → understand current structure
3. search  → find specific items
4. add / update / batch-update → operate
5. agent_magic_link → deliver results
```

### Team sharing workflow

```
1. create-shared-category "Team KB" --mode cocreate
2. create-invite-link  → share code with teammates
3. Teammates run: join-shared-category 
4. Everyone: add-to-shared  --collection-id  → build together
```

## Pitfalls

### category_ids is REPLACEMENT, not append

When updating, `--category-ids` sets the complete list. It does NOT add to existing categories. Always fetch current state first:

```bash
python {baseDir}/scripts/footprints.py get 42   # → categories: [{id: 3}, {id: 5}]
python {baseDir}/scripts/footprints.py update 42 --category-ids 3,5,7   # keep 3,5; add 7
```

### Subscribe mode is read-only

Writing to a subscribe-mode shared category returns HTTP 403. Tell the user the owner must switch it to cocreate mode.

### NEVER call agent_register without consent

Each call creates a fresh empty account. Always check for existing token with `me` first. Always get explicit user approval before registering.

### Rate limiting

Frequent API calls trigger HTTP 429. Use `batch-update` for bulk operations. Add delays between rapid calls.

### No member management via API

Inviting or removing members from shared categories requires the web UI. You cannot do this programmatically.

### Always

- **Get explicit consent before `agent_register`** — never auto-register
- Inform the user on first use: this skill connects to ai.ocean94.com, data is stored there
- Search before listing — use `search` for targeted queries
- Discover before creating — check existing categories and tags to avoid duplicates
- Deliver with magic link — after organizing, always generate and share a link

### Confirm before

- Removing footprint-category associations (irreversible)
- Clearing tags
- Modifying cocreate shared categories (affects others)
- Removing footprints from shared categories (other members lose access)

## Verification

After setting up or making changes, verify the skill works:

```bash
# 1. Confirm identity
python {baseDir}/scripts/footprints.py me --json

# 2. Create a test footprint
python {baseDir}/scripts/footprints.py add "https://example.com" --title "Test" --json

# 3. Search for it
python {baseDir}/scripts/footprints.py search "Test" --json

# 4. Cleanup — delete via the web UI at https://ai.ocean94.com
```

## Source & license

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

- **Author:** [Piccolo123](https://github.com/Piccolo123)
- **Source:** [Piccolo123/url-manager](https://github.com/Piccolo123/url-manager)
- **License:** MIT
- **Homepage:** https://ai.ocean94.com

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-piccolo123-url-manager-hermes-agent
- Seller: https://agentstack.voostack.com/s/piccolo123
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.