Skill: xisen-w/aicoo-share-agent (version 1.1.0)

--- name: share-agent description: "Use this skill when the user wants to share their AI agent with someone, generate a shareable link, require sign-in, allow anonymous access, let others talk to their agent, configure write access for guests, or manage existing shared links. Triggers on: 'share link', 'agent link', 'share my agent', 'let them talk to my AI', 'require sign-in', 'anonymous link', 'write access', 'edit access', 'guest permissions', or wanting to create a link for investors, prospects, partners, or anyone else to interact with their AI assistant." user-invokable: true metadata: author: systemind version: "2.0.0" --- # Share Agent Create and manage secure, shareable links to a user's agent. ## Prerequisites - `AICOO_API_KEY` must be set; legacy `PULSE_API_KEY` is also accepted - Base URL: `https://www.aicoo.io/api/v1` - User should sync context first - Command examples use `${AICOO_API_KEY:-$PULSE_API_KEY}` for backward compatibility ## Core Workflow ### 1) Check context exists ```bash curl -s -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \ "https://www.aicoo.io/api/v1/os/status" | jq . ``` If `contextCount` is 0, run `context-sync` first. ### 2) Create a share link (OS endpoint) ```bash curl -s -X POST "https://www.aicoo.io/api/v1/os/share" \ -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "scope":"all", "access":"read", "notesAccess":"read", "label":"For investors", "expiresIn":"7d", "requireSignIn":true }' | jq . ``` ### 3) Confirm to user Always report: 1. URL to share 2. Scope and notes/calendar permissions 3. Expiration 4. Sign-in requirement 5. Access is sandboxed Default behavior: new links require sign-in (`requireSignIn:true`). Only set `requireSignIn:false` when the user explicitly asks for an anonymous public link. ## Parameters | Parameter | Values | Description | |-----------|--------|-------------| | `scope` | `all` \| `folders` | `folders` requires `folderIds` | | `folderIds` | number[] | folder scope ids | | `access` | `read` \| `read_calendar` \| `read_calendar_write` | calendar access | | `notesAccess` | `read` \| `write` \| `edit` | notes permission | | `label` | string | link label | | `expiresIn` | `1h` \| `24h` \| `7d` \| `30d` \| `90d` \| `never` | expiration | | `requireSignIn` | boolean | Defaults to `true`. If true, `/a/<token>` and `/shared/<token>` require a signed-in Aicoo user. Signed-in guest sessions can track `guestUserId`, `guestName`, `guestUsername`, and `guestEmail`. Set `false` only for anonymous public links. | ## Notes Access Matrix | Operation | read | write | edit | |-----------|------|-------|------| | Search/read notes | yes | yes | yes | | Create notes | no | yes | yes | | Edit notes | no | no | yes | | Snapshots | no | no | yes | ## Manage Existing Links ### List links + visitors + contacts ```bash curl -s -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \ "https://www.aicoo.io/api/v1/os/network" | jq . ``` ### Update/revoke link (canonical OS endpoints) ```bash # update curl -s -X PATCH "https://www.aicoo.io/api/v1/os/share/{linkId}" \ -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \ -H "Content-Type: application/json" \ -d '{"notesAccess":"write","expiresIn":"30d","requireSignIn":true}' | jq . # revoke curl -s -X DELETE "https://www.aicoo.io/api/v1/os/share/{linkId}" \ -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" | jq . ``` ### List links with analytics ```bash curl -s -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \ "https://www.aicoo.io/api/v1/os/share/list?status=active&limit=20" | jq . ``` ## Folder-Scoped Share Example ```bash # inspect folders first curl -s -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \ "https://www.aicoo.io/api/v1/os/folders" | jq . # create folder-scoped link curl -s -X POST "https://www.aicoo.io/api/v1/os/share" \ -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \ -H "Content-Type: application/json" \ -d '{"scope":"folders","folderIds":[5,12],"access":"read","notesAccess":"write","label":"Team collaborator","requireSignIn":true}' | jq . ``` ## Per-Link Policy Editing Link notes are stored in `links/` folder. Edit policy by searching notes then patching note content: ```bash # find link policy note curl -s -X POST "https://www.aicoo.io/api/v1/os/notes/search" \ -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \ -H "Content-Type: application/json" \ -d '{"query":"For-Investors"}' | jq . # edit policy note content curl -s -X PATCH "https://www.aicoo.io/api/v1/os/notes/123" \ -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \ -H "Content-Type: application/json" \ -d '{"content":"...\n\n## Policy\n\nBe professional, concise, and do not disclose confidential numbers."}' | jq . ``` ## Security Notes - Every link runs inside isolated scope - New links require sign-in by default unless `requireSignIn:false` is explicitly set - Signed-in visitors can appear in analytics with name, username, email, and user id; anonymous links only have guest-session/fingerprint metadata - Revoked/expired links lose access immediately - Default expiration is 30 days unless overridden - Use `notesAccess: "edit"` carefully

path: examples/basic-share.md
content: # Example: Share Agent with an Investor

## Scenario
You're a founder preparing for a fundraise. You want to share your AI agent with potential investors so they can learn about your company before the first meeting.

## Step-by-step

### 1. Sync your investor materials
```
> "Sync all my files in ./investor-materials to Aicoo"
```
The agent reads files from `./investor-materials/` and uploads them to a "Investor Materials" folder on Aicoo.

### 2. Create a share link
```
> "Create a share link for investors, read-only, expires in 7 days"
```
The agent calls `POST /share/create` with:
```json
{
  "scope": "folders",
  "folderIds": ["<investor-materials-folder-id>"],
  "access": "read",
  "label": "For investors - Series A",
  "expiresIn": "7d",
  "requireSignIn": true
}
```

### 3. Get the link
The agent returns:
```
Your shareable agent link:
https://www.aicoo.io/s/a1b2c3d4...

Signed-in recipients with this link can talk to your agent about your investor materials.
- Scope: Investor Materials folder only
- Access: Read-only (no calendar, no email)
- Expires: April 9, 2026
- Sign-in required for recipients
```

### 4. Share it
Send the link via email, WhatsApp, LinkedIn, or any messaging platform. Recipients open the link, sign in, and then chat with your AI agent. For anonymous public access, explicitly set `requireSignIn:false`.

### 5. Check how it's going
```
> "How many people have used my investor link?"
```
The agent calls the analytics endpoint and reports visitor count, conversation count, and top questions asked.


path: reference/API.md
content: # Share Agent API Reference

Base URL: `https://www.aicoo.io/api/v1`

All endpoints require `Authorization: Bearer <AICOO_API_KEY>`. Legacy `PULSE_API_KEY` is also accepted.

---

## POST /os/share

Create a new shareable agent link.

**Request Body:**

```json
{
  "scope": "all" | "folders",
  "access": "read" | "read_calendar" | "read_calendar_write",
  "notesAccess": "read" | "write" | "edit",
  "label": "string (optional)",
  "expiresIn": "1h" | "24h" | "7d" | "30d" | "90d" | "never",
  "folderIds": [1, 2, 3],
  "requireSignIn": true
}
```

`requireSignIn` defaults to `true`. When true, `/a/<token>` and `/shared/<token>` require a signed-in Aicoo user. Headless callers such as Claude Code can satisfy the same requirement by passing `Authorization: Bearer <AICOO_API_KEY>` to `guest-v04`. Signed-in guest-session analytics can include `guestUserId`, `guestName`, `guestUsername`, and `guestEmail`. Set `requireSignIn:false` only when the user explicitly wants an anonymous public link.

---

## GET /os/share/list

List links with analytics, effective capabilities, and `requireSignIn`.

**Query Params:**
- `status`: `active` | `revoked` | `all`
- `limit`: 1..50

---

## PATCH /os/share/{linkId}

Update link settings (`scope`, `folderIds`, `access`, `notesAccess`, `label`, `expiresIn`, `requireSignIn`, `identity`, `email`, `todos`, `tools`).

**Body examples:**

```json
{ "requireSignIn": true }
```

```json
{ "requireSignIn": false }
```

---

## DELETE /os/share/{linkId}

Revoke a share link.

---

## GET /os/network

High-level network state:
- `shareLinks`
- `visitors` (signed-in visitors may include name, username, email, and user id)
- `contacts`

---

## Notes

- Sharing/network are OS-native (`/os/*`).
- `/tools` is reserved for non-OS integrations/tools execution.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal:  | SkillSpector: suspicious (CRITICAL)