@superagnt/superagnt 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,83 @@
1
+ # superagnt_ for OpenClaw — the agent value layer
2
+
3
+ The agent value layer: one MCP connection = every data source (X, TikTok, YouTube, Instagram, Reddit, LinkedIn, web), people + company enrichment, a real workspace Postgres, schedules, webhooks and shareable canvases — plus the base skills that teach the workflows. OAuth on first use; the consent screen doubles as signup.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ openclaw plugins install @superagnt/superagnt
9
+ ```
10
+
11
+ Installing the plugin loads the base skills and declares the superagnt MCP
12
+ server (`https://mcp.superagnt.com/mcp`) as a default.
13
+
14
+ ## Connect
15
+
16
+ ```bash
17
+ openclaw superagnt connect
18
+ ```
19
+
20
+ OAuth in the browser; the consent screen doubles as signup if you don't have
21
+ an account yet. After login the live tool surface is available in every
22
+ OpenClaw session — and it grows server-side (`agnt_tools_enable`), no plugin
23
+ update needed.
24
+
25
+ <details>
26
+ <summary>What connect does (or run it manually)</summary>
27
+
28
+ `openclaw mcp login` only resolves servers saved in config, so connect saves
29
+ the server under the same name as the plugin-declared default (OpenClaw's
30
+ sanctioned override) and then runs the login:
31
+
32
+ ```bash
33
+ openclaw mcp add superagnt --url https://mcp.superagnt.com/mcp --transport streamable-http --auth oauth
34
+ openclaw mcp login superagnt
35
+ ```
36
+
37
+ </details>
38
+
39
+ ## What you get
40
+
41
+ One MCP connection carries the whole value layer:
42
+
43
+ - **Data sources** — X, TikTok, YouTube, Instagram, Reddit, LinkedIn, and web
44
+ scraping, as structured JSON tools
45
+ - **People + company enrichment** — search, enrich, verified emails
46
+ - **Workspace database** — a real Postgres per workspace, with migrations
47
+ - **Schedules & webhooks** — recurring automations and inbound event ingestion
48
+ - **Canvases** — shareable live dashboards
49
+
50
+ ## Bundled skills
51
+
52
+ The same base skills as the superagnt Claude Code plugin, teaching the
53
+ workflows on top of the tools:
54
+
55
+ - `superagnt-automations`
56
+ - `superagnt-canvas`
57
+ - `superagnt-data-pipelines`
58
+ - `superagnt-data-sources`
59
+ - `superagnt-lead-generation`
60
+ - `superagnt-setup`
61
+ - `superagnt-task-agents`
62
+ - `superagnt-workspace-db`
63
+
64
+ ## Prefer fixed, API-key tools?
65
+
66
+ The per-platform data plugins (`@superagnt/reddit-data`,
67
+ `@superagnt/linkedin-data`, …) and the `@superagnt/openclaw-agnt-data` master
68
+ plugin ship baked toolsets that authenticate with just a `SUPERAGNT_API_KEY`
69
+ — no OAuth, no MCP handshake. Install those instead when you want a minimal
70
+ fixed surface.
71
+
72
+ ## CLI
73
+
74
+ ```bash
75
+ openclaw superagnt status # configured key (masked) + login hint
76
+ openclaw superagnt doctor # connectivity + auth checks
77
+ ```
78
+
79
+ ## Links
80
+
81
+ - Product: https://superagnt.com
82
+ - Dashboard: https://app.superagnt.com/dashboard
83
+ - Docs: https://superagnt.com/docs
package/index.js ADDED
@@ -0,0 +1,157 @@
1
+ /**
2
+ * superagnt — OpenClaw plugin
3
+ * The MCP server (declared in openclaw.plugin.json) carries the tool surface;
4
+ * this body registers the CLI. Auto-generated by @superagnt/clawhub. Do not
5
+ * edit by hand.
6
+ */
7
+
8
+ import { homedir as _homedir } from 'node:os'
9
+ import { join as _join } from 'node:path'
10
+ import { existsSync as _existsSync, readFileSync as _readFileSync } from 'node:fs'
11
+ import { spawnSync as _spawnSync } from 'node:child_process'
12
+
13
+
14
+ // ── Auth Module (inlined) ────────────────────────────────────────────────────
15
+
16
+ function getConfigPath() {
17
+ return _join(_homedir(), '.superagnt', 'config.json')
18
+ }
19
+
20
+ function readAgntConfig() {
21
+ const configFile = getConfigPath()
22
+ if (!_existsSync(configFile)) return null
23
+ try {
24
+ return JSON.parse(_readFileSync(configFile, 'utf-8'))
25
+ } catch {
26
+ return null
27
+ }
28
+ }
29
+
30
+ // ── End Auth Module ──────────────────────────────────────────────────────────
31
+
32
+
33
+ // ── CLI Module (inlined) ─────────────────────────────────────────────────────
34
+
35
+ function maskApiKey(key) {
36
+ if (!key || typeof key !== 'string') return '(none)'
37
+ const k = key.trim()
38
+ if (k.length <= 8) return k.slice(0, 2) + '…'
39
+ return k.slice(0, 6) + '…' + k.slice(-4)
40
+ }
41
+
42
+ function registerAgntCli(api) {
43
+ api.registerCli(
44
+ ({ program }) => {
45
+ const cmd = program
46
+ .command('superagnt')
47
+ .description('superagnt — connect the MCP surface, check status, run doctor')
48
+
49
+ cmd
50
+ .command('connect')
51
+ .description('Wire up the live MCP tool surface: save the server config, then run OAuth login')
52
+ .action(async () => {
53
+ const MCP_ARGS = ['--url', 'https://mcp.superagnt.com/mcp', '--transport', 'streamable-http', '--auth', 'oauth']
54
+ const run = (args, quiet) => _spawnSync('openclaw', args, { stdio: quiet ? 'ignore' : 'inherit', shell: false })
55
+ const probe = run(['mcp', 'show', 'superagnt'], true)
56
+ if (probe.error) {
57
+ console.log('\nCould not run the "openclaw" binary from PATH. Run these two commands manually:\n')
58
+ console.log(' openclaw mcp add superagnt ' + MCP_ARGS.join(' '))
59
+ console.log(' openclaw mcp login superagnt\n')
60
+ process.exitCode = 1
61
+ return
62
+ }
63
+ if (probe.status !== 0) {
64
+ console.log('\nSaving MCP server "superagnt"…')
65
+ const add = run(['mcp', 'add', 'superagnt', ...MCP_ARGS])
66
+ if (add.status !== 0) {
67
+ process.exitCode = add.status ?? 1
68
+ return
69
+ }
70
+ } else {
71
+ console.log('\nMCP server "superagnt" already saved.')
72
+ }
73
+ console.log('Starting OAuth login (the consent screen doubles as signup)…\n')
74
+ const login = run(['mcp', 'login', 'superagnt'])
75
+ process.exitCode = login.status ?? 0
76
+ })
77
+
78
+ cmd
79
+ .command('status')
80
+ .description('Show whether an API key is configured (masked)')
81
+ .action(async () => {
82
+ const cfg = readAgntConfig()
83
+ const key = cfg?.apiKey
84
+
85
+ console.log('\nsuperagnt status\n')
86
+ if (!key) {
87
+ console.log(' API key: not configured (only needed for the data plugins)')
88
+ console.log(' Workspace: —')
89
+ console.log(' Live tools: run "openclaw superagnt connect" to authorize the MCP surface')
90
+ console.log('\n Get your API key at: https://app.superagnt.com/dashboard\n')
91
+ return
92
+ }
93
+ console.log(' API key: ' + maskApiKey(key) + ' (from ~/.superagnt/config.json)')
94
+ console.log(' Workspace: ' + (cfg?.workspaceId ?? '—'))
95
+ console.log(' Live tools: run "openclaw superagnt connect" to authorize the MCP surface')
96
+ console.log('')
97
+ })
98
+
99
+ cmd
100
+ .command('doctor')
101
+ .description('Check connectivity and validate API key against api.superagnt.com')
102
+ .action(async () => {
103
+ console.log('\nsuperagnt doctor\n')
104
+
105
+ try {
106
+ const publicRes = await fetch('https://api.superagnt.com/v1/platforms')
107
+ console.log(' Public API: ' + (publicRes.ok ? 'OK (' + publicRes.status + ')' : 'HTTP ' + publicRes.status))
108
+ } catch (err) {
109
+ const msg = err instanceof Error ? err.message : String(err)
110
+ console.log(' Public API: failed — ' + msg)
111
+ }
112
+
113
+ const cfg = readAgntConfig()
114
+ const key = cfg?.apiKey
115
+
116
+ if (!key) {
117
+ console.log('\n Authenticated: skipped (no API key)')
118
+ console.log(' Get your API key at: https://app.superagnt.com/dashboard\n')
119
+ return
120
+ }
121
+
122
+ try {
123
+ const res = await fetch('https://api.superagnt.com/v1/platforms', {
124
+ headers: { Authorization: 'Bearer ' + key },
125
+ })
126
+ const text = await res.text()
127
+ let summary = 'HTTP ' + res.status
128
+ if (res.ok) {
129
+ try {
130
+ const json = JSON.parse(text)
131
+ const n = Array.isArray(json?.data) ? json.data.length : (json?.data ? Object.keys(json.data).length : 'ok')
132
+ summary = 'OK — platforms payload received (' + (typeof n === 'number' ? n + ' entries' : String(n)) + ')'
133
+ } catch {
134
+ summary = 'OK (' + res.status + ')'
135
+ }
136
+ }
137
+ console.log(' Authenticated: ' + summary)
138
+ if (!res.ok) {
139
+ console.log(' If 401, get a new key at: https://app.superagnt.com/dashboard')
140
+ }
141
+ } catch (err) {
142
+ const msg = err instanceof Error ? err.message : String(err)
143
+ console.log(' Authenticated: failed — ' + msg)
144
+ }
145
+ console.log('\n Live MCP tools: run "openclaw superagnt connect" (OAuth; the consent screen doubles as signup)')
146
+ console.log('')
147
+ })
148
+ },
149
+ { commands: ['superagnt'] },
150
+ )
151
+ }
152
+
153
+ // ── End CLI Module ───────────────────────────────────────────────────────────
154
+
155
+ export default function register(api) {
156
+ registerAgntCli(api)
157
+ }
@@ -0,0 +1,31 @@
1
+ {
2
+ "id": "superagnt",
3
+ "name": "superagnt_",
4
+ "description": "The agent value layer: one MCP connection = every data source (X, TikTok, YouTube, Instagram, Reddit, LinkedIn, web), people + company enrichment, a real workspace Postgres, schedules, webhooks and shareable canvases — plus the base skills that teach the workflows. OAuth on first use; the consent screen doubles as signup.",
5
+ "version": "2.0.3",
6
+ "mcpServers": {
7
+ "superagnt": {
8
+ "url": "https://mcp.superagnt.com/mcp",
9
+ "transport": "streamable-http",
10
+ "auth": "oauth"
11
+ }
12
+ },
13
+ "skills": [
14
+ "skills/superagnt-automations",
15
+ "skills/superagnt-canvas",
16
+ "skills/superagnt-data-pipelines",
17
+ "skills/superagnt-data-sources",
18
+ "skills/superagnt-lead-generation",
19
+ "skills/superagnt-setup",
20
+ "skills/superagnt-task-agents",
21
+ "skills/superagnt-workspace-db"
22
+ ],
23
+ "cliCommands": [
24
+ "superagnt"
25
+ ],
26
+ "configSchema": {
27
+ "type": "object",
28
+ "properties": {},
29
+ "additionalProperties": false
30
+ }
31
+ }
package/package.json ADDED
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "@superagnt/superagnt",
3
+ "version": "2.0.3",
4
+ "type": "module",
5
+ "description": "The agent value layer: one MCP connection = every data source (X, TikTok, YouTube, Instagram, Reddit, LinkedIn, web), people + company enrichment, a real workspace Postgres, schedules, webhooks and shareable canvases — plus the base skills that teach the workflows. OAuth on first use; the consent screen doubles as signup.",
6
+ "main": "index.js",
7
+ "license": "MIT",
8
+ "homepage": "https://superagnt.com/agent-toolkit",
9
+ "keywords": [
10
+ "openclaw",
11
+ "openclaw-plugin",
12
+ "superagnt",
13
+ "mcp",
14
+ "data",
15
+ "database",
16
+ "automation",
17
+ "lead-generation",
18
+ "canvas",
19
+ "ai-agent"
20
+ ],
21
+ "publishConfig": {
22
+ "access": "public"
23
+ },
24
+ "files": [
25
+ "index.js",
26
+ "openclaw.plugin.json",
27
+ "README.md",
28
+ "skills"
29
+ ],
30
+ "openclaw": {
31
+ "extensions": [
32
+ "./index.js"
33
+ ],
34
+ "compat": {
35
+ "pluginApi": ">=2026.3.24-beta.2",
36
+ "minGatewayVersion": "2026.3.24-beta.2"
37
+ },
38
+ "build": {
39
+ "openclawVersion": "2026.3.24-beta.2",
40
+ "pluginSdkVersion": "2026.3.24-beta.2"
41
+ }
42
+ }
43
+ }
@@ -0,0 +1,63 @@
1
+ ---
2
+ name: superagnt-automations
3
+ description: This skill should be used when work should be triggered by an event: "when X happens, do Y", "when a form is submitted", "when Stripe/GitHub fires a webhook", "notify my system when this finishes", or wiring superagnt to Zapier, Make, or any backend. Covers superagnt inbound and outbound webhooks — receiving events that trigger hosted work, sending signed results out, and inspecting deliveries. For cron-style recurring runs, use the task-agents skill.
4
+ version: 0.2.0
5
+ ---
6
+
7
+ # Event-driven work on superagnt
8
+
9
+ Webhooks are how superagnt reacts to the outside world instead of being asked.
10
+ An inbound endpoint gives any external system (a SaaS, a form, a backend, a
11
+ Zapier zap) a URL that triggers work in the workspace; an outbound endpoint
12
+ lets an agent push results to a system the user already runs. This is what
13
+ most recurring needs actually are — "when a lead signs up", "when a payment
14
+ fails" — an event, not a clock. Reach for a schedule (task-agents skill) only
15
+ when no event exists to hook.
16
+
17
+ ## Always available (no setup)
18
+
19
+ - `agnt_webhooks_inbound_url` — the workspace's inbound ingest URL.
20
+ - `agnt_webhooks_receive_recent` — read recent inbound deliveries in-session.
21
+ - `agnt_webhooks_send` — POST a payload to a configured outbound endpoint.
22
+
23
+ The simplest loop needs nothing else: hand the inbound URL to the external
24
+ system, then read deliveries with `receive_recent` when the session runs.
25
+
26
+ ## The management family (`webhooks`)
27
+
28
+ `agnt_webhooks_create_endpoint`, `create_outbound`, `list_endpoints`,
29
+ `link_agent`, `link_data_job`, `set_active`, `rotate_secret`,
30
+ `list_deliveries`, `get_delivery`. Enable with
31
+ `agnt_tools_enable(['webhooks'])` — sold under the Automation module (free
32
+ trial); a `requires_upgrade` result carries a `confirm_url` for the human.
33
+ Hand the link over and wait; never treat it as an error.
34
+
35
+ Three patterns, in the order clients usually need them:
36
+
37
+ 1. **Event → hosted agent.** `agnt_webhooks_create_endpoint` with
38
+ `deployed_agent_id`: every delivery starts a session on that agent with
39
+ the payload — work fires with nobody at a keyboard. Build the agent first
40
+ (task-agents skill); a draft agent ingests but does not fan out until
41
+ deployed.
42
+ 2. **Event → data job.** Bind with `data_job_id` instead: each delivery
43
+ enqueues one job item (raw JSON body as payload). Use for high-volume,
44
+ non-conversational ingestion — a SaaS firing one webhook per record
45
+ (data-pipelines skill).
46
+ 3. **Agent → outside world.** `agnt_webhooks_create_outbound`
47
+ (`target_kind=external`, the URL) then `agnt_webhooks_send`. Payloads are
48
+ HMAC-SHA256 signed by default; the secret is returned ONCE at creation —
49
+ store it, or `rotate_secret` later. `target_kind=agent` chains two
50
+ deployed agents (signing forced on).
51
+
52
+ ## Debugging deliveries
53
+
54
+ `agnt_webhooks_list_deliveries` / `get_delivery` show what actually arrived
55
+ and how it was acked. Check there before assuming the upstream never fired.
56
+
57
+ ## More
58
+
59
+ - Schedules (cron) moved to the task-agents skill — see its `schedules.md`.
60
+ - Live setup + endpoint reference: https://superagnt.com/agent-setup/prompt.md
61
+ - Packaged event-driven workflows: https://superagnt.com/blueprints
62
+
63
+ <!-- skill_id: automations · source: https://github.com/superagnt/plugins -->
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: superagnt-canvas
3
+ description: This skill should be used when the user asks for a "dashboard", "shareable report", "KPI page", or "live chart", or wants results as a URL someone else can open. Covers superagnt canvases: widgets bound to workspace-database queries (KPI rows, trends, funnels, tables, kanban), layout discipline, and share links. Use after data lands in the workspace database; see workspace-db for table design.
4
+ version: 0.2.0
5
+ ---
6
+
7
+ # Canvases: results as a living page
8
+
9
+ A canvas is a hosted page of widgets, each bound to a SQL query over the
10
+ workspace database. It stays current as the data changes, and a share link
11
+ opens for anyone — no account needed on the viewer's side.
12
+
13
+ ## Procedure
14
+
15
+ 1. Data first. Widgets bind to tables; if the table does not exist yet, the
16
+ workspace-db skill's patterns come first.
17
+ 2. `agnt_canvas_introspect_schema` to see what is bindable, then
18
+ `agnt_canvas_preview_query` BEFORE `agnt_canvas_put_widget` — previews
19
+ are capped at 50 rows, so aggregate in SQL (`group by date_trunc`), never
20
+ in the widget.
21
+ 3. Build the page: `agnt_canvas_put_widget` per widget,
22
+ `agnt_canvas_set_layout` once at the end.
23
+ 4. Share: `agnt_canvas_share_create` returns the public link;
24
+ `agnt_canvas_share_revoke` kills it. Confirm with the user before
25
+ creating a share link — it makes the page reachable outside the
26
+ workspace.
27
+
28
+ ## Layout discipline
29
+
30
+ - Lead with a KPI row (3–5 single numbers), then trends, then detail tables.
31
+ - One measure per widget; failed/error series in the danger tone, never the
32
+ accent.
33
+ - Time widgets need `event_at`/`created_at` timestamptz columns; funnels and
34
+ kanbans bind to stable status strings — schema rules in workspace-db.
35
+ - If the canvas family is not enabled: `agnt_tools_enable(['canvas'])` —
36
+ sold under the Database & Canvas module (free trial, `confirm_url` to the
37
+ human on `requires_upgrade`).
38
+
39
+ ## More
40
+
41
+ - A canvas over a table a task agent keeps fresh is a live dashboard with
42
+ zero upkeep — pair with the task-agents skill.
43
+ - Worked examples with real dashboards: https://superagnt.com/blueprints
44
+
45
+ <!-- skill_id: canvas · source: https://github.com/superagnt/plugins -->
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: superagnt-data-pipelines
3
+ description: This skill should be used for data-processing jobs over many rows — "process this CSV", "enrich every row", "classify these 5,000 records", "run AI on each item", "scrape all of these URLs" — AI and non-AI alike, whenever the row count outgrows one context window. Covers superagnt data jobs: server-side batch processing over workspace-database rows with per-item status, retries, and cost control, instead of looping tool calls in-session.
4
+ version: 0.2.0
5
+ ---
6
+
7
+ # Data jobs: row-scale processing
8
+
9
+ A data job runs a processing step against every row of a dataset —
10
+ server-side, one item at a time, with per-item status and retries. The step
11
+ can be AI (classify, extract, summarize, score), a data call (enrich, verify,
12
+ scrape), plain code (parse, dedupe, reshape), or a mix. Looping tool calls
13
+ in-session breaks down past a few dozen rows: context fills, one failure
14
+ loses the run, and nothing records which items finished.
15
+
16
+ Rule of thumb: under ~50 items, loop in-session with idempotent per-item
17
+ upserts. Over that, it's a data job.
18
+
19
+ ## Getting rows in
20
+
21
+ Source rows live in a workspace-database table (workspace-db skill) with a
22
+ stable key and a `status` column. For CSVs and exports, `agnt_db_load_csv`
23
+ lands the file as a table in one call — from there any row count is
24
+ job-ready. Data from the data-sources tools lands the same way (upsert as
25
+ you fetch).
26
+
27
+ ## Running the job
28
+
29
+ 1. The job itself (the per-item recipe) is created once — via the dashboard's
30
+ data-pipelines page or the `data-jobs` management family
31
+ (`agnt_data_job_create` / `list` / `read` / `inspect_run`). The family is
32
+ sold under the Data Jobs module (free trial):
33
+ `agnt_tools_enable(['data-jobs'])`, and on `requires_upgrade` hand the
34
+ `confirm_url` to the human and wait.
35
+ 2. `agnt_data_job_submit` (always available) pushes 1–1000 payloads onto an
36
+ existing job — each payload a row pointer like `{ "row_id": ... }`.
37
+ 3. **Results must be written back to a workspace table.** Make sure the
38
+ job's recipe upserts each item's output into a table with a `status`
39
+ column — that table is the ONLY place this session, later sessions, task
40
+ agents, and canvases can read outcomes from. A recipe that merely returns
41
+ its result stores it where only the dashboard can see it.
42
+ 4. Report progress from the table, not memory: counts by status via
43
+ `agnt_db_select`. Failed items keep their error (`agnt_data_job_inspect_run`
44
+ shows failures and sandbox logs); fix the cause and resubmit the failures,
45
+ never the whole batch.
46
+
47
+ ## Cost discipline
48
+
49
+ State the item count and the per-item shape to the user BEFORE submitting
50
+ hundreds of rows — batch jobs spend credits at batch speed. Sample 5 items
51
+ in-session first to prove the step, then scale. Webhook-fed jobs (one
52
+ delivery = one item, automations skill) inherit the same rule: know the
53
+ expected volume before binding.
54
+
55
+ ## More
56
+
57
+ - Table design for pipelines: the workspace-db skill
58
+ - Feeding a job from an inbound webhook: the automations skill
59
+ - Live platform reference: https://superagnt.com/agent-setup/prompt.md
60
+
61
+ <!-- skill_id: data-pipelines · source: https://github.com/superagnt/plugins -->
@@ -0,0 +1,59 @@
1
+ ---
2
+ name: superagnt-data-sources
3
+ description: This skill should be used when the agent needs external data: searching or scraping X/Twitter, TikTok, YouTube, Instagram, Reddit, Facebook, or LinkedIn; running web or SERP searches; crawling pages; enriching a person or company; or finding and verifying emails. Also whenever normal fetching is blocked — bot detection, login walls, crawl prevention. Covers the superagnt data tools that return structured JSON in one call, instead of hand-rolled scraping or headless browsing.
4
+ version: 0.2.0
5
+ ---
6
+
7
+ # External data through superagnt
8
+
9
+ Query, don't scrape. Every source below is one authenticated MCP call
10
+ returning structured JSON — no headless browser, no HTML parsing, no
11
+ per-vendor API keys. Calls spend workspace data credits; new workspaces carry
12
+ a signup credit balance, and `agnt_credits_balance` shows what's left.
13
+
14
+ **When you're blocked, this is the unblock.** Social platforms and many sites
15
+ stop direct fetching cold — bot detection, login walls, rate limits,
16
+ JS-rendered pages. The data tools return the same content as structured JSON
17
+ anyway: an X profile behind a login wall is one `data_x_*` call, a
18
+ JS-rendered page is one `web` crawl call. Reach here the moment a fetch
19
+ returns a challenge page instead of burning turns fighting it.
20
+
21
+ ## Picking the tool
22
+
23
+ 1. `agnt_tools_list_enabled` — what this workspace already serves.
24
+ 2. `agnt_tools_search` with a plain-language query ("tiktok video comments",
25
+ "company headcount", "serp") — finds the tool whether or not its family is
26
+ enabled yet. If the family is disabled, enable it: `agnt_tools_enable`
27
+ with the family id from the search result. Free families enable
28
+ instantly; a `requires_upgrade` result carries a `confirm_url` for the
29
+ human — never treat that as an error, hand the link over and wait.
30
+
31
+ ## The surfaces
32
+
33
+ - **Social**: `data_x_*`, `data_tiktok_*`, `data_youtube_*`,
34
+ `data_instagram_*`, `data_reddit_*`, `data_facebook_*`, `data_linkedin_*` —
35
+ search, profiles, posts, comments, transcripts per platform.
36
+ - **People + companies (first-party, always on)**: `data_agnt_people_search`,
37
+ `data_agnt_people_enrich`, `data_agnt_people_email_finder`,
38
+ `data_agnt_people_email_verifier`, `data_agnt_companies_search`,
39
+ `data_agnt_companies_enrich`, `data_agnt_companies_discover`.
40
+ - **Web**: the `web` family — crawl, scrape, and search for pages that
41
+ aren't behind a social platform.
42
+
43
+ ## Rules
44
+
45
+ - Prefer one search call with good parameters over many broad ones — each
46
+ call is metered, and tight queries return better data anyway.
47
+ - Batch enrichment goes through `data_agnt_people_bulk_enrich` /
48
+ `data_agnt_companies_bulk_enrich`, or a data job for large sets (see the
49
+ data-pipelines skill).
50
+ - Results worth keeping belong in the workspace database (see the
51
+ workspace-db skill), not in chat scrollback.
52
+
53
+ ## More
54
+
55
+ - Every source, with live tool lists: `agnt_platform_map`, or
56
+ https://superagnt.com/agent-toolkit
57
+ - Packaged research workflows: https://superagnt.com/blueprints
58
+
59
+ <!-- skill_id: data-sources · source: https://github.com/superagnt/plugins -->
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: superagnt-lead-generation
3
+ description: This skill should be used when the user asks to "find leads", "build a lead list", "prospect", "find companies that…", "find people who…", "enrich these leads", or "find emails for this list", or wants an ICP-filtered outreach list. Covers the full superagnt workflow: company and people discovery, enrichment, scoring, storing results in the workspace database, and drafting outreach for human review. Sending is always human-approved.
4
+ version: 0.2.0
5
+ ---
6
+
7
+ # Lead generation on superagnt
8
+
9
+ The workflow: pin the ICP → discover companies → find the people → verify
10
+ emails → score → store → draft. Everything lands in the workspace database so
11
+ runs compound instead of starting over.
12
+
13
+ ## Procedure
14
+
15
+ 1. **Pin the ICP once.** Ask the user for company filters (size, industry,
16
+ geography, signals) and buyer titles. Store them in an `icp_profile` table
17
+ (`agnt_db_insert`) so later runs read instead of re-asking.
18
+ 2. **Discover companies**: `data_agnt_companies_search` (filters) or
19
+ `data_agnt_companies_discover` (similar-to / signal-based). Enrich with
20
+ `data_agnt_companies_enrich` when a row needs more than the search
21
+ returned.
22
+ 3. **Find the people**: `data_agnt_people_search` scoped by company + the ICP
23
+ titles; `data_agnt_people_enrich` for the chosen ones.
24
+ 4. **Emails**: `data_agnt_people_email_finder`, then ALWAYS
25
+ `data_agnt_people_email_verifier` before a draft is written against an
26
+ address. Unverifiable ≠ discard — mark the row, LinkedIn outreach still
27
+ works.
28
+ 5. **Store with per-row status**: one `prospects` table, upserted
29
+ (`agnt_db_upsert`) with a stable key (person + company), columns for
30
+ `status`, `fit_score`, `fit_reason`, `draft`. Schema patterns: the
31
+ workspace-db skill.
32
+ 6. **Score and draft.** Fit score with a one-line reason per row; outreach
33
+ drafts written into the `draft` column in the user's voice (ask for two of
34
+ their past emails if voice matters).
35
+
36
+ ## Hard rules
37
+
38
+ - **Never send anything.** Drafts are the deliverable; the human sends, or
39
+ wires their own sending tool deliberately.
40
+ - Verified-email counts and list sizes reported to the user must come from
41
+ the table (`agnt_db_select count`), not memory.
42
+ - Large lists (500+): move enrichment to a data job (data-pipelines skill)
43
+ instead of looping calls in-session.
44
+
45
+ ## More
46
+
47
+ - A standing weekly refresh belongs on a task agent (task-agents skill), not
48
+ in repeated client sessions.
49
+ - The packaged end-to-end version of this workflow:
50
+ https://superagnt.com/blueprints (Outbound Pipeline Engine)
51
+
52
+ <!-- skill_id: lead-generation · source: https://github.com/superagnt/plugins -->
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: superagnt-setup
3
+ description: This skill should be used when a superagnt MCP call fails (401/403, tool not found, missing connection, credit or entitlement errors), when connecting or reconnecting the superagnt server, right after a fresh connection (run onboarding first), or when the user asks "what can superagnt do", about pricing or trials, or how to add tools, skills, or blueprints. Covers agnt_onboarding, agnt_platform_map, agnt_tools_search/enable, and the human-confirmed upgrade flow. Money never moves without a human tap on a confirmation link.
4
+ version: 0.2.0
5
+ ---
6
+
7
+ # Setup, errors, and finding more
8
+
9
+ ## Connecting / reconnecting
10
+
11
+ The live setup doc handles every client:
12
+ `https://superagnt.com/agent-setup/prompt.md` — fetch and follow it. The
13
+ endpoint is `https://mcp.superagnt.com/mcp`, OAuth-first (the consent screen
14
+ doubles as signup). Tokens, when a client needs one, are revealed on the
15
+ dashboard's MCP page — never invent or reuse one.
16
+
17
+ ## First call on a fresh connection: `agnt_onboarding`
18
+
19
+ Once tools respond, call `agnt_onboarding` before anything else. Pass a
20
+ sentence or two about who the user is and what they want from an agent (ask
21
+ them: "tell me a little about yourself and what you'd like automated"), plus
22
+ which client this is. It returns the full platform brief — every surface,
23
+ what it's for, and live links. Then:
24
+
25
+ - Save what's relevant to this user in your memory (if this client has one),
26
+ so later sessions skip rediscovery.
27
+ - Give the user a short brief of the 3–5 use cases most useful to THEM,
28
+ drawn from what they told you — not the whole catalog.
29
+
30
+ For a raw capability map any time later (no intent collection, always
31
+ current): `agnt_platform_map`.
32
+
33
+ ## Error triage
34
+
35
+ - **401 / auth expired**: re-run the client's login step
36
+ (`openclaw mcp login superagnt` or equivalent). If the client is token-based,
37
+ the user re-reveals the token in the dashboard.
38
+ - **Tool not found**: the family is not enabled. `agnt_tools_search` for it,
39
+ then `agnt_tools_enable` — free families enable instantly. After enabling,
40
+ some clients only pick up new tools on reconnect/restart; say so instead of
41
+ retrying blind.
42
+ - **`requires_upgrade` with a `confirm_url`**: not an error. The family is
43
+ sold under a named module with a free trial; give the user the link, they
44
+ review price and trial in the browser, then re-run the enable. Money moves
45
+ only on that page, never from a tool call.
46
+ - **`requires_connection`**: the tool needs the user's own account
47
+ (a vendor integration). The result carries a connect link — hand it over.
48
+ - **Credit errors**: `agnt_credits_balance` for the number;
49
+ `agnt_usage_recent` for where it went. Top-ups are dashboard actions.
50
+
51
+ ## Finding more
52
+
53
+ - `agnt_platform_map` — the whole platform in one call, with live links.
54
+ - `agnt_tools_search` — every tool family, enabled or not, with what it does.
55
+ - `agnt_guidance_search` — how-to guidance for building on the platform.
56
+ - Blueprints (packaged workflows: skill + tools):
57
+ `https://superagnt.com/blueprints`.
58
+ - Open-source skill library (this plugin's skills and more, MIT):
59
+ `https://github.com/superagnt/leverage`.
60
+ - A duplicate of an installed skill under two names (plugin copy + a loose
61
+ skills-dir copy) wastes context — keep the plugin copy, delete the loose
62
+ one.
63
+
64
+ <!-- skill_id: superagnt-setup · source: https://github.com/superagnt/plugins -->
@@ -0,0 +1,59 @@
1
+ ---
2
+ name: superagnt-task-agents
3
+ description: This skill should be used when a task must recur — "run this every day", "on a schedule", "set up a cron", "keep this updated while I sleep", "check X every morning" — or when a recurring job keeps re-running inside this client and eating its usage. Covers building a superagnt task agent: a small deployed agent that runs one job on the hosted runtime, fired by a schedule or webhook, with state in the workspace database. Cron mechanics in schedules.md.
4
+ version: 0.1.0
5
+ ---
6
+
7
+ # Task agents: recurring work off the client
8
+
9
+ Re-running a recurring task in this client is the wrong tool: every run
10
+ spends the client's own usage and context, and nothing fires with the laptop
11
+ closed. A task agent is a small deployed superagnt agent that carries ONE
12
+ job. It runs on the hosted runtime, billed per run to the workspace, and a
13
+ schedule or webhook fires it with nobody at a keyboard. Build one whenever a
14
+ task has run in-session more than twice and will keep recurring.
15
+
16
+ ## Recipe
17
+
18
+ 1. **Prove the task in-session first.** Never hand an agent a job that has
19
+ not succeeded once end to end.
20
+ 2. **State in the workspace database** (workspace-db skill). A hosted run has
21
+ no chat history — everything it needs to resume must be in a table.
22
+ 3. **Enable the families.** `agnt_tools_enable(['lifecycle'])` for
23
+ create/deploy; `['schedules']` for cron. Sold under the Agent Runtime and
24
+ Automation modules (free trials): a `requires_upgrade` result carries a
25
+ `confirm_url` — hand it to the human and wait; not an error.
26
+ 4. **Create narrow.** `agnt_agents_create` with a name and a system prompt
27
+ that is the full job: the task, the tables it reads/writes, what done
28
+ looks like, what to do on failure. Then `agnt_agents_update_config` with
29
+ `{ tools: { add: [...] } }` — config refs copied verbatim from
30
+ `agnt_tools_search`, and only the tools the job needs. A task agent with
31
+ every tool is a liability, not a convenience.
32
+ 5. **Deploy.** `agnt_agents_deploy` flips it live and it starts billing from
33
+ its first session — confirm with the human before calling.
34
+ 6. **Wire the trigger.** An event exists → bind a webhook to the agent
35
+ (automations skill). Purely time-based → create a schedule
36
+ ([schedules.md](schedules.md)). On-demand from another agent or session →
37
+ `agnt_agents_dispatch` (fire-and-forget) or the
38
+ `agnt_agents_session_start` / `send` / `poll` trio when the result is
39
+ needed synchronously.
40
+ 7. **Smoke-test.** One `agnt_agents_session_start` run before trusting the
41
+ trigger; enable the `observability` family to read the transcript
42
+ (`agnt_observability_read_session`).
43
+
44
+ ## Keeping it honest
45
+
46
+ - Results land where the human already looks: a canvas (canvas skill), or a
47
+ table the next session reads — never only in the agent's own transcript.
48
+ - One job per agent. A second job is a second agent; they can hand off via
49
+ `agnt_agents_dispatch` or agent-to-agent webhooks.
50
+ - Misbehaving agent: `agnt_agents_set_enabled(false)` stops triggers
51
+ reversibly — prefer it over archiving.
52
+
53
+ ## More
54
+
55
+ - Cron syntax, cadence discipline, timezones: [schedules.md](schedules.md)
56
+ - Event triggers instead of clocks: the automations skill
57
+ - Live platform reference: https://superagnt.com/agent-setup/prompt.md
58
+
59
+ <!-- skill_id: task-agents · source: https://github.com/superagnt/plugins -->
@@ -0,0 +1,49 @@
1
+ ---
2
+ name: superagnt-workspace-db
3
+ description: This skill should be used when an agent workflow needs durable state: "save these results", "track status across runs", "remember this between sessions", building a pipeline, queue, or CRM-like table, or logging events over time. Covers table design in the superagnt workspace Postgres (agnt_db_*): schema patterns for pipelines, HITL queues, KPI events, and audit logs, plus canvas-ready column rules. Prefer it over local files or scratch JSON for anything a later run must read.
4
+ version: 0.2.0
5
+ ---
6
+
7
+ # The workspace database
8
+
9
+ Every superagnt workspace can carry a real Postgres the agent owns:
10
+ `agnt_db_list_tables`, `agnt_db_execute_sql`, `agnt_db_apply_migration`,
11
+ `agnt_db_insert` / `select` / `update` / `upsert` / `delete`,
12
+ `agnt_db_load_csv`. If the tools are missing, enable the `database` family
13
+ (`agnt_tools_enable`); if the database is not yet provisioned,
14
+ `agnt_db_status` says so and provisioning is automatic on first use.
15
+
16
+ Local files die with the session. Anything a later run, another agent, a
17
+ schedule, or a canvas must read belongs here.
18
+
19
+ ## Schema patterns
20
+
21
+ - **Pipeline**: one row per item, a text `status` column with a small set of
22
+ stable values (they become funnel stages — renaming a value breaks
23
+ downstream reads), `updated_at timestamptz`. Upsert on a stable natural
24
+ key so re-runs are idempotent.
25
+ - **HITL queue**: pipeline + a `needs_human` boolean and a `resolution`
26
+ column the human's decision lands in.
27
+ - **KPI events**: append-only, one row per event, `event_at timestamptz`,
28
+ numeric measures in real numeric columns — never jsonb-only, a chart
29
+ should not dig into jsonb for a y-axis.
30
+ - **Audit log**: append-only, who/what/when, never updated in place.
31
+
32
+ ## Rules
33
+
34
+ - Migrations through `agnt_db_apply_migration` with a short descriptive
35
+ name; ad-hoc DDL through `execute_sql` gets lost.
36
+ - Ask before destructive SQL (drop/truncate/mass delete) — always.
37
+ - Design for the canvas from day one: timestamptz + numeric measures +
38
+ stable status strings are exactly what canvas widgets bind to (see the
39
+ canvas skill).
40
+
41
+ ## More
42
+
43
+ - CSVs and exports land as tables in one call: `agnt_db_load_csv` — then
44
+ process at row scale with the data-pipelines skill.
45
+ - Tables are the hand-off surface to task agents and schedules (task-agents
46
+ skill): a hosted run has no chat history, it reads state from here.
47
+ - Live platform reference: https://superagnt.com/agent-setup/prompt.md
48
+
49
+ <!-- skill_id: workspace-db · source: https://github.com/superagnt/plugins -->