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 files and runtime instructions match its stated purpose (running download/upload tests, logging results, and analyzing for throttling); there are no hidden endpoints, credential requests, or install steps that contradict its description.

Purpose & Capability

Name/description describe speed testing and throttling analysis; code implements downloads/uploads to public endpoints, logging, analysis, and report generation. Required resources (no env vars, writes to a home config/log path) are proportionate to the stated task.

Instruction Scope

SKILL.md and scripts instruct the agent to run local Python scripts that read/write config and logs under ~/.isp-throttle-detective and perform network requests to listed public endpoints (Cloudflare, npm registry, GitHub, optionally CloudFront). This is expected, but the scripts will perform repeated large downloads/uploads (default cap 25 MB per test, upload 5 MB) and create persistent logs — users should be aware of bandwidth, metered connections, and privacy of stored timestamps and test metadata.

Install Mechanism

Instruction-only skill with bundled Python scripts; no install spec or external archives are fetched by an installer. The code uses subprocess to call curl if available and to run local analysis; this is normal for accuracy and report generation.

Credentials

No environment variables, credentials, or config paths for unrelated services are requested. The scripts read a config file under the user's home directory (expected) and write logs there. No secrets are required or accessed.

Persistence & Privilege

Skill is not always-enabled and does not request permanent platform presence. It writes its own config and logs under ~/.isp-throttle-detective, which is appropriate for its function and within its declared scope.

Assessment

This skill appears to do what it claims. Before installing or scheduling it: (1) be aware tests download up to ~25 MB and upload ~5 MB per run by default — running every 30 minutes can consume significant data on metered connections; reduce max_download_bytes or schedule less frequently if needed; (2) logs and reports are stored under ~/.isp-throttle-detective and include timestamps and test metadata — treat them as local telemetry you may share with an ISP; (3) review and, if desired, customize the endpoints in the config (the example includes a CloudFront URL that may download a large ZIP); (4) curl is optionally invoked if present — that subprocess usage is for measurement accuracy and not executing fetched content; (5) no credentials or hidden network exfiltration were found. If you want higher assurance, inspect the packaged scripts locally or run them in a sandboxed/network-metered environment first.

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).