Imported from recoupable/skills (
skills/recoup-catalog-import-catalog/SKILL.md). Install upstream withnpx skills add recoupable/skills --skill recoup-catalog-import-catalog. Copyright stays with the author.
Import my catalog
Read references/music-business-records.md before starting; it defines supported
file-review and hosted-save routes, source handling and completion checks.
Result
Give the user a usable catalog and a separate list of rows needing a decision, without dropping troublesome rows or turning an import into a rights claim.
Workflow
- Read the authorized CSV/spreadsheet and its worksheets, encoding, delimiter, header and row counts with available file tools. Preserve identifiers as strings, including leading zeros. Inspect the actual format; name unsupported or unreadable inputs.
- Propose column mappings for title/version, artist, ISRC, release title, UPC, release date/precision, disc/track position and any supplied composition/writer fields. Resolve ambiguous mappings with the user before treating them as facts; never interpret distributor revenue shares as songwriter or ownership shares.
- Separate recordings from release membership and compositions. Repeated ISRCs across releases may mean one recording in several products, while conflicting metadata under one ISRC requires review. Keep rows lacking IDs as unresolved candidates; do not invent identifiers or merge solely by title/artist name.
- Build an organized catalog plus a review queue. Every row retains file/sheet/row and original values; retain excluded/invalid rows and reasons. Reconcile total input rows against imported, unchanged, proposed and rejected/held rows without counting multi-release membership as new recordings.
- Compare with existing authorized catalog records if available. Reusing the same file/version should not create duplicates; changed versions produce a change list and preserve history rather than overwrite accepted identity or rights decisions.
- Discover an importer that supports this format and workspace before writing. Inspect existing catalogs and exact schemas. If an operation only associates ISRCs with a catalog, it cannot be assumed to import a spreadsheet, unresolved rows or full composition records. Verify its supported fields before use. Never use it as proof of complete import. Without suitable hosted support, return a labeled private catalog worksheet/export and review queue instead.
- Read back supported hosted writes and reconcile counts. Retain the import/version or operation receipt where returned, and identify exactly what was not saved.
Handoff
Provide catalog location, source/version, row reconciliation, unique recording and release counts where resolvable, held rows and the specific decisions needed next. Do not enroll credited people into a roster, infer rights, perform valuation, upload media or silently skip bad rows. Use the host's available deterministic file tooling; paid OCR or model extraction is a separate authorized step.
Example: 20 rows with one ISRC appearing on two releases preserve both memberships; that repeat is not automatically two recordings or a row to delete.
Repeatable intake packet
For CSV/XLSX, read references/intake.md and adapt templates/import-map.json.
Run the local helper scripts/import_catalog.py alongside this skill to produce
source fingerprints, typed candidates, release memberships, many-to-many work links,
parented interest observations and complete row dispositions. It makes no hosted writes.
Retain its packet and the original input in the selected private case. Run
python3 -m unittest discover -s tests from this skill to verify the helper.
A local proposed row is ready for review; it is not imported. Numeric spreadsheet
IDs, ambiguous identities and unsupported share semantics stay held. Separate ownership,
writer interest, administration, collection, statement percentage and producer participation.
Do not alter a percentage to make totals pass. Discover supported save schemas, record
per-field omissions and read back actual writes before promoting any row to imported.
