Agent Skills Hub

CLI alternative for agents without MCP support:

---
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.

> **Prefer MCP when available.** If your agent supports the Model Context
> Protocol (Claude Code, Claude Desktop, claude.ai), connect to the Scope MCP
> server instead: it exposes richer tools (including organization status and
> write actions) with API-key or OAuth auth. Setup guide:
> https://docs.usescope.co/connect-claude.html. Use this CLI when MCP is not
> an option.

## 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://db.usescope.co/functions/v1/greenhouse-webhooks`
- `https://db.usescope.co/functions/v1/lever-webhooks`
- `https://db.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 (pay on hire, tiered by service):**
- Full recruiter pipeline: 15% of first-year salary.
- Sourcing-only: 10% of first-year salary.
- Open-to-both listings: the rate of whoever delivers the hire (15% recruiter, 10% sourcer).
Recruiters earn 75% of the fee (rising to 78% / 82% at higher performance
tiers); sourcers earn 50% of the fee. Payout in 2 installments: at 30 days
post-start and at the end of the guarantee window.
**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**:
1. Free-plan organizations may still be able to source: every organization
   gets **10 free worker enrichments** and **5 free contact reveals**
   (non-expiring usage grants, no time-based trial). One attempt of
   `scope project source` is safe; if the grant is exhausted the API returns
   402 `FREE_ENRICHMENTS_EXHAUSTED` and you should stop.
2. On `INSUFFICIENT_CREDITS` or `FREE_ENRICHMENTS_EXHAUSTED`, inform the user
   and suggest topping up at https://app.usescope.co/settings?tab=billing
3. **Fallback:** Use the Scope Desktop (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 .
```