Isp Throttle Detective

Run speed tests to multiple endpoints, log results, and detect ISP throttling patterns. Use when the user mentions speed test, internet slow, ISP throttling,...

Security Scan

The skill's code and instructions match its stated purpose (running and logging speed tests, analyzing patterns, and producing reports); it requests no secrets and has no surprising install steps, though it will perform network downloads/uploads and store logs in your home directory.

Purpose & Capability

Name/description (ISP throttling detection) aligns with the included scripts: speed tests (downloads + upload), logging, analysis, and report generation. Required files and config (endpoints, log path) are appropriate for this purpose.

Instruction Scope

SKILL.md and scripts restrict themselves to running downloads/uploads against configured endpoints, appending JSON lines to a log under ~/.isp-throttle-detective, analyzing that log, and producing markdown reports. There are no instructions to read unrelated system files, environment secrets, or to transmit logs to unknown third-party endpoints beyond the configured speed-test URLs.

Install Mechanism

No install spec is provided (instruction-only). The package is script-based and doesn't attempt to download or install additional code at install time. All code is included in the skill bundle.

Credentials

The skill requests no environment variables, no credentials, and only writes to a per-user directory (~/.isp-throttle-detective). The network access it needs (HTTP(S) to test endpoints and Cloudflare upload) is proportional to the stated function.

Persistence & Privilege

The skill is not forced always-on, does not request elevated privileges, and only writes its own logs/config under the user's home directory. Scheduling via cron/launchd is recommended in the docs but requires explicit user action.

Assessment

This skill appears coherent with its purpose, but review and consider the following before installing: 1) Network & data usage — default tests download up to ~25 MB and upload ~5 MB per run; schedule frequency (every 30 minutes) can consume significant data or trigger ISP rate limits. 2) Endpoints — default targets include Cloudflare, npm registry, and GitHub; you can and should edit the config to remove or replace any endpoint you don't trust. 3) Logs & privacy — results (timestamps, per-endpoint speeds, and URLs) are stored in ~/.isp-throttle-detective/speed_log.jsonl; protect or remove this file if it contains info you don't want persisted. 4) Scheduling & safety — cron/launchd entries in the guide run the scripts automatically; only enable scheduling if you accept periodic network activity. 5) Operation scope — the scripts download data but do not execute downloaded code; still avoid adding endpoints that serve executable payloads if you plan to manually inspect downloaded content. If you want extra assurance, review the included scripts locally before running and customize endpoints and schedule to match your privacy and bandwidth constraints.

Scripts live in scripts/. Log and config default to ~/.isp-throttle-detective/. See references/setup-guide.md for full setup, scheduling, and interpretation guidance.

Workflow

Run a single test and log it

python3 scripts/speedtest.py | python3 scripts/log_result.py

Analyze patterns (needs ≥5 tests across multiple hours/days)

python3 scripts/analyze.py
python3 scripts/analyze.py --days 30 --json   # machine-readable

Generate evidence report

python3 scripts/report.py --days 30 --out ~/report.md

Scripts

Script	Purpose
speedtest.py	Download from 3 endpoints + upload to Cloudflare. Outputs JSON to stdout.
log_result.py	Append speedtest JSON to JSONL log with hour, day_of_week enrichment.
analyze.py	Detect peak vs off-peak, CDN discrimination, trend, anomalies.
report.py	Generate markdown evidence report with tables and plain-English conclusion.

Configuration

Copy assets/config.example.json to ~/.isp-throttle-detective/config.json. All scripts auto-detect it. Key fields:

• log_file — where the JSONL log lives
• endpoints — add/remove test targets; set category: "cdn" vs "general" to enable CDN discrimination detection
• peak_hours — list of hours (0–23) considered peak

Pass --config /path/to/config.json to any script to override.

Scheduling

See references/setup-guide.md for launchd (macOS) and cron (Linux) snippets. Recommended: every 30 minutes for meaningful data within a day or two.

Throttling Signals

• Peak-hour drop >20% vs off-peak → time-based throttling
• CDN speed <75% of general internet → destination-based throttling
• Declining trend slope → infrastructure degradation
• Multiple low-speed anomalies at the same hour → systematic, not random

Using the Evidence Report

report.py produces a markdown file with a peak/off-peak comparison table, per-endpoint breakdown, hourly chart, trend analysis, and a plain-English conclusion. Share it directly with ISP support or use it to evaluate whether upgrading your plan would actually help (if CDN throttling is confirmed, a faster plan won't fix it).