OpenOutreach Lead Finder
Self-hosted B2B lead-gen CLI: describe your product, it finds the people who fit, writes down why, and emails them from your mailbox.
The SKILL.md is disciplined on permissions and spend: bare find cannot spend, send/run require an explicit user request, the legal notice is never accepted on the user's behalf, credentials must be asked not guessed, and the data flow (stdout results, stderr logs) is transparently disclosed. Deductions: reliance on two external services (BetterContact, LLM) with mailbox app-password storage, whose protection and rollback are not documented at skill level; an affiliate link in the README discloses commercial incentive but introduces steering.
Instruction self-consistency is high: a unified error-type table, exit-code contract, stdout/stderr separation, precise N semantics and resumable --agent-qualify logic; failures name missing variables instead of shifting debugging cost. Deductions: the committed tests cover only the CLI entry, registry and wizard export — not the find key paths (discovery, qualification, export, provider failure) — so static review cannot confirm the documented behavior exists.
Trigger precision and scenario fit are excellent ('get me leads' maps to find, 'email them' to send/run), with clear non-fit boundaries (--open, headless, no TTY) and N semantics. Deductions: core function depends entirely on BetterContact and overseas LLM APIs whose reachability from mainland China is doubtful; no Chinese-language support is documented, weakening environment fit.
Docs are well layered: progressive disclosure in SKILL.md, parameter tables, FAQ-style cautions (dedupe, never stitch stdout). GPLv3 is explicit, the commit-count versioning scheme is explained, CI/publish flows are transparent, and maintenance signals are visible. Deductions: installability is pinned exactly to two child repos (openoutfind 0.1.12, openoutsend 0.1.36); the three-repo maintenance coupling is not fully transparent to a skill user; no changelog file.
The claimed deliverable — importer-friendly CSV/JSONL with a reason column, directly usable in Instantly/Smartlead, find 0 re-export, incremental semantics — is well designed and plausibly beats manual list-building. Deductions: nothing was executed, so direct usability of the output is unverified; result quality depends on external provider data and LLM judgment, with no third-party usage evidence.
Auditable primary material exists: README and SKILL.md corroborate each other, and tests plus CI workflows (tests.yml, deploy.yml) are committed covering wizard/registry/CLI. Deductions: tests do not cover the skill's key find/send paths, so the documented behavior cannot be independently reproduced; most claims are author statements.
- Core function depends entirely on BetterContact and overseas LLM APIs; verify mainland-China reachability and the 40-credit free tier yourself before adopting.
- send/run dispatch real mail from the user's own identity to strangers; confirm every time — the skill's rules are documentation, not technical enforcement.
- The mailbox app password and several API keys are stored in local SQLite (~/.openoutreach); secure the host and use app-level passwords, not primary credentials.
- The BetterContact signup link is an affiliate link; you can register independently to avoid the referral.
- Before first use, run find 0 and a small find in a sandbox to confirm behavior matches the documentation.
What does this skill do, and when should you use it?
OpenOutreach is a GPLv3 open-source, self-hosted command-line tool for B2B lead generation and cold outreach. It bundles discovery, LLM qualification, email resolution and sending behind one command: you supply a product description, a target market, and a few API keys. It pulls candidates from a licensed data source (BetterContact), judges each against the ICP it learned from your description, and exports CSV rows that include a written reason for every pick. Discovery and qualification are free; only verified email lookups cost credits. The repo ships a Claude Code plugin and an Agent Skill (skills/find-leads/SKILL.md) so an agent can drive it safely — it never spends or sends mail unasked.
Core verbs: openoutreach status reports configuration, counts and blocks (never spends); init runs one-time onboarding (database, LLM key, BetterContact key, mailbox credentials, legal notice); find N finds N more qualified leads for free and prints every lead as CSV on stdout; find N --emails or find N emails additionally buys verified addresses (capped in credits); send/run actually mail from the user's mailbox under send guards (sending window, daily cap, pacing). Output columns match Instantly/Smartlead importers with no column mapping; -- emits JSON Lines (including profile_text). It also supports --agent-qualify/--agent-draft, letting the calling agent write the fit verdict or the opener itself and drop the second LLM key. Failures exit non-zero with a stable error: <type> (e.g. goal_unreached, qualify_pending); stdout is always result-only.
- A solo founder or small team selling their own SaaS who wants Claude Code to pull an ICP-matched prospect list and feed it straight into Instantly or Smartlead.
- Teams that already send with Lemlist, HubSpot or a spreadsheet and only need an import-ready CSV that says why each person was chosen.
- Compliance- and platform-risk-sensitive operators: browserless, no social accounts, no scraping, fully self-hosted and auditable pipeline.
- Budget-conscious users: run the free `find N` first to inspect lead quality and reasons, then decide whether to pay for verified addresses.
- Engineers running automated pipelines: use the `--` + stdout/stderr contract to pipe `outfind find 50 -- | outsend` into their own sender.
- Operators who fear an agent going rogue: the skill hard-codes no-spend-unless-asked, no-send-unless-asked, and the legal notice must be accepted by the user personally.
What are this skill's strengths and limitations?
- Self-hosted and GPLv3: the ICP, the verdicts and the whole pipeline live on your machine, readable and auditable.
- Every lead carries an LLM-written prose reason — you can read it, disagree with it, and correct verdicts by fixing the description.
- Zero platform-ToS surface: browserless, no social-network account, no scraping — no account to get banned.
- Clear cost model: discovery and qualification are free; the paid lookup is rationed, and a bare `find N` cannot spend by construction.
- CSV columns are shaped for Instantly/Smartlead importers — the file imports without column mapping.
- Careful guardrails: the agent never sends or buys addresses without explicit consent, with stable exit codes and error types.
- Address resolution depends on BetterContact, the one paid third party, surfaced via an affiliate link in the README; replacing it means finding another data source.
- The Gaussian-Process learning loop is explicitly labeled an active experiment in the README, with no claim it beats random picking.
- Cold outreach carries legal and compliance duties (data-controller obligations, sender duties) borne entirely by the user — the Legal Notice disclaims liability.
- Runs can be slow (one LLM call per lead, paid lookups polled) and need generous timeouts rather than short retries.
- Dedup relies on the receiving sequencer's import dedupe — opt-in on Smartlead, undocumented on Instantly — so re-exports can cause double contact.
- Only Google Workspace is documented as working out of the box; other providers require finding their SMTP/IMAP host and port yourself.
How do you install this skill?
Simplest: uv tool install openoutreach, then run openoutreach to onboard. Or pip install openoutreach. For development: git clone https://github.com/eracle/OpenOutreach.git && cd OpenOutreach && make setup. You need: an LLM API key (OpenAI, Anthropic, or OpenAI-compatible), a BetterContact API key (free account: 40 credits, no card), product description and target market as text files, and a sending mailbox address plus an app password. For server deploys, a Docker image is published to GitHub Container Registry (see docs/docker.md).
How do you use this skill?
In Claude Code: /plugin marketplace add eracle/OpenOutreach then /plugin install openoutreach@openoutreach; or copy skills/find-leads/ into ~/.claude/skills/. Outside Claude Code, point any agent (Codex, Cursor, etc.) at the same SKILL.md and it can call the same commands. Typical prompt: "find me 10 leads matching our ICP" → agent runs openoutreach find 10 (free); emails is added only when the user asked for addresses; send/run only when the user asked for mail to go out. On first use run openoutreach init; pass the long prose fields as files via init --product-docs product.md --target target.md. Check state with openoutreach status --.
How does this skill compare with similar options?
The README explicitly contrasts two paid product categories: cold-email sequencers (like Instantly and Smartlead — you bring the list) and lead databases (rows without reasons). OpenOutreach's stated difference: the input is a sentence about your product, and the output is a per-person verdict in plain language. It also asserts every comparable tool that qualifies leads for you is paid SaaS, while this one is free and self-hosted.