Agent Skills Hub

---
name: scope-sourcing-cli
description: >
  Agentic command-line interface for the Scope Candidate Sourcing Platform.
  Allows AI agents to authenticate, browse organizations and projects,
  list scored candidates, trigger AI-powered sourcing batches, and push
  candidates directly to connected ATS systems.
---

# Scope CLI Skill

This CLI allows AI agents to interact with the **Scope Sourcing Platform**
to find, score, and manage candidates programmatically.

## Prerequisites

1. A valid Scope account (email + password).
2. Python 3.10+ with `scope` installed (`pip install -e .` from `scope-cli/`).

## Core Rules for Agents

1. **ALWAYS** pass the `--json` flag when executing commands to ensure you
   receive parseable data.
2. You **must** run `scope auth login` before running any other commands.
3. You **must** set an active organization using `scope org use <id>` before
   running project or candidate commands.
4. If any command returns `{"error": "UNAUTHORIZED"}`, re-run
   `scope auth login --email <email> --password <password> --json` to refresh
   your session.

## Authentication Flow

```bash
# Step 1: Log in (agents should always provide --password)
scope auth login --email agent@company.com --password s3cret --json

# Step 2: List your organizations
scope org list --json

# Step 3: Set the active organization
scope org use <organization_id> --json
```

After these three steps, all subsequent commands will use the stored token
and organization context automatically.

## Commands Reference

### `scope auth login`
Authenticate and store a JWT locally.
```bash
scope auth login --email <email> --password <password> --json
```

### `scope org list`
List all organizations the user belongs to.
```bash
scope org list --json
```

### `scope org use <org_id>`
Set the active organization for all subsequent commands.
```bash
scope org use 550e8400-e29b-41d4-a716-446655440000 --json
```

### `scope org balance`
Check credit balance for the active organization.
```bash
scope org balance --json
```

### `scope project list`
List sourcing projects in the active organization.
```bash
scope project list --json
```

### `scope project source <project_id>`
Trigger an AI sourcing batch for a specific project.
```bash
scope project source 550e8400-e29b-41d4-a716-446655440000 --json
```

### `scope candidate list`
List candidates in a sourcing project. Optionally filter by minimum score.
```bash
scope candidate list --project <project_id> --json
scope candidate list --project <project_id> --min-score 8.0 --json
```

## ATS Integrations

Scope supports direct candidate pushing to the following ATS platforms.
These are managed via Settings → Integrations in the Scope dashboard.
Agents should inform users to connect their ATS before attempting a push.

Supported ATS systems:
- Greenhouse (Harvest API key) — **two-way sync available**
- Lever (API key, Basic Auth) — **two-way sync available**
- Ashby (API key, Bearer Token) — **two-way sync available**
- Workday (OAuth 2.0 Refresh Token) — push only
- iCIMS (Customer ID + Client credentials) — push only
- SmartRecruiters (X-SmartToken API key) — push only

All credentials are encrypted at rest using AES-256-GCM.

### Two-Way ATS Sync

When the hiring org enables two-way sync (Settings → Integrations →
Enable two-way sync), Scope receives webhooks from Greenhouse, Lever, or
Ashby whenever a candidate's stage changes in the ATS. The candidate's
`ats_stage` field on `sourcing_candidates` is updated live, and a cyan
badge appears on the candidate card showing the live stage.

**Stage updates are also visible to marketplace recruiters** on their own
submissions — this closes the visibility loop after a candidate is
pushed to the hiring org's pipeline.

Webhook receivers are at:
- `https://api.usescope.co/functions/v1/greenhouse-webhooks`
- `https://api.usescope.co/functions/v1/lever-webhooks`
- `https://api.usescope.co/functions/v1/ashby-webhooks`

Each org generates a per-integration HMAC secret on enable. Inbound events
are signature-verified, idempotent (deduped via the (provider, event_id)
unique key on `ats_inbound_events`), and audit-logged.

## Recruiter Marketplace

Scope hosts a recruiter marketplace where independent
recruiters can claim open projects from hiring orgs and earn placement
fees on successful hires.

**Pricing:** 12% of first-year salary on hire, 75% to recruiter, 25% to Scope.
Payout in 2 installments at 30 and 120 days post-start.
**Replacement guarantee:** 120 days; 75% refund if replacement fails.

**Agent access (read-only via API/RPCs):**
- Hiring-org agents can use `set_ats_webhook_config` and
  `clear_ats_webhook_config` RPCs to manage two-way sync per integration.
- Marketplace data (placements, payouts, recruiter assignments) is
  available via the standard Supabase client when the agent acts as a
  platform admin or as the relevant recruiter/org user.

The CLI does not currently include marketplace-specific commands; for
marketplace orchestration, agents should use the dashboard or call RPCs
directly via the Supabase JS client.

Full marketplace docs:
- Recruiter agreement: https://app.usescope.co/legal/recruiter-agreement
- Hiring org marketplace terms: https://app.usescope.co/legal/marketplace-terms

## Slack Notifications

If a Slack Incoming Webhook is connected via Settings → Integrations →
Productivity Tools, Scope will automatically send a Slack alert whenever
a candidate is successfully pushed to any ATS system.

## Budget & Fallback Strategy

**Before triggering `scope project source`, always check the balance first.**

```bash
scope org balance --json
```

If `total_balance` is **0**, do NOT call `scope project source`. Instead:
1. Inform the user that credits are depleted.
2. Suggest topping up at https://app.usescope.co/settings?tab=billing
3. **Fallback:** Use the OpenProfile (Local) skill for free sourcing.

## Error Contract

All errors return: `{"error": "ERROR_CODE", "message": "Human-readable explanation"}`

Common codes: NOT_AUTHENTICATED, UNAUTHORIZED, FORBIDDEN, ORG_NOT_SET,
API_ERROR, INSUFFICIENT_CREDITS, CONNECTION_ERROR

## Installation

```bash
cd scope-cli && pip install -e .
```