Add similarweb-analytics Docker sandbox skill

2026-03-05 10:28:14 +08:00
--- a/similarweb-analytics/SKILL.md
+++ b/similarweb-analytics/SKILL.md
@@ -0,0 +1,156 @@
+---
+name: similarweb-analytics
+description: Analyze website and domain traffic with SimilarWeb APIs through a Docker sandbox. Use for visits, unique visitors, rank, bounce rate, traffic sources, traffic by country, and domain comparison research.
+---
+
+# SimilarWeb Analytics
+
+## Overview
+
+Use this skill to run SimilarWeb analytics in an isolated Docker container and save every API response to JSON immediately.
+Use it when the user asks about domain traffic, popularity ranking, engagement quality, channel mix, or country-level traffic split.
+
+## Trigger Cues
+
+Use this skill when the request includes one or more of these cues:
+- Domain inputs such as `google.com`, `amazon.com`, `openai.com`
+- Traffic words such as `visits`, `unique visitors`, `traffic trend`
+- Ranking words such as `global rank`, `website rank`
+- Engagement words such as `bounce rate`, `pages per visit`, `visit duration`
+- Source words such as `organic`, `paid`, `direct`, `social`, `referrals`
+- Geography words such as `top countries`, `country split`, `regional traffic`
+- Comparison words such as `compare`, `vs`, `benchmark`
+
+## Workflow
+
+1. Parse user intent into API call inputs:
+   - `domain` (required)
+   - `api` (required)
+   - Optional: `start_date`, `end_date`, `country`, `granularity`, `limit`, `main_domain_only`
+2. Build image when needed:
+   - Run `scripts/run_in_docker.sh --build -- --self-test`
+3. Execute query in Docker sandbox:
+   - Run `scripts/run_in_docker.sh -- --api <api> --domain <domain> ...`
+4. Persist output on every call:
+   - Always pass `--output /data/<file>.json` or let auto filename run in `/data`
+   - Never keep API output only in terminal output
+5. For comparisons:
+   - Execute one call per domain with the same time window
+   - Save each domain response as a separate JSON file for reproducible analysis
+
+## Command Entry Points
+
+- Main host wrapper: `scripts/run_in_docker.sh`
+- Container entrypoint: `scripts/docker/entrypoint.py`
+- Image definition: `scripts/docker/Dockerfile`
+- Runtime adapter installer: `scripts/install_runtime_adapter.sh`
+- Runtime adapter source: `scripts/runtime/data_api.py`
+- Test runner: `scripts/test_docker_workflow.sh`
+
+## Quick Start
+
+Install runtime adapter to expected host path:
+
+```bash
+/root/.codex/skills/similarweb-analytics/scripts/install_runtime_adapter.sh
+```
+
+Build image and verify runtime:
+
+```bash
+/root/.codex/skills/similarweb-analytics/scripts/run_in_docker.sh --build -- --self-test
+```
+
+Dry run without consuming API credits:
+
+```bash
+/root/.codex/skills/similarweb-analytics/scripts/run_in_docker.sh -- \
+  --api visits-total \
+  --domain amazon.com \
+  --country world \
+  --dry-run
+```
+
+Real call and save data immediately:
+
+```bash
+/root/.codex/skills/similarweb-analytics/scripts/run_in_docker.sh -- \
+  --api traffic-by-country \
+  --domain amazon.com \
+  --start-date 2025-12 \
+  --end-date 2026-02 \
+  --limit 10 \
+  --output /data/amazon-country.json
+```
+
+## Supported APIs
+
+- `global-rank` -> `SimilarWeb/get_global_rank`
+- `visits-total` -> `SimilarWeb/get_visits_total`
+- `unique-visit` -> `SimilarWeb/get_unique_visit`
+- `bounce-rate` -> `SimilarWeb/get_bounce_rate`
+- `traffic-sources-desktop` -> `SimilarWeb/get_traffic_sources_desktop`
+- `traffic-sources-mobile` -> `SimilarWeb/get_traffic_sources_mobile`
+- `traffic-by-country` -> `SimilarWeb/get_total_traffic_by_country`
+
+For parameter matrix and defaults, see `references/api-matrix.md`.
+
+## Sandbox Rules
+
+`scripts/run_in_docker.sh` runs with:
+- Non-root container user
+- Read-only root filesystem
+- `tmpfs` only for `/tmp` and `/var/tmp`
+- Dropped Linux capabilities (`--cap-drop ALL`)
+- `no-new-privileges` enabled
+- CPU, memory, and PID limits
+
+Runtime dependency mount:
+- Must mount host runtime path into container at `/opt/.manus/.sandbox-runtime`
+- Default host path is `/opt/.manus/.sandbox-runtime`
+- You can override with `--runtime-dir <path>`
+- `data_api.py` must exist in that runtime directory
+
+Credential pass-through:
+- `SIMILARWEB_API_KEY` for official Similarweb API mode
+- Optional fallback: `RAPIDAPI_KEY` and `RAPIDAPI_SIMILARWEB_HOST`
+- Runner auto-forwards these env vars into container when present
+
+## Data Constraints
+
+- Historical data window is at most 12 months
+- `traffic-by-country` is limited to at most 3 months
+- Latest reliable month is the last complete month
+- Default date range:
+  - 6 months: `global-rank`, `visits-total`, `unique-visit`, `bounce-rate`
+  - 3 months: `traffic-sources-desktop`, `traffic-sources-mobile`, `traffic-by-country`
+
+## Validation Record
+
+Last validated on `2026-03-05`:
+- Docker image build succeeded
+- Container self-test succeeded
+- End-to-end fixture call succeeded and wrote JSON output
+- Skill structure validation succeeded with `quick_validate.py`
+- Runtime adapter installed to `/opt/.manus/.sandbox-runtime/data_api.py` and imported successfully
+- Official mode live call attempted and failed fast with explicit credential error when `SIMILARWEB_API_KEY` is unset
+- Live network call attempted via RapidAPI fallback; request reached provider and returned `403 not subscribed` (credential/subscription issue, not runtime failure)
+
+## Troubleshooting
+
+- Error `data_api import failed`:
+  - Check that runtime path exists on host and is mounted to `/opt/.manus/.sandbox-runtime`
+- Error about date range:
+  - Use `YYYY-MM` format and keep range inside API limits
+- No output file:
+  - Ensure output points to `/data/...` inside container or mounted output directory from host
+
+## Resources
+
+- `scripts/docker/Dockerfile`: container image for sandbox runtime
+- `scripts/docker/entrypoint.py`: SimilarWeb API caller inside container
+- `scripts/run_in_docker.sh`: host wrapper for build and secure execution
+- `scripts/install_runtime_adapter.sh`: install runtime adapter into `/opt/.manus/.sandbox-runtime`
+- `scripts/runtime/data_api.py`: `ApiClient` adapter implementation
+- `scripts/test_docker_workflow.sh`: reproducible smoke test script
+- `references/api-matrix.md`: endpoint and parameter matrix