Terminal
Terminal/Skill
Reviews a Fivetran connector's code for correctness, security and reliability, and produces a quality report before deployment.
By Fivetran
Works with
npx skills add fivetran/connector_sdk_tools --skill evaluate-connectorContext: This plugin is for the Fivetran Connector SDK (CSDK). "CSDK" is shorthand for "Connector SDK".
FIRST: Read sdk-reference.md from the plugin directory to load SDK rules and patterns.
Perform a static code evaluation of the connector. This is a read-only analysis — do NOT modify any files.
If no connector name is provided:
Ask which connector to evaluate. List any directories in the workspace that contain a connector.py file as options.
Read all source files in the connector directory:
connector.py — required; main implementation.py files presentrequirements.txt — if present, check for incorrectly declared pre-installed packagesDo NOT read or log any values from configuration.json.
If connector.py is missing, tell the user and stop.
Analyze the code against the criteria below. Be deterministic and conservative — only flag issues with concrete code evidence. Do NOT flag theoretical or hypothetical problems.
CRITICAL SDK RULE — read before evaluating anything: SDK operations (
op.upsert,op.update,op.delete,op.checkpoint) must be called directly. They are NOT generators and must NEVER be used withyieldoryield from.
- WRONG:
yield op.upsert(table="x", data=d)- CORRECT:
op.upsert(table="x", data=d)
update()is a plain function, not a generator.yield fromis only valid inside helper pagination functions that stream raw API records — it is never valid with SDK operations.If you find code that calls SDK operations without
yield, that is correct. Do not flag it.
Flag as required only when the code clearly demonstrates the problem.
1. Memory & Resource Management
cursor.fetchall() on a large query instead of a batched/paginated fetch).close()2. SDK Compliance
update(configuration, state) function must exist and be passed to Connector() instantiationop.upsert(), op.update(), op.delete(), or op.truncate() must be calledop.checkpoint() must be calledop.upsert, op.update, op.delete, op.truncate, op.checkpoint) must be called directly — never with yield or yield from:
yield op.upsert(table="x", data=d)op.upsert(table="x", data=d)update() must not return anything — SDK operations return Nonetable, primary_key, columns keys are valid — any other key is an errorcolumns are specified, only BOOLEAN, SHORT, INT, LONG, FLOAT, DOUBLE, DECIMAL, STRING, BINARY, JSON, XML, NAIVE_DATE, NAIVE_DATETIME, UTC_DATETIME are valid — any other type name is an errorcolumns with valid types is correct and supported — do NOT flag it as an issue. Declaring a primary_key for each table is recommended.log.debug(), log.info(), log.warning(), log.error(), log.critical() — flag print(), logging.*, logger.* as required issuesGenerator[op.Operation, None, None] or any use of op.Operation in type hints is invalid — use plain dict and list only; never import from typing for SDK function signaturesexit(), sys.exit(), or os._exit() must never be used — use raise RuntimeError(...) insteadConnector(...) must be assigned to a module (global) scope variable named exactly
connector (lowercase) — not inside if __name__ == "__main__" or any function, and not
under any other name. The SDK looks specifically for a module-level connector; any other
name is a SEVERE error even though the object itself is valid.3. Security
state dict (state is persisted to disk unencrypted)log.info(f"record: {data}"))4. Data Reliability
raise_for_status() or equivalent status code checkcursor = data['updated_at'] then op.upsert(...)op.upsert(...) then cursor = data['updated_at']sdk-reference.md for the normalization rules): (1) the same logical table/column uses raw names in schema() and op.*() calls that normalize to different identifiers — flag it, this silently creates a duplicate/empty table; (2) two distinct logical tables or columns use raw names that normalize to the same identifier — flag it as a collision, this silently merges their data. Always compare normalized forms, not raw strings — aliases of the same entity that normalize identically are not a bug.5. Exception Handling
except Exception: pass)op.warning() — flag this even if the code logs the skip. log.*() never creates a
dashboard alert (see Error Handling in sdk-reference.md); only op.warning() does, and
logging is an optional supplement, not a substitute. Skipping bad rows/endpoints is fine — doing
so without op.warning() is not.1. Performance
timeout parameter2. Code Quality
requirements.txt lists requests or fivetran_connector_sdk — these are pre-installed in the runtime and must not be declaredprimary_key declared for a table — Fivetran will create a surrogate _fivetran_id key; declaring an explicit primary key is recommendedlog.fine() or log.severe() used — these are deprecated Java-style aliases; prefer log.debug() and log.error() respectively3. Configurability
configuration_form passed to Connector(...) while connector.py reads credential- or connection-specific-looking keys from the configuration dict (e.g. configuration.get("api_key"), configuration["password"], tokens, hosts, URLs) — a setup form lets users provide those values through the Fivetran dashboard instead of a manually created configuration.json, and fivetran configuration requires one to generate configuration.json interactively. Base this on keys read/validated in source code, never on configuration.json's contents. The setup form is optional: debug/run/package/deploy all work fine without it.4. Reliability
op.error(message, trace=...) would give the user a clear, dashboard-visible reason instead of a raw stack trace. Do NOT flag a plain raise RuntimeError("clear message") — that is also a correct fail-fast pattern.columns declared with valid data types — declaring types is explicitly supported by the SDK and useful for forcing a specific type. Only flag declaring a type for every column (good_to_have).configuration dict — Fivetran encrypts configurationop.upsert() data — SDK accepts bothyield from inside a helper pagination generator that streams raw API records — this is correct and unrelated to SDK operationslog.fine() or log.severe() as a required issue — they are deprecated but still work; flag as good_to_have onlyENCRYPTED:v1:<key_id>:local-fernet: values in configuration.json — this is normal; the plugin decrypts configuration values at runtime.Start at 100 and deduct based on issues found:
Required deductions:
Good-to-have deductions:
Compute three subscores:
required_score: 100 minus required deductionsgood_to_have_score: 100 minus good-to-have deductionssdk_adherence_score: 100 minus SDK-specific violations onlyFloor all scores at 0.
Present findings using this structure. Omit any section that has no issues.
## Evaluation Report — <connector_name>
### Score
Overall: <score>/100
- SDK Adherence: <sdk_adherence_score>/100
- Required: <required_score>/100
- Good to Have: <good_to_have_score>/100
### Required Issues
**[<tag>] <issue title>**
- Problem: <what is wrong>
- Location: <function name or line reference>
- Current code:
```python
<offending snippet>
<corrected snippet>
<2–3 sentence overall assessment>
**Tags:** `memory management` | `security` | `resource management` | `reliability` | `exception handling` | `input validation` | `configurability` | `code quality` | `sdk compliance` | `others`
If no issues are found in a category, write `None found.`
Do NOT suggest fixes for `good_to_have` issues unless the fix is a straightforward one-liner. Do NOT modify any files.