/geofeed-tuner

name: geofeed-tuner
description: >
  Use this skill whenever the user mentions IP geolocation feeds, RFC 8805, geofeeds, or wants help creating, tuning, validating, or publishing a
  self-published IP geolocation feed in CSV format. Intended user audience is a network
  operator, ISP, mobile carrier, cloud provider, hosting company, IXP, or satellite provider
  asking about IP geolocation accuracy, or geofeed authoring best practices.
  Helps create, refine, and improve CSV-format IP geolocation feeds with opinionated
  recommendations beyond RFC 8805 compliance. Do NOT use for private or internal IP address
  management — applies only to publicly routable IP addresses.
license: Apache-2.0
metadata:
  author: Sid Mathur <support@getfastah.com>
  version: "0.0.9"
compatibility: Requires Python 3

Geofeed Tuner – Create Better IP Geolocation Feeds

This skill helps you create and improve IP geolocation feeds in CSV format by:

• Ensuring your CSV is well-formed and consistent
• Checking alignment with [RFC 8805](references/rfc8805.txt) (the industry standard)
• Applying **opinionated best practices** learned from real-world deployments
• Suggesting improvements for accuracy, completeness, and privacy

When to Use This Skill

• Use this skill when a user asks for help **creating, improving, or publishing** an IP geolocation feed file in CSV format.
• Use it to **tune and troubleshoot CSV geolocation feeds** — catching errors, suggesting improvements, and ensuring real-world usability beyond RFC compliance.
• **Intended audience:**
• Network operators, administrators, and engineers responsible for publicly routable IP address space
• Organizations such as ISPs, mobile carriers, cloud providers, hosting and colocation companies, Internet Exchange operators, and satellite internet providers
• **Do not use** this skill for private or internal IP address management; it applies **only to publicly routable IP addresses**.

Prerequisites

• **Python 3** is required.

Directory Structure and File Management

This skill uses a clear separation between **distribution files** (read-only) and **working files** (generated at runtime).

Read-Only Directories (Do Not Modify)

The following directories contain static distribution assets. **Do not create, modify, or delete files in these directories:**

| Directory | Purpose | |----------------|------------------------------------------------------------| | `assets/` | Static data files (ISO codes, examples) | | `references/` | RFC specifications and code snippets for reference | | `scripts/` | Executable code and HTML template files for reports |

Working Directories (Generated Content)

All generated, temporary, and output files go in these directories:

| Directory | Purpose | |-----------------|------------------------------------------------------| | `run/` | Working directory for all agent-generated content | | `run/data/` | Downloaded CSV files from remote URLs | | `run/report/` | Generated HTML tuning reports |

File Management Rules

1. **Never write to `assets/`, `references/`, or `scripts/`** — these are part of the skill distribution and must remain unchanged. 2. **All downloaded input files** (from remote URLs) must be saved to `./run/data/`. 3. **All generated HTML reports** must be saved to `./run/report/`. 4. **All generated Python scripts** must be saved to `./run/`. 5. The `run/` directory may be cleared between sessions; do not store permanent data there. 6. **Working directory for execution:** All generated scripts in `./run/` must be executed with the **skill root directory** (the directory containing `SKILL.md`) as the current working directory, so that relative paths like `assets/iso3166-1.json` and `./run/data/report-data.json` resolve correctly. Do not `cd` into `./run/` before running scripts.

Processing Pipeline: Sequential Phase Execution

All phases must be executed **in order**, from Phase 1 through Phase 6. Each phase depends on the successful completion of the previous phase. For example, **structure checks** must complete before **quality analysis** can run.

The phases are summarized below. The agent must follow the detailed steps outlined further in each phase section.

| Phase | Name | Description | |-------|----------------------------|-----------------------------------------------------------------------------------| | 1 | Understand the Standard | Review the key requirements of RFC 8805 for self-published IP geolocation feeds | | 2 | Gather Input | Collect IP subnet data from local files or remote URLs | | 3 | Checks & Suggestions | Validate CSV structure, analyze IP prefixes, and check data quality | | 4 | Tuning Data Lookup | Use Fastah's MCP tool to retrieve tuning data for improving geolocation accuracy | | 5 | Generate Tuning Report | Create an HTML report summarizing the analysis and suggestions | | 6 | Final Review | Verify consistency and completeness of the report data |

**Do not skip phases.** Each phase provides critical checks or data transformations required by subsequent stages.

Execution Plan Rules

Before executing each phase, the agent MUST generate a visible TODO checklist.

The plan MUST:

• Appear at the very start of the phase
• List every step in order
• Use a checkbox format
• Be updated live as steps complete

Phase 1: Understand the Standard

The key requirements from RFC 8805 that this skill enforces are summarized below. **Use this summary as your working reference.** Only consult the full