Geofeed-Tuner

# 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 geolocatio