Building a connector

A connector is just a folder with a manifest and some skill files. The fastest way to build one is to copy a bundled reference connector of the same auth type and adapt it.

Connector layout

Directoryapps/community/my-app/
- manifest.json name, auth type, integration metadata
- SKILL.md human-readable overview
- Directoryskills/
  - sync.md a runnable skill
  - get-balance.md

When configured on a machine, its runtime state and synced data live separately, under ~/.prevail/connectors/my-app/ (auth/, data/, _log/). Keep credentials out of the definition folder — they belong in the machine-local runtime folder, which is never synced.

The manifest

manifest.json declares what the connector is and how it authenticates:

{
  "id": "my-app",
  "name": "My App",
  "auth": "oauth",
  "integration": "rest",
  "description": "Sync widgets from My App.",
  "oauth": {
    "authorizeUrl": "https://myapp.com/oauth/authorize",
    "tokenUrl": "https://myapp.com/oauth/token",
    "scopes": ["read:widgets"]
  }
}

The auth field is one of api, oauth, mcp, browser, or manual — it tells Prevail which probe and which auth flow to use. See the auth types.

Skills

Each file in skills/ is a runnable action, written like a domain skill — frontmatter plus steps. A connector skill typically reads from the connector’s auth, calls the app, and writes results into the connector’s data/ folder.

---
name: sync
description: Pull recent widgets into local storage
---

## Inputs
- **since** (optional): ISO date; defaults to the last sync cursor.

## Steps
1. Read the access token from `auth/`.
2. GET /widgets?since=<since>.
3. Append results to `data/widgets/YYYY-MM.jsonl`.
4. Update the cursor in `data/_meta.json`.

Run it with prevail connectors run my-app sync. → Using connectors

Auth-type checklists

api — document which environment variable holds the key; the probe checks it’s set.
oauth — fill in authorizeUrl, tokenUrl, and scopes; Prevail’s runner handles PKCE, the loopback callback, and refresh.
mcp — point at the MCP server command; the probe checks it starts.
browser — provide the Playwright steps to authenticate; the session is captured to auth/session.json.
manual — document where the user drops files; the probe checks the watched folder.

Contributing it back

The bundled connectors live in apps/community/. To share one, follow the same shape and open a PR — see CONTRIBUTING.md in the repo for the connector protocol and review checklist.