Skip to content
Back to search

codex-first-customer-finder-skill

A Codex skill that finds evidence-backed potential first customers from recent public signals.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kappaemme-git-codex-first-customer-finder-skill/badge.svg)](/listings/kappaemme-git-codex-first-customer-finder-skill)

HTML

<a href="/listings/kappaemme-git-codex-first-customer-finder-skill"><img src="/api/listings/kappaemme-git-codex-first-customer-finder-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx --yes codex-first-customer-finder-skill@latest

Installs into `$CODEX_HOME/skills/first-customer-finder` or `~/.codex/skills/first-customer-finder`. Restart Codex after an update so it loads the new instructions. Re-running the command installs the version currently published on npm; source changes are not available there until a release is published.

Custom directory:

npx --yes codex-first-customer-finder-skill@latest --skills-dir /path/to/skills

**Requirements:** Node.js for the installer, Python 3.9+ for the local helpers, and a Codex environment with web search or browser access for live research. No third-party Python dependencies, data-broker subscription, or skill-specific API key is required. Codex usage and external platform access remain subject to your own account and tools.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 196 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # First Customer Finder
  2. **Find people with a public reason to care about your product — and know your next manual step.**
  3. Give Codex your product URL, repository, or a short description. This skill researches accessible public demand signals, qualifies potential customers, verifies suitable public contact routes, and creates a report you can open directly in Codex.
  4. Tell it which prospects fit. The next search uses your explicit feedback and local history.
  5. > These are potential customers based on public evidence, not confirmed buyers. The skill never sends outreach automatically.
  6. ## What's new in v2
  7. - **Concrete outreach:** target role, observed/inferred label, verified public route or an honest missing-route warning, realistic next step, and a specific CTA.
  8. - **Feedback-driven searches:** keep, maybe, or reject candidates; refine the target profile with explicit preferences.
  9. - **Product-local history:** stable prospect IDs, duplicate exclusion, previously seen labels, and manually recorded contact outcomes.
  10. - **Native Markdown + CSV:** evidence and next steps in Codex, with a spreadsheet-friendly export. Standalone HTML is still available.
  11. - **Stronger checks:** weighted scores are computed, missing dates/routes reduce their relevant dimensions, and malformed or incomplete qualified records are rejected.
  12. - **Recoverable upgrades:** the installer preserves your previous skill folder outside the active skills directory.
  13. “Learning” means saved search preferences, not model training. Public route verification means Codex inspected the page, not that the recipient consented to promotion.
  14. ## Install or update
  15. ```bash
  16. npx --yes codex-first-customer-finder-skill@latest
  17. ```
  18. Installs into `$CODEX_HOME/skills/first-customer-finder` or `~/.codex/skills/first-customer-finder`. Restart Codex after an update so it loads the new instructions. Re-running the command installs the version currently published on npm; source changes are not available there until a release is published.
  19. Custom directory:
  20. ```bash
  21. npx --yes codex-first-customer-finder-skill@latest --skills-dir /path/to/skills
  22. ```
  23. **Requirements:** Node.js for the installer, Python 3.9+ for the local helpers, and a Codex environment with web search or browser access for live research. No third-party Python dependencies, data-broker subscription, or skill-specific API key is required. Codex usage and external platform access remain subject to your own account and tools.
  24. ## Try it
  25. Start with a product:
  26. ```text
  27. Use $first-customer-finder to find 5 potential customers for [PRODUCT URL].
  28. ```
  29. Then refine the results:
  30. ```text
  31. P1 and P3 fit. Focus on owner-led small businesses, avoid enterprise teams, and find 5 more.
  32. ```
  33. Record a real outcome:
  34. ```text
  35. I contacted P1. Remember that and exclude it from the next search.
  36. ```
  37. Ranks such as P1 belong to the report you are discussing. The saved history uses stable IDs, so ranks cannot silently point to a different prospect in another report.
  38. Other useful requests:
  39. ```text
  40. Use $first-customer-finder in design-partners mode for [PRODUCT URL].
  41. ```
  42. ```text
  43. Use $first-customer-finder to find developers publicly asking for an alternative to [TOOL], for my product [URL].
  44. ```
  45. ```text
  46. Refresh the existing shortlist, recheck the sources, and include the HTML report.
  47. ```
  48. ## How a search works
  49. 1. **Understand the product.** Identify the outcome, buyer, use case, geography, alternatives, and disqualifiers. Ask a concise question only when a material ambiguity remains.
  50. 2. **Read the current project history.** Apply explicit preferences and avoid excluded candidates. A different product gets a separate history.
  51. 3. **Research public signals.** Discover and open original sources: requests for tools, manual workarounds, unresolved pain, switching intent, and relevant business events.
  52. 4. **Qualify and challenge.** Attribute the evidence correctly, check for resolved problems or poor fit, calculate the score, and consolidate duplicate entities.
  53. 5. **Make the next step concrete.** Identify the relevant function, verify a suitable official/public route when possible, and draft a short message with an actionable CTA.
  54. 6. **Deliver and refine.** Save a Markdown report, CSV, and local history. On request, use your feedback for the next search or refresh.
  55. Search may use accessible public X posts, GitHub issues, forums, product reviews, company pages, and search engines. It does not promise access to every platform, bypass login walls, or qualify candidates from snippets alone. Blocked sources are reported as coverage gaps.
  56. ## What you receive
  57. | Output | Purpose |
  58. | --- | --- |
  59. | `report.md` | Native Codex report with ranked candidates, source links/dates, roles, contact routes, drafts, and cautions |
  60. | `prospects.csv` | Spreadsheet-safe snapshot of the included shortlist and its next steps |
  61. | `report.html` (optional) | Responsive standalone visual report |
  62. | `state.json` | Product-scoped local history, explicit preferences, feedback, and reported outcomes |
  63. | `analysis.json` | The run's structured evidence, retained in the workspace unless using an ephemeral workflow |
  64. Example workspace layout:
  65. ```text
  66. outputs/first-customer-finder/my-product/
  67. ├── state.json
  68. ├── run-01/
  69. │ ├── analysis.json
  70. │ ├── report.md
  71. │ └── prospects.csv
  72. └── run-02/
  73. ├── analysis.json
  74. ├── report.md
  75. └── prospects.csv
  76. ```
  77. History is kept in the chosen workspace, not uploaded, synced, or stored inside the installed skill. Ask for a run without saved history to omit it. Existing report files remain independent snapshots. Keep the research folder out of version control; remove that exact product folder yourself when you no longer want the stored data.
  78. CSV edits are not automatically imported. Tell Codex which outcomes to record.
  79. ## Feedback and repeat searches
  80. - **Keep / maybe / reject:** save your assessment and reason for a specific prospect.
  81. - **Prefer / avoid:** save explicit general criteria. Rejecting one company does not automatically reject its entire industry.
  82. - **Find more:** exclude all previously seen entities, as well as rejected or already-contacted records.
  83. - **Refresh:** revisit eligible existing prospects and inspect their current evidence. Preserve feedback and contact status.
  84. - **Contact outcomes:** `new`, `contacted`, `replied`, `not_interested`, or `customer`; entered only from your report, never inferred from a generated draft.
  85. No background monitoring is started. No follow-up is sent. An empty shortlist is a valid result when there are no additional qualified matches.
  86. ## Qualification
  87. | Dimension | Weight |
  88. | --- | ---: |
  89. | Pain strength | 25% |
  90. | Product fit | 25% |
  91. | Timing | 20% |
  92. | Public reachability | 15% |
  93. | Evidence quality | 15% |
  94. Each dimension runs from 0 to 5. The helper calculates the weighted total. Scores are research priorities, **not conversion probabilities**. Numerical scores cannot override missing, contradictory, or misattributed evidence.
  95. Every primary prospect needs an inspected original source. Unknown signal dates cap timing at 2/5; no suitable verified contact route caps reachability at 1/5. The report distinguishes publication date from the date the source was checked.
  96. ## Modes
  97. - `quick`: up to 5 prospects
  98. - `standard`: up to 10, default
  99. - `deep`: up to 20 plus repeated-pattern analysis
  100. - `design-partners`: feedback-oriented early adopters
  101. - `b2b`: companies, business triggers, and buyer functions
  102. - `community`: explicit requests and public discussion signals
  103. Requested counts are limits, not quotas. The skill should return fewer candidates when evidence is weak.
  104. ## Privacy and limits
  105. - Public, intentionally shared professional/business information only.
  106. - No private email discovery, phone enrichment, data brokers, sensitive-trait targeting, or private-group access.
  107. - No messages, form submissions, follows, comments, or CRM changes from a prospect-search request.
  108. - A found route is not permission to advertise; platform/community rules still matter.
  109. - A local preference profile is not autonomous learning or proof of demand.
  110. - The scripts validate structure and consistency; they cannot prove a public statement true or replace judgment about outreach suitability.
  111. ## Run the fictional demo
  112. This offline fixture tests the report and history workflow. **Every prospect, statement, and route is fictional.** It is not a live research benchmark.
  113. ```bash
  114. git clone https://github.com/Kappaemme-git/codex-first-customer-finder-skill.git
  115. cd codex-first-customer-finder-skill
  116. python3 first-customer-finder/scripts/generate_report.py examples/demo.json outputs/demo/run-01/report.md --csv outputs/demo/run-01/prospects.csv --html outputs/demo/run-01/report.html --state outputs/demo/state.json
  117. ```
  118. Try a repeat run: it should not invent new prospects or repackage old ones as new.
  119. ```bash
  120. python3 first-customer-finder/scripts/generate_report.py examples/demo.json outputs/demo/run-02/report.md --state outputs/demo/state.json --new-only
  121. ```
  122. Demo history cannot be mixed with real research. The fixture is not shipped in the npm install.
  123. ## Local development and tests
  124. Install a source checkout for testing before publishing:
  125. ```bash
  126. node scripts/install.js
  127. npm test
  128. npm pack --dry-run
  129. ```
  130. Tests cover score calculation, stable identities, product isolation, feedback, outcome retention, repeated-search exclusions, missing routes, unsafe links, CSV formula escaping, legacy HTML, demo labels, history locking, output protection, and recoverable installation.
  131. The package version is `0.2.0`; “v2” describes the second workflow generation.
  132. ## Community input
  133. The outreach improvements address [issue #2](https://github.com/Kappaemme-git/codex-first-customer-finder-skill/issues/2) and incorporate the direction proposed in [PR #3](https://github.com/Kappaemme-git/codex-first-customer-finder-skill/pull/3) and [PR #5](https://github.com/Kappaemme-git/codex-first-customer-finder-skill/pull/5). Those proposals motivated concrete contact routes and manual CTAs; this update also adds local feedback/history and native exports.
  134. ## License
  135. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.