Related Pages

Related topics: Analysis Skills Catalog, Discovery Firehoses and Real-time Channels, Price Alert System, Architecture, and Operations

Overview, Setup, and Installation

What this project is

claude-investment-skills is a collection of Claude Code skills designed for retail and semi-professional investors who want algorithmic, source-backed trading signals without paying for Bloomberg or a hedge-fund terminal. Each "skill" is a self-contained bundle of natural-language triggers, Python scripts, configuration files, and GitHub Actions workflows that together implement a specific market-monitoring use case.

The flagship skill covered in the documentation is the Strategic Partner Firehose, a 30-minute-cadence SEC EDGAR monitor that scans 8-K and SC 13D filings for evidence of Tier-1 strategic investors (NVIDIA, Microsoft, OpenAI, SK Telecom, etc.) taking positions in small/mid-cap US-listed companies. The README frames the use case around the CoreWeave (CRWV) IPO, where a 2025-03-31 8-K disclosing an OpenAI commercial agreement preceded a +367% rally over the following quarter. Source: strategic-partner-firehose/README.md:11-25

Companion skills mentioned in the same document form a complete investing toolkit: insider-firehose (Form 4 buys), analyze-stock, option-wall-analysis, macro-warning, and tax-optimize. A composite signal detector (scripts/composite.py) cross-validates alerts from the two firehoses, and a price-alert skill integrates a Cloudflare Worker webhook for Telegram delivery. Source: strategic-partner-firehose/README.md:154-162

High-level architecture

The system is fully self-hosted on GitHub. No central service, no SaaS dependency, no telemetry. The data flow has four stages:

1. Cron trigger — a GitHub Actions workflow fires the entry script (e.g. scripts/partner_firehose.py) on a 30-minute schedule during US market hours (weekdays 9 AM – 7:30 PM ET).
2. EDGAR poll — the script pulls recent 8-K and SC 13D filings from sec.gov and runs regex-based extractors (scripts/parsers.py) and filters (scripts/filters.py) for market-cap, US-listing, and dollar-amount thresholds.
3. Scoring — a 0-10 Partner Score (scripts/analysis.py) weights filings by investor tier; a parallel theme classifier (scripts/classifier.py, v2.4) catches anonymous-hyperscaler deals like the POWL $400M data-center order.
4. Alert delivery — qualifying alerts are pushed to a Telegram chat via bot API, deduplicated against strategic_state.json and recent_alerts.json ledgers.

flowchart LR
    A[GitHub Actions<br/>cron 30 min] --> B[partner_firehose.py]
    B --> C[SEC EDGAR<br/>8-K + SC 13D]
    C --> D[parsers.py<br/>+ filters.py]
    D --> E{Investor registry<br/>OR theme score >= 6}
    E -- yes --> F[Partner Score 0-10]
    E -- no --> G[Skip]
    F --> H[Telegram<br/>bot API]
    H --> I[recent_alerts.json]
    I --> J[composite.py]
    K[insider-firehose<br/>alert] --> J
    J --> H

Repository layout

The project follows a per-skill subdirectory convention. Each skill ships with the same five files: SKILL.md (natural-language trigger for Claude Code), SETUP.md (5-minute installation), README.md (long-form with examples), strategic_config.json (on/off toggle), and a scripts/ directory containing the entry point plus helper modules. The firehose skill additionally carries a tests/ directory with 32 unit tests executed in ~22 ms with no network calls, plus four text fixtures including peng_sgh_sk_telecom_8k.txt (score 9/10), nvidia_partnership_8k.txt, sovereign_cluster_8k.txt (score 10/10), and noise_5_02_officer_change.txt (correctly filtered). Source: strategic-partner-firehose/README.md:21-30

For the price-alert skill, the webhook handler is a Cloudflare Worker written in TypeScript. The package.json declares wrangler (^4.0.0) as a dev dependency, with dev, deploy, and tail scripts for local development and production rollout. Source: price-alert/webhook/package.json:1-15

Installation steps

The README delegates primary installation guidance to each skill's SETUP.md, but the canonical 5-minute flow for the firehose family is:

No local Python install is required for end users — the workflow installs dependencies in a fresh ubuntu-latest runner. For developers who want to run the script locally, the same scripts/partner_firehose.py is executable as a standalone CLI and supports the same environment variables used by the cron.

Configuration and state

The firehose exposes a single on/off toggle in strategic_config.json at the skill root; flipping enabled to false suppresses Telegram delivery without disabling the workflow (the Actions cron keeps running and updating state). Two persistent JSON ledgers track system memory:

• strategic_state.json — a deduplication ledger of SEC accession numbers already alerted, so a filing is never re-sent even if it appears in multiple poll windows.
• recent_alerts.json — a 90-day rolling log consumed by scripts/composite.py to detect the same ticker appearing in both the partner firehose and the insider firehose within 30 days, which triggers a MEGA SIGNAL alert rate-limited to one send per ticker per 24 hours. Source: strategic-partner-firehose/README.md:170-176

A third ledger, composite_state.json, handles the 24-hour dedup window for composite alerts. None of the three ledgers contain personally identifiable information; they are pure ticker-level caches intended to be checked into the fork.

What is and is not covered

The v2.4 release explicitly excludes S-1 IPO prospectuses (which would have caught CoreWeave pre-IPO), foreign-only listings (HKEX, LSE, JPX), SPACs and crypto IPOs, and F-1/20-F filings from foreign private issuers. Form 8-K Item 5.02 (officer/director changes) is parsed but filtered as noise — verified by the noise_5_02_officer_change.txt fixture. Source: strategic-partner-firehose/README.md:108-114

See Also

• Strategic Partner Firehose — Detection Logic and Scoring
• Composite Signals — Cross-Firehose Mega-Signal Detection
• Price Alert — Cloudflare Worker Webhook Setup

Related Pages

Related topics: Overview, Setup, and Installation, Discovery Firehoses and Real-time Channels, Price Alert System, Architecture, and Operations

Analysis Skills Catalog

Overview

The Analysis Skills Catalog is the on-demand, decision-support layer of the claude-investment-skills repository. Whereas the firehose skills (e.g., strategic-partner-firehose, insider-firehose) are cron-driven scanners that push raw signals to Telegram, the analysis skills are invoked by the user (or by a firehose follow-up workflow) to translate a signal into an actionable decision.

In the documented triage flow for a freshly-fired firehose alert, the user is explicitly told to "Run /analyze STOCK in Telegram → triggers analyze-stock skill" and then "Run /option-wall STOCK → see option positioning" before sizing the position. Source: strategic-partner-firehose/README.md

The catalog is therefore best understood as a portfolio of single-purpose, triggerable skills that compose with the firehoses to form a full detect → validate → size → execute pipeline.

Related Pages

Related topics: Overview, Setup, and Installation, Analysis Skills Catalog, Price Alert System, Architecture, and Operations

Discovery Firehoses and Real-time Channels

1. Purpose and Scope

The "Discovery Firehoses and Real-time Channels" subsystem is the early-signal layer of the claude-investment-skills repository. It continuously polls U.S. SEC EDGAR for new filings and pushes actionable alerts to a Telegram bot, with the goal of surfacing strategic-partnership and insider-buying events before they are absorbed by retail-facing media (Substack, Twitter, financial newsletters). The strategic-partner firehose markets itself with the phrase "Find the next CoreWeave, the next PENG, the next POWL — by reading the same SEC filings hedge funds read, automatically, every 30 minutes" (strategic-partner-firehose/README.md:1-2).

The subsystem is implemented as two cooperating GitHub-Actions cron jobs (the "firehoses") plus a shared composite detector. Each firehose ingests a different SEC form type, normalizes it into a common alert record, and forwards the result through a Cloudflare Worker webhook to a Telegram chat. The firehoses intentionally do not run LLMs against filings — the design favors deterministic regex extraction plus rule-based scoring, validated by 36 unit tests (strategic-partner-firehose/README.md:165-170).

2. Two Parallel Detection Paths (v2.4 Dual-Path Architecture)

The strategic-partner firehose reads 8-K and SC 13D filings and applies two independent detection paths so it catches both named-investor deals (PENG/CRWV) and anonymous-hyperscaler deals (POWL) (strategic-partner-firehose/README.md:31-36).

When both paths fire on the same accession, a bonus theme tag is attached to the alert (strategic-partner-firehose/README.md:38-46).

flowchart LR
  A[SEC EDGAR poll<br/>every 30 min] --> B[parsers.py<br/>extract 8-K/13D]
  B --> C{Path A<br/>investor_registry match?}
  B --> D{Path B<br/>classifier.py score >= 6?}
  C -- yes --> E[🤝 PARTNER alert]
  D -- yes --> F[🏭 AI SIGNAL alert]
  E --> G[filters.py<br/>mcap + US-listed + amount]
  F --> G
  G --> H[composite.py<br/>cross-check insider-firehose]
  H -- same ticker, 30d --> I[🚨🚨🚨 MEGA SIGNAL]
  H --> J[Telegram bot<br/>via webhook]
  I --> J

The classifier collapses multi-line whitespace before regex matching, which makes the detector robust to HTML-stripped filings where phrases like "largest order in company history" are broken across lines (strategic-partner-firehose/README.md:188-190).

3. Filing Coverage and Investor Registry

The firehose ingests a deliberately narrow slice of EDGAR to keep the false-positive rate near zero (strategic-partner-firehose/README.md:53-60):

SC 13G filings (passive index-fund ownership) are explicitly downweighted in the Partner Score by −1 to avoid mistaking Vanguard/BlackRock holdings for strategic conviction (strategic-partner-firehose/README.md:99-107).

investor_registry.py stores the canonical entity list grouped into four tiers: Tier-1 (NVIDIA, Microsoft, Alphabet, Amazon, Meta, Apple, Oracle, SK Telecom, SK Hynix, Samsung, LG, TSMC, SoftBank, Sony, ASML, SAP), Tier-2 (Intel Capital, Qualcomm Ventures, Salesforce Ventures, Dell, HPE, Cisco, IBM, Adobe, ServiceNow, Workday, AMD), Sovereign (MGX, Mubadala, ADIA, Saudi PIF, Temasek, GIC, CPPIB), and Smart-money VC (a16z, Lux, Sequoia, Founders Fund, Khosla, Coatue, Tiger Global). Each entity carries 2–5 SEC-filing aliases (e.g. "NVIDIA Corporation" / "Nvidia Corp" / "NVentures") and is matched by full regex (strategic-partner-firehose/README.md:64-69).

4. Composite MEGA SIGNAL and Cross-Firehose Coupling

The strategic-partner firehose and the insider-firehose (Form 4 monitor) cross-validate each other. When both firehoses log an alert for the same ticker within 30 days, scripts/composite.py emits a "MEGA SIGNAL" that carries both messages in a single Telegram push (strategic-partner-firehose/README.md:120-140).

Mechanics (strategic-partner-firehose/README.md:134-140):

1. Each firehose appends every alert to its own recent_alerts.json (90-day retention).
2. On every new alert, the firehose queries the other firehose's log for the same ticker.
3. If matched within 30 days, a composite alert is emitted.
4. Composite alerts are rate-limited to 1 send per ticker per 24h via composite_state.json to prevent spam.

The composite detector is invoked by both firehoses and lives in the shared scripts/composite.py module; it is the explicit sibling link described in the README's "Companion skills" section (strategic-partner-firehose/README.md:212-217).

5. Configuration, Scheduling, and Delivery

The cron cadence is every 30 minutes, weekdays 9 AM – 7:30 PM ET in strategic-partner-firehose/.github/workflows/, deliberately aligned with the insider-firehose cron so composite alerts can fire on the same tick (strategic-partner-firehose/README.md:174-178, strategic-partner-firehose/README.md:191-195).

Toggles and runtime controls live in strategic_config.json (on/off for the workflow). Required secrets in the GitHub repository are TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID, which are also reused by the price-alert bot. The webhook that receives firehose payloads and forwards them to Telegram is a Cloudflare Worker, declared in price-alert/webhook/package.json and run with wrangler dev / wrangler deploy (price-alert/webhook/package.json:1-15).

6. Known Failure Modes and Out-of-Scope Filings

The README is explicit about limitations (strategic-partner-firehose/README.md:228-240):

• Conservative amount extraction — regexes can miss deals where the dollar value is buried in tables or only described generically as "the Investment".
• False positives — a filing that mentions NVIDIA in passing and also mentions $200M (e.g. a buyback) can be misclassified; the filter pipeline minimizes but does not eliminate these.
• No semantic LLM — ambiguous cases are not second-passed; a future release may add an LLM layer.
• Out of scope — S-1 IPO prospectuses (which would have caught CRWV pre-IPO; planned for v2.4+), foreign-only filings (HKEX/LSE/JPX), crypto IPOs/SPACs, and F-1 / 20-F foreign-private-issuer filings.

The system is deliberately self-hosted: telemetry is opt-out by construction, with adoption measured only via public GitHub signals (stars, forks, issues, PRs) (strategic-partner-firehose/README.md:248-273).

See Also

• insider-firehose skill — Form 4 sibling firehose that participates in composite MEGA SIGNAL detection
• analyze-stock skill — recommended follow-up workflow when an alert fires for an unknown ticker
• option-wall-analysis skill — option-flow check before sizing in
• macro-warning skill — regime gate before any conviction buy
• tax-optimize skill — tax math before exit

Related Pages

Related topics: Overview, Setup, and Installation, Analysis Skills Catalog, Discovery Firehoses and Real-time Channels

Price Alert System, Architecture, and Operations

Purpose and Scope

The Price Alert skill is the notification and user-interaction surface for the claude-investment-skills repository. It is shared infrastructure that multiple upstream skills call into whenever an actionable signal is detected — most notably the strategic-partner-firehose and insider-firehose skills, but also any of the analysis skills that need to push results to a human operator.

The role it plays is narrow but critical:

• Receiving signals from cron-driven detector scripts that poll public sources (SEC EDGAR 8-K, SC 13D, Form 4, price feeds).
• Normalizing and deduplicating alerts before they are sent, so a single filing does not page the operator twice.
• Pushing alerts to a Telegram chat via a Cloudflare-hosted webhook, with credentials supplied through GitHub Secrets.
• Exposing an inbound webhook endpoint so the user can issue commands back to Claude (/analyze TICKER, /option-wall TICKER, etc.) and the bot can reply with structured context.

This skill is referenced explicitly in the workflow of every other skill in the toolkit. Source: strategic-partner-firehose/README.md describes the workflow ending with *"Set price-alert if you want to wait for a dip"*, confirming the alert mechanism is the entry point for both automated detection and user-initiated analysis.

Architecture

The system is split into two cooperating halves: a detector side (Python scripts and GitHub Actions workflows under each upstream skill) and a delivery side (the Cloudflare Worker that fronts the Telegram Bot API).

Detector side

Each upstream skill (e.g. strategic-partner-firehose/scripts/partner_firehose.py) is invoked on a cron schedule by GitHub Actions. When a signal passes the skill's filters — for the strategic-partner firehose this means a Tier-1/Sovereign/Tier-2 investor in an 8-K Item 1.01/3.02 filing of a US-listed ≥ $50M mcap company, or a theme score ≥ 6 from the theme classifier — the script builds an alert payload and posts it through the shared Price Alert delivery path.

Two JSON state files accompany each detector:

• strategic_state.json — a dedup ledger of accessions already seen, so the same 8-K does not fire twice.
• recent_alerts.json — a 90-day rolling window used by the composite-signal detector to recognize when two firehoses fire on the same ticker within 30 days and emit a 🚨🚨🚨 MEGA SIGNAL. Source: strategic-partner-firehose/README.md describes *"Both firehoses log every alert to their own recent_alerts.json (90-day retention)"* and *"composite is rate-limited to 1 send per ticker per 24h"*.

Delivery side (Cloudflare Worker)

The inbound webhook is implemented as a Cloudflare Worker. The price-alert/webhook/package.json declares it explicitly:

{
  "name": "price-alert-webhook",
  "version": "1.0.0",
  "private": true,
  "description": "Cloudflare Worker — Telegram webhook handler for price-alert bot",
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "tail": "wrangler tail"
  },
  "devDependencies": {
    "@cloudflare/workers-types": "^4.20251201.0",
    "typescript": "^5.5.0",
    "wrangler": "^4.0.0"
  }
}

Source: price-alert/webhook/package.json. The presence of wrangler dev, wrangler deploy, and wrangler tail confirms the Worker is a standalone TypeScript service (per the @cloudflare/workers-types dependency) deployed to Cloudflare's edge, not a Node.js process or Cloudflare Pages function.

flowchart LR
    EDGAR[SEC EDGAR<br/>8-K / SC 13D / Form 4] -->|cron 30m| Det[Detector Scripts<br/>Python]
    Det -->|passes filters| Dedup{Dedup ledger<br/>state.json}
    Dedup -->|new accession| Alert[Build alert payload]
    Alert -->|HTTP POST| CW[Cloudflare Worker<br/>price-alert-webhook]
    CW -->|Bot API| TG[Telegram Bot API]
    TG -->|push| User[Operator chat]
    User -->|reply /command| CW
    CW -->|invoke| Claude[Claude Code skills<br/>analyze-stock, option-wall, ...]

Configuration and Setup

Setup is documented across three SETUP files in the price-alert/ directory, and the same credentials are reused across every skill that emits alerts. From the strategic-partner-firehose setup notes: *"Follow price-alert/SETUP.md once. Set TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID as GitHub Secrets. That's it — both firehoses + composite detection use the same bot."* Source: strategic-partner-firehose/README.md.

The setup is split across:

The Worker has no application-level configuration beyond the standard wrangler.toml (not visible in the provided files), and the only declared entry points are wrangler dev for local emulation and wrangler deploy for production. Source: price-alert/webhook/package.json.

Operations and Failure Modes

When an alert fires

The operator workflow, as documented in the strategic-partner-firehose README, is the canonical post-alert procedure reused by every emitting skill:

1. Read the SEC EDGAR link embedded in the alert (≈ 5–10 minutes).
2. Run /analyze TICKER in Telegram to trigger the analyze-stock skill.
3. Run /option-wall TICKER to inspect options positioning.
4. Cross-check the Partner Score factors emitted with the alert.
5. Size the position at ≤ 1% of portfolio per alert; never all-in.
6. Optionally set a price-alert to wait for a dip.

Source: strategic-partner-firehose/README.md.

Known gaps and operational risks

Because the alert pipeline is regex-driven, three failure modes are documented in the source:

• Missing alerts — the amount-extraction regex is conservative; filings that bury the dollar value in tables or refer only to "the Investment" generically will be missed. Source: strategic-partner-firehose/README.md.
• False positives — a filing that mentions a Tier-1 name in passing alongside an unrelated $200M figure (e.g. a buyback) may be misclassified; the filter pipeline minimizes but does not eliminate this.
• No semantic understanding — no LLM is invoked. v2.4 plans an LLM second-pass for ambiguous cases.

What is *not* covered

The skill explicitly does not monitor S-1 IPO prospectuses, foreign-only listings (HKEX, LSE, JPX), crypto IPOs, SPACs, or F-1 / 20-F foreign-private-issuer filings — all by design. Source: strategic-partner-firehose/README.md.

See Also

• Strategic Partner Firehose
• Insider Firehose
• Analyze Stock
• Option Wall Analysis
• Macro Warning
• Tax Optimize

Doramagic Pitfall Log

Found 9 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

1. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: packet_text.keyword_scan | https://github.com/ssurmic/claude-investment-skills

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/ssurmic/claude-investment-skills

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/ssurmic/claude-investment-skills

4. Runtime risk: Runtime risk requires verification

• Severity: medium
• Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: packet_text.keyword_scan | https://github.com/ssurmic/claude-investment-skills

5. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/ssurmic/claude-investment-skills

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/ssurmic/claude-investment-skills

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/ssurmic/claude-investment-skills

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/ssurmic/claude-investment-skills

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/ssurmic/claude-investment-skills

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using claude-investment-skills with real data or production workflows.

• Security or permission risk requires verification - GitHub / issue