| name | add-iso3166 |
| description | Add ISO 3166 country codes (alpha-2, alpha-3, numeric) to a dataset that references countries by name but lacks standardised codes. Use when the user has a CSV/JSON/Parquet/Excel dataset with country names and wants ISO 3166 codes added as new columns/fields. |
Add ISO 3166 Country Codes
Add ISO 3166-1 codes to a dataset whose country column contains plain names.
When to invoke
- Dataset has a country column (named
country, nation, country_name, or similar) but no ISO code column.
- User asks to "add country codes", "add ISO codes", "enrich with ISO 3166".
Procedure
- Locate the dataset — confirm file path and format (CSV, JSON, JSONL, Parquet, XLSX).
- Identify the country column — if multiple candidates exist or the column is ambiguous, ask the user which column holds the country name.
- Check for pre-existing codes — if an ISO column already exists, report and ask whether to overwrite or skip.
- Load data with pandas (
pd.read_csv, pd.read_json, pd.read_parquet, pd.read_excel).
- Resolve country names to ISO codes using
pycountry:
- Try exact match first via
pycountry.countries.get(name=...) and .lookup(...).
- For fuzzy/partial matches, use
pycountry.countries.search_fuzzy(...) with a confidence threshold.
- Common aliases to hard-code before fuzzy matching:
USA/U.S./U.S.A. → United States, UK → United Kingdom, Russia → Russian Federation, South Korea → Korea, Republic of, North Korea → Korea, Democratic People's Republic of, Ivory Coast → Côte d'Ivoire, Czech Republic → Czechia, Burma → Myanmar.
- Add columns:
iso3166_alpha2, iso3166_alpha3, iso3166_numeric. Ask the user if they want all three or a subset — default to all three.
- Report unresolved rows — list every country value that could not be mapped, with row counts. Do not silently drop or leave blank without reporting.
- Write output — save alongside the input with
_iso3166 suffix by default (e.g. countries.csv → countries_iso3166.csv), preserving the input format. Confirm path with user if ambiguous.
- Update the data dictionary — if a data dictionary exists in the same folder (see
add-data-dictionary / update-data-dictionary skills), add the new columns. If none exists, offer to create one.
Dependencies
pip install pandas pycountry openpyxl pyarrow
Edge cases
- Subnational regions (e.g. "Scotland", "Catalonia") — flag and ask user whether to map to parent country or leave blank.
- Historical entities ("USSR", "Yugoslavia", "Czechoslovakia") — ISO 3166-3 covers these; offer that as an option.
- Multi-country rows (e.g. "Germany / France") — flag and ask user how to handle (split, skip, keep first).
- Empty / null country values — leave ISO columns null; report count.
