gemini-cli-extensions/data-agent-kit-starter-pack/schema-mapping
Claude Code and agent skill by gemini-cli-extensions/data-agent-kit-starter-pack
- community
Checking that the SKILL.md file is still in the repository.
Guides the process of analyzing, mapping, and documenting transformations between source and target schemas for any database, data warehouse, or data platform. Focuses exclusively on creating a high-fidelity mapping plan (Mapping Manifesto). Used when initiating an ETL, ELT, or data integration task with schema mapping specification for multiple tables (i.e. more than 3 tables) before writing code. Do NOT use this skill for basic SQL generation without mapping requirements, or when the user already has a complete mapping specification.
Install
npx vskill@latest install gemini-cli-extensions/data-agent-kit-starter-pack/schema-mappingSKILL.md
The same SKILL.md was published earlier as gemini-cli-extensions/data-agent-kit-starter-pack/schema-mapping.
Skill: Semantic Schema Mapping Planning
Follow this structured process and procedures for analyzing source-to-target data relationships and creating a high-fidelity Mapping Plan (also known as a Mapping Manifesto). This process is platform-agnostic and should be used before generating any target-specific pipeline code. When this skill is loaded, you MUST use this plan and replace the existing generic plan.
When to Use
Use this skill when:
- You need to map schemas between a source dataset/database and a target
destination database/warehouse.
- You are initiating an ETL, ELT, or data integration task.
- You need to identify schema gaps, data type conflicts, or aggregation
requirements.
Required Input Variables
Before creating the plan, you must obtain or request:
- `SOURCE_SCHEMAS`: Definitions (schemas, tables, fields, types) of the
source data.
- `TARGET_SCHEMAS`: Definitions of the desired target/destination schemas.
- `BUSINESS_CONTEXT`: Domain details, business rules, or use case
description.
- `TARGET_PLATFORM`: The database or execution engine (e.g., BigQuery,
Snowflake, Postgres, Spark, Beam).
Optional Input Variables
- `KNOWLEDGE_GRAPH`: If there's a knowledge graph / property graph
available, always inspect the graph for node table definitions, edge table definitions, and foreign key bindings (SOURCE / DESTINATION key references), etc.
The Schema Mapping Planning Procedure
[!IMPORTANT] Execution Strategy: Table-by-Table IterationYou MUST execute this procedure iteratively, one target table at a time.For each individual table in theTARGET_SCHEMAS, complete Steps 1 through 6sequentially before moving to the next table. Do not attempt to map orsummarize multiple tables in a single batch, as this leads to hallucinations,overlooked constraints, and context window bloat.
Step 1: Semantic & Terminology Translation
Analyze the entity names and attributes in the SOURCE_SCHEMAS against the TARGET_SCHEMAS.
- Synonym Resolution: Using the
BUSINESS_CONTEXT, map matching concepts
with different names (e.g., client_id vs customer_num).
- Identify Domain Standards: Match field values or formats to known
standards (e.g., ISO country codes, currency codes, UN/LOCODE, UUIDs) based on the business context.
- Verify Domain Semantics: Do not rely purely on lexical matching (name
similarity). Verify the functional business purpose of the entities in both schemas. Ensure that a target table representing a specific business resource maps to a source table modeling that same resource rather than an unrelated administrative log or generic list table sharing a similar name.
Step 2: Establish the Anchor Table
For each table or collection in the TARGET_SCHEMAS:
- Identify the primary source table (the "Anchor Table") that holds the
core records for this target.
- Identify contributing/lookup tables in the source that will enrich the
target records.
- Prefer Structured Tables over Generic Key-Value Tables: If the same
attribute exists in both a structured column in a domain table and as a generic property in an Entity-Attribute-Value (EAV) key-value/properties table, always anchor on the structured table to ensure schema stability and performant joins.
Step 3: Proactive Data Sampling & Inspection
If a target field mapping is ambiguous or schema types do not tell the whole story (e.g., verifying if a timestamp is ISO-8601, if a string is a JSON array, or checking the distribution of values):
- Proactive Inspection: If environment access allows, run
platform-specific queries (e.g., SELECT ... LIMIT 10, SELECT COUNT(DISTINCT ... )) to sample values.
- User Inquiry: If direct access is not possible, output sample queries
and ask the user to provide the output to confirm assumptions before finalizing the plan.
Step 4: Perform Field-Level Gap Analysis & Cleanliness Design
Evaluate every column in each target table to determine its source mapping. Categorize mappings and plan cleanliness transformations:
- Direct Mapping: A 1-to-1 match.
- Derived Mapping: Requires type casting, string manipulation, date
formatting, mathematical derivation, or case statement logic.
- Joined Mapping: Requires looking up values from contributing tables
using defined join keys.
- Aggregated Mapping: Requires collapsing 1-to-many relationships (e.g.,
calculating SUM, COUNT, ARRAY_AGG or string concatenation).
- Gaps (Unmapped fields): Target fields that do not exist in the source.
- Constraint Checking: Verify whether the target column has a
NOT NULL or REQUIRED constraint in the target schema.
- Handling Nullable Gaps: If the target column is nullable, explicitly
flag it as NULL or define a default value.
- Handling Non-Nullable Gaps: If the target column is
NOT NULL, you
MUST NOT map it to NULL. (Rationale: Mapping NOT NULL target columns to NULL will cause execution-time database constraint violations and pipeline failures). You must identify a source field to derive it from, default it to a valid non-null placeholder (e.g., 'UNKNOWN', 0, or default dates), or define logic to generate a valid unique reference.
Universal Data Cleanliness Rules to Incorporate in Mappings:
- Null Standardization: Map source strings like
"NULL","None",
"N/A", or empty spaces to true database NULL values.
- Trim & Casing: Plan to trim leading/trailing whitespaces. Convert
standardized codes (e.g., ISO codes, status strings) to uppercase.
- Temporal Consistency: Plan to parse all source timestamps into standard
ISO-8601 format (YYYY-MM-DDTHH:MM:SSZ) or standard destination TIMESTAMP format. Plan checks to ensure logical temporal progression (e.g., start_time <= end_time).
- Defensive Checks: Plan checks for strict destination types (e.g.,
checking if string is a valid number before casting to DECIMAL).
Step 5: Map Relationships & Joins
Specify the logical join path to connect the Anchor Table with all contributing source tables:
- Define the join condition/keys (e.g.,
source_order.customer_id = source_customer.id).
- Identify join scale properties:
- Large-to-Large: Joining two high-volume transaction tables.
- Large-to-Small: Joining a transaction table to a static lookup table
(ideal for Map-side/Broadcast joins to optimize speed/cost).
- Document potential join challenges:
- Many-to-many risks or potential duplicate generation.
- Type mismatches on join keys (e.g., joining an
INTcolumn to a
STRING column).
- Graph Validation: If a graph was identified in input, cross-reference
the proposed join conditions with the graph's edge table definitions to validate foreign key relationships.
Step 6: Draft the "Mapping Manifesto" (Output Format & Example)
Analyze the schemas and reference the ONE_SHOT_EXAMPLE below to structure your output.
ONE_SHOT_EXAMPLE (How to Structure the Mapping Manifesto)
Example Source Schemas
Example Target Schemas
The Mapping Manifesto (Expected Output Format)
For each target table, document your column-to-column reasoning:
Critical Operational Rules
- Plan Before Execution: You MUST NOT generate any ETL code,
target-specific pipeline configurations, or migration scripts until the Mapping Manifesto has been presented to and approved by the user. (Rationale: Establishing clear mapping logic first prevents coding errors, avoids circular dependencies, and ensures user alignment on semantic mappings before wasting resources on implementation).
- Strict Schema Grounding: Every source table and field name referenced in
the mapping plan MUST exactly match the names and data types present in the provided SOURCE_SCHEMAS. You MUST NOT reference non-existent columns, guess field names, or make assumptions about source schemas without explicitly confirming them in the schema definitions. (Rationale: Proposing guesses leads to compilation errors and invalid mapping specifications).
- Target Schema Constraint Integrity: You must never propose a mapping
that writes NULL to a column defined as NOT NULL or REQUIRED in the TARGET_SCHEMAS.
- Exhaustive Field Search: Before declaring a target field as an "Unmapped
/ Gap", search all available source schemas to verify the data is not in a less-obvious table. (Rationale: Lazy mappings that default target fields to NULL lead to downstream data loss and incomplete pipelines).
- Defensive Type Mapping: Explicitly plan the transformation rules for
strict destination types (e.g. TIMESTAMP, BOOLEAN, DECIMAL) to avoid load failures. (Rationale: Different databases and platforms handle type validation strictly; pre-planning casts prevents execution-time runtime errors).
- Data Integrity Check: Identify join conditions that could cause
Cartesian product expansion or data duplication, and note prevention strategies in the plan. (Rationale: Unvalidated joins can distort aggregated metrics or exhaust processing memory on large datasets).
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewNot runA model review is scheduled for the next rescan.
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/schema-mapping/SKILL.md
Popularity
- Repository stars
- 187
- Repository forks
- 57
- 7-day trend score
- 26
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/gemini-cli-extensions/data-agent-kit-starter-pack/schema-mapping)