From adva-superpowers
Use when the user wants to import, onboard, or migrate data from an external source (CSV, spreadsheet, API export, or another system like Airtable, Google Sheets, Jobber, Salesforce) into the Adva platform. Covers source inspection, entity mapping, validation, idempotent uploads via the adva-staging MCP, and troubleshooting common friction.
How this skill is triggered — by the user, by Claude, or both
Slash command
/adva-superpowers:onboard-dataThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guide an agent through importing data from any external source into Adva. This skill is **source-agnostic** — whatever the source system is (spreadsheet, API, database dump, hand-built CSV), the workflow is the same once the agent can read rows from it. Source-specific quirks live in separate reference files, loaded only when relevant.
Guide an agent through importing data from any external source into Adva. This skill is source-agnostic — whatever the source system is (spreadsheet, API, database dump, hand-built CSV), the workflow is the same once the agent can read rows from it. Source-specific quirks live in separate reference files, loaded only when relevant.
Inspect the source. Enumerate what's there (tables / sheets / files) and pull a small sample (3–5 rows) from each candidate table. Use whatever read path is connected — an MCP server for the source, the Read tool for local files, or a hand-written CSV. Avoid pulling the full dataset into context; samples are enough to draft mappings.
List Adva's target entities. Call mcp__adva-staging__list_entity_types. Entities are organized into tiers (1–6); lower tiers must be imported before higher ones. Typical order:
Fetch the target schema. Call mcp__adva-staging__get_import_schema with the entity type. The returned schema is the contract — field names, types, required flags, enum constraints. Treat unknown fields as "drop from mapping" rather than "pass through".
Draft a mapping. Produce an explicit {source_field → adva_field} mapping by comparing the schema to the source columns and sample values. Show the mapping to the user and get confirmation before proceeding. The MCP exposes mcp__adva-staging__suggest_column_mapping for AI-assisted drafting, but it may return a Workers AI error code (5024); if it does, fall back to manual mapping from the schema + samples.
Validate first. Send a small batch (3–5 records) through mcp__adva-staging__validate_records. This is a dry run — it reports errors without writing. Surface every error to the user. Fix the mapping, drop bad rows, or ask about ambiguous values before moving on.
Upload in chunks. Once the batch validates cleanly, call mcp__adva-staging__upload_records with the full set. Chunk large imports (roughly 50–200 records per call). If the user has a well-formed CSV already, mcp__adva-staging__upload_csv is a one-shot alternative — the server parses it.
Poll status. Uploads are async — upload_records returns a job_id. Call mcp__adva-staging__get_import_status(job_id) until it reports completion. Expect 10–30s of queue latency before processing actually starts; that's normal, not a hang.
Verify idempotency. Call mcp__adva-staging__get_external_ids with the same source value to confirm records are linked. Re-running the import should upsert (match by external_id), not duplicate.
These are Adva platform facts. Violating them breaks idempotency, produces bad data, or fails validation.
external_id and source on every record. external_id is the source system's primary key; source is a short string identifying the system (e.g. "csv_upload", "sheets", "jobber"). Without these, every re-run creates duplicates.*_external_id fields, never Adva UUIDs. E.g. on a proposal, set customer_external_id to the source's customer ID. The import API resolves these to Adva UUIDs via an external-id index.custom_fields is a JSON object, not a string. The schema may describe it as a generic field, but the validator requires an object keyed by custom-field name, e.g. {"HOA Name": "Oak Valley"}.If the source is rich (Airtable, a database) but the user prefers to review data before upload, an intermediate CSV can be a good pattern:
external_id and source).mcp__adva-staging__upload_csv or by reading it back and calling upload_records.This is especially useful when the user wants to spot-check name cleanup, enum translation, or sensitive fields before anything lands in Adva.
Some source systems have quirks worth knowing. Load the relevant reference only if the user's source matches — otherwise keep it out of context.
If the user's source isn't in this list, proceed with the core workflow. If you hit friction that would have been useful to document for the next user, capture it — a new reference file for that source is the right follow-up.
"Business" / "Individual", Adva expects "commercial" / "residential"). Read the schema's enum constraints and build a per-field translation map. Validation errors will point at the offending field — use them.location record, not directly on a customer. Customer → location is 1:N.npx claudepluginhub rightsite-cloud/adva-superpowers --plugin adva-superpowersCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.