---
name: workspace-outreach
description: |
  Operate a workspace on this outreach platform -- prospects, sequences, search,
  outreach, approvals, suppressions. Use when the user asks to run outreach
  activity, check their book, import/enroll prospects, send connections or
  InMails, clear the approval queue, or manage outreach via the REST API or
  workspace MCP.
triggers:
  - fireapp
  - /fireapp
  - fire app
  - fireapp prospects
  - fireapp sequence
  - fireapp approvals
  - fireapp outreach
  - connect ai agent
invocable: true
argument-hint: "[action] [args...]"
---

# Workspace operator (agent skill)

Operate the user's workspace via workspace API key (`ufa_...`).

**Replace `YOUR-ORIGIN`** below with the user's app hostname (where they sign in).

Product docs: `YOUR-ORIGIN/docs/agents/`

## Authentication

```bash
export UFA_API_KEY="$(cat ~/.config/outreach-agent/api_key)"
export UFA_ORIGIN="https://YOUR-ORIGIN"
```

All REST calls: `-H "X-ApiKey: $UFA_API_KEY"`. Base: `$UFA_ORIGIN/api/v1`.

- REST semantics: `YOUR-ORIGIN/docs/public-api.md`
- OpenAPI: `YOUR-ORIGIN/docs/openapi.json`

**Never** commit or paste API keys into skills, chat logs, or git. Roll in
Settings -> Integrations if exposed.

## Two integration surfaces

| Surface | When to use |
|---------|-------------|
| **Workspace MCP** (`/mcp`) | Native agent tools -- list/import/enroll, search, connect, message, approvals, suppressions, billing, reports |
| **REST API** (`/api/v1/*`) | Same operations via HTTP -- useful for scripting or clients without MCP support |

MCP tools: `whoami`, `list_prospects`, `get_prospect`, `explain_prospect`, `list_tags`,
`list_sequences`, `list_templates`, `append_prospects`, `create_tag`,
`assign_tag`, `enroll_prospects`, `search_people`, `draft_message`, `connect_prospect`,
`message_prospect`, `list_inbox`, `list_approvals`,
`approve_workspace_send`, `complete_workspace_send`, `reject_workspace_send`,
`bulk_approve_workspace_sends`, `list_suppressions`, `add_suppression`,
`remove_suppression`, `update_prospect`, `archive_prospect`, `unarchive_prospect`, `cancel_enrollment`,
`resume_enrollment`, `get_targeting_brief`, `update_targeting_brief` (including locations / industries / remoteOk),
`compile_brief_search_plan`, `run_brief_people_search`, `score_prospects`,
`get_plan_status`, `get_upgrade_options`, `get_workspace_report`,
`get_send_health`, `lookup_linkedin_taxonomy` -- every workspace agent tool is on MCP now.

REST remains available for the same operations (`POST /search`,
`POST .../connect`, `POST .../message`, approvals,
suppressions, enrollment cancel/resume) -- use whichever surface your
client prefers; both call the same handlers.

**Operator MCP** (`/mcp/operator`, key `ufa_op_...`) is for multi-book
coach/operator seats -- not workspace keys. Book fill: Autopilot owns the
unattended feed (`run_brief_people_search` is the same pipeline). Repair a mush
brief with `update_targeting_brief` (structured locations / industries, never
invent chip ids; look industries up with `lookup_linkedin_taxonomy` and pass
`{ id }`), then compile. Hand `search_people` is a permutation fallback,
not the daily feeder. Keep-list matches the Autopilot propose_import gate.

## Agent invariants

1. **Read before write** -- workspace, channels, sequences before mutating.
2. **Rate limits** -- 60 writes/min/key; `POST /search` counts as a write and
   spends a paid provider request.
3. **No blind retries on sends** -- under HITL, connect/message stage (not
   idempotent). Check `GET /approvals` first.
4. **Branch on `reason`** -- send failures return `{ error, reason }`.
5. **Suppressions are absolute** -- suppressed prospects cannot be reached.
6. **Confirm bulk/destructive actions** with the user before executing.
7. **Default channel** -- LinkedIn `channelId` from `GET /channels`.

## CLI (optional)

If `scripts/ufa.sh` is installed:

```bash
ufa.sh whoami
ufa.sh channels
ufa.sh prospects --limit 20 --q "Acme"
ufa.sh sequences
ufa.sh approvals
ufa.sh search --url 'https://www.linkedin.com/search/results/people/?keywords=...'
ufa.sh import prospects.json
ufa.sh enroll SEQUENCE_ID prs_a prs_b
ufa.sh connect prs_id [--note 'Hi ...']
ufa.sh message prs_id --body '...'
ufa.sh approve APPROVAL_ID [--body 'edited text']
```

Requires `UFA_ORIGIN` and key in env or `~/.config/outreach-agent/api_key`.

## Workflows

See `YOUR-ORIGIN/docs/agents/use-cases.md` for full playbooks.

### Daily book check

1. `GET /workspace`
2. `GET /approvals`
3. `GET /prospects?limit=500`
4. `GET /sequences`

### Search -> import -> enroll

1. `GET /channels` -> LinkedIn `channelId`
2. `POST /search` `{ channelId, url }`
3. `POST /prospects` with selected candidates
4. `PUT /sequences/{id}/prospects` with prospect ids

### Approval queue (HITL)

```bash
GET  /approvals?limit=100
POST /approvals/{id}/approve     # optional { editedBody }
POST /approvals/{id}/complete
```

## MCP setup (Cursor / Claude)

```json
{
  "mcpServers": {
    "workspace-outreach": {
      "url": "https://YOUR-ORIGIN/mcp",
      "headers": { "X-ApiKey": "ufa_..." }
    }
  }
}
```

Verify: `curl -s -o /dev/null -w '%{http_code}\n' -H "X-ApiKey: ..." https://YOUR-ORIGIN/mcp` -> `405`.

MCP covers every workspace agent tool, including search/sends/approvals/suppressions -- prefer it when your client supports MCP; REST or `ufa.sh` work the same way for scripting.

## Reference

- Route cheat sheet: [reference.md](reference.md)
- Installation: `/docs/agents/installation.md`
- Use cases: `/docs/agents/use-cases.md`