选择路径

动作：

• 一次性请求，用户触发，使用 createAction() 构建
• 编写代码前阅读 references/actions.md

同步：

• 计划任务或 webhook 驱动的缓存更新，使用 createSync() 构建
• 首先完成同步策略关口
• 编写代码前阅读 references/syncs.md

工作流程（推荐）

1. 决定这是动作还是同步。
2. 阅读相应的参考文件：references/actions.md 或 references/syncs.md。
3. 对于同步，检查提供者文档或负载以了解检查点和删除，决定端点返回完整数据还是变更行，并完成同步策略关口。
4. 收集所需的输入和外部值。对于连接查找、凭据或发现，使用 Nango HTTP API。
5. 确认这是零 YAML TypeScript 项目（no nango.yaml）并且你在 Nango 根目录（存在 .nango/）。
6. 在 {integrationId}/actions/ 或 {integrationId}/syncs/ 下创建或更新函数，应用此处的模式和命名规则，然后在 index.ts 中注册它。
7. 使用 nango dryrun ... --validate -e dev --no-interactive --auto-confirm 进行验证。
8. 如果验证无法通过，停止并报告缺少的外部状态或输入。
9. 验证通过后，运行 nango dryrun ... --save，然后运行 nango generate:tests，接着运行 npm test。
10. 仅在请求时使用 nango deploy dev 进行部署。

必需输入（若缺失则询问用户）

始终需要：

• 集成 ID（提供者名称）
• 连接 ID（用于 dryrun）
• 脚本名称（kebab-case）
• API 参考 URL 或示例响应

动作特定：

• 用例摘要
• 输入参数
• 输出字段
• 所需的元数据 JSON
• 用于 dryrun --input 和模拟测试的测试输入 JSON（必需；对于无输入动作使用 {}）

同步特定：

• 模型名称（单数，PascalCase）
• 频率（每小时、每 5 分钟等）
• 检查点模式（时间戳、游标、页面令牌、偏移量/页码、since_id 或复合模式）
• 检查点如何改变提供者请求或恢复状态
• 删除策略（删除记录端点/webhook，或为何需要完全刷新）
• 如果提议完全刷新，来自文档/示例响应的阻碍检查点的确切提供者限制
• 所需的元数据 JSON（team_id、workspace_id）

如果缺少任何必需的外部值，请在检查仓库和提供者文档后提出有针对性的问题。对于同步，只要提供者支持，就选择检查点加删除策略。如果找不到可行的检查点策略，请在编写完全刷新之前确切说明原因。

前提条件（编码前执行）

确认 TypeScript 项目（无 nango.yaml）

此技能仅支持使用 createAction()/createSync() 的 TypeScript 项目。

ls nango.yaml 2>/dev/null && echo "YAML PROJECT DETECTED" || echo "OK - No nango.yaml"

如果看到 YAML PROJECT DETECTED：

• 立即停止。
• 告诉用户先升级到 TypeScript 格式。
• 不要尝试混合 YAML 和 TypeScript。

参考：https://nango.dev/docs/implementation-guides/platform/migrations/migrate-to-zero-yaml

验证 Nango 项目根目录

在确认 Nango 根目录之前不要创建文件：

ls -la .nango/ 2>/dev/null && pwd && echo "IN NANGO PROJECT ROOT" || echo "NOT in Nango root"

如果看到 NOT in Nango root：

• cd 到包含 .nango/ 的目录
• 重新运行检查
• 不要使用绝对路径作为变通方法

所有文件路径必须相对于 Nango 根目录。在已处于 Nango 根目录时使用额外前缀创建文件将创建嵌套目录，从而破坏构建。

项目结构和命名

./
|-- .nango/
|-- index.ts
|-- hubspot/
|   |-- actions/
|   |   `-- create-contact.ts
|   `-- syncs/
|       `-- fetch-contacts.ts
`-- slack/
    `-- actions/
        `-- post-message.ts

• 提供者目录：小写（hubspot、slack）
• 动作文件：kebab-case（create-contact.ts）
• 同步文件：kebab-case（许多团队使用 fetch- 前缀，但它是可选的）
• 每个文件一个函数（动作或同步）
• 所有动作和同步必须在 index.ts 中导入

在 index.ts 中注册脚本（必需）

仅使用副作用导入（无默认/命名导入）。包含 .js 扩展名。

// index.ts
import './github/actions/get-top-contributor.js';
import './github/syncs/fetch-issues.js';

注册不正确的症状：文件编译但看到 No entry points found in index.ts... 或函数从未出现。

不可协商的规则

共享平台约束

• 零 YAML TypeScript 项目使用 createAction() / createSync()，而不是 nango.yaml。
• 使用副作用导入（import './<path>.js'）在 index.ts 中注册每个动作/同步。
• 不能添加任意包。使用相对导入；内置包包括 zod、crypto/node:crypto 和 url/node:url。
• 在函数代码外部使用 Nango HTTP API 进行连接查找、凭据和代理调用。不要发明 CLI 令牌/连接命令。
• 在每个提供者调用上方添加 API 文档链接注释。
• 动作输出不能超过 2MB。
• HTTP 重试默认值为 0；特意设置 retries，特别是对于写入操作。

同步规则

• 同步记录需要一个稳定的字符串 id。
• 新同步应定义 checkpoint 模式，首先调用 nango.getCheckpoint()，并在每个页面或批次后调用 nango.saveCheckpoint()。
• 仅当检查点改变请求或恢复状态（since、updated_after、cursor、page_token、offset、page、since_id 等）时才有效。保存一个而不使用它不是增量同步。
• 新同步不得使用 syncType: 'incremental' 或 nango.lastSyncDate。
• 默认使用 nango.paginate(...) + nango.batchSave(...)。当 cursor、link 或 offset 分页适用时，避免手动 while (true) 循环。
• 当提供者返回删除、墓碑或删除 webhook 时，优先使用 batchDelete()。
• 仅当提供者无法返回变更、删除或恢复状态，或者数据集很小时，才使用完全刷新。
• 对于完全刷新，引用文档或负载中的确切提供者限制。“它更容易”是不够的。
• deleteRecordsFromPreviousExecutions() 已弃用。对于完全刷新，在获取/保存之前调用 trackDeletesStart()，并且仅在成功完成完整获取/保存后调用 trackDeletesEnd()。
• 切勿将 trackDeletesStart() / trackDeletesEnd() 与仅变更检查点（modified_after、updated_after、变更记录端点等）结合使用。它们会忽略未变更的行，因此 trackDeletesEnd() 会删除它们。
• 带检查点的完全刷新仍然是完全刷新。仅在完成完整窗口的运行中调用 trackDeletesEnd()。

约定

• 字段命名与外部 API 匹配。直通字段保持提供者命名；非直通字段应使用该 API 的主流命名。
• 优先使用显式字段名。
• 为 ID、时间戳、枚举和 URL 添加 .describe() 示例。
• 避免 any；使用内联映射类型。
• 优先使用静态 Nango 端点路径（避免在暴露的端点中使用 :id / {id}）；在输入/参数中传递 ID。
• 列表动作应暴露 cursor 加上该 API 主流命名的下一个游标字段（next_cursor、nextCursor 等）。
• 仅当需要自定义验证或日志记录时才使用 nango.zodValidateInput()；否则依赖模式 + nango dryrun --validate。

模式语义

• 将非必需输入默认为 .optional()。
• 仅当 null 有意义时才使用 .nullable()，通常是更新时清除；当调用者也可能省略该字段时添加 .optional()。
• 原始提供者模式应与提供者匹配：省略的字段用 .optional()，显式 null 用 .nullable()，仅当提供者确实两者都做时才使用 .nullish()。
• 最终动作输出和规范化的同步模型应优先使用 .optional()，并将上游 null 规范化为省略，除非 null 很重要。
• 将生成的模式默认为非必需输入和规范化输出的 .optional()；仅当上游合约证明有必要时才放宽。
• 优先使用 .nullable() 而不是 z.union([z.null(), T]) 或 z.union([T, z.null()])。
• 仅当输出模式允许时才返回 null。
• z.object() 默认剥离未知键。对于提供者直通，使用 z.object({}).passthrough()、z.record(z.unknown()) 或带有最少细化的 z.unknown()。

字段命名和大小写规则

• 使用 API 主流命名中的显式后缀：ID（user_id、userId）、名称（channel_name、channelName）、电子邮件（user_email、userEmail）、URL（callback_url、callbackUrl）和时间戳（created_at、createdAt）。

映射示例（API 期望不同的参数名）：

const InputSchema = z.object({
    userId: z.string()
});

const config: ProxyConfiguration = {
    endpoint: 'users.info',
    params: {
        user: input.userId
    },
    retries: 3
};

如果 API 是 snake_case，则使用 user_id。目标是保持 API 一致性。

Dryrun、模拟和测试（必需）

必需循环（不要跳过步骤）：

1. 运行 nango dryrun ... --validate -e dev --no-interactive --auto-confirm 直到通过。
2. 动作：始终传递 --input '{...}'（对于无输入动作使用 --input '{}'）。
3. 同步：当需要模拟恢复运行时，使用 --checkpoint '{...}'。
4. 如果验证无法通过，停止并说明缺少的外部状态或所需输入。
5. 验证通过后，运行 nango dryrun ... --save -e dev --no-interactive --auto-confirm 以生成 <script-name>.test.json。
6. 运行 nango generate:tests，然后运行 npm test。

硬性规则：

• 将 <script-name>.test.json 视为生成的输出。切勿创建、编辑、重命名或移动它（包括记录的 hash 字段）。
• 如果模拟错误或过时，修复代码并使用 --save 重新记录。
• 不要在 *.test.json 中硬编码错误负载；对于 404/401/429/超时情况，使用带有 vi.spyOn(...) 的 Vitest 测试。
• 连接 ID 是第二个位置参数；不要使用 --connection-id。
• 当脚本名称在集成之间重叠时，使用 --integration-id <integration-id>。
• 对于新的增量同步，优先使用 --checkpoint；--lastSyncDate 是遗留模式。
• 如果 nango 不在 PATH 上，使用 npx nango ...。
• CLI 升级提示可能会阻止自动化；如果需要，设置 NANGO_CLI_UPGRADE_MODE=ignore。

参考：https://nango.dev/docs/implementation-guides/platform/functions/testing

参考资料

• 动作模式、CRUD 示例、元数据使用和 ActionError 示例：references/actions.md
• 同步模式、具体检查点示例、删除策略和完全刷新回退：references/syncs.md

有用的 Nango 文档（快速链接）

• 函数运行时 SDK 参考：https://nango.dev/docs/reference/functions
• 实现动作：https://nango.dev/docs/implementation-guides/use-cases/actions/implement-an-action
• 实现同步：https://nango.dev/docs/implementation-guides/use-cases/syncs/implement-a-sync
• 检查点：https://nango.dev/docs/implementation-guides/use-cases/syncs/checkpoints
• 删除检测（完全 vs 增量）：https://nango.dev/docs/implementation-guides/use-cases/syncs/deletion-detection
• 测试集成（dryrun、--save、Vitest）：https://nango.dev/docs/implementation-guides/platform/functions/testing
• Nango HTTP API 参考：https://nango.dev/docs/reference/api

部署（可选）

将函数部署到 Nango 账户中的环境：

nango deploy dev

# 仅部署一个函数
nango deploy --action <action-name> dev
nango deploy --sync <sync-name> dev

参考：https://nango.dev/docs/implementation-guides/use-cases/actions/implement-an-action

当 API 文档无法渲染时

如果网页抓取返回不完整的文档（JS 渲染）：

• 向用户请求示例响应
• 使用仓库中现有的动作/同步作为模式
• 运行带 --validate 的 dryrun 直到通过，然后运行带 --save 的 dryrun，接着运行 nango generate:tests

最终检查清单

动作：

• Nango 根目录已验证
• 使用了 references/actions.md 中的动作模式
• 模式和类型清晰，缺失值规则与提供者 vs 规范化合约匹配
• createAction() 包含端点、输入、输出和所需的作用域
• 字段使用直通命名或 API 的主流命名
• 提供者调用包含 API 文档链接注释和特意设置的重试次数
• 预期失败时使用 nango.ActionError
• 已在 index.ts 中注册
• Dryrun 使用 --validate -e dev --no-interactive --auto-confirm --input '{...}' 成功
• <action-name>.test.json 由 nango dryrun ... --save 在 --validate 后生成
• 已运行 nango generate:tests 且 npm test 通过

同步：

• Nango 根目录已验证
• 使用了 references/syncs.md 中的同步模式
• 模型映射已定义，id 是稳定的字符串，规范化模型优先使用 .optional()，除非 null 重要
• 首先选择了增量，并定义了检查点模式，除非有来自文档或负载的明确理由进行完全刷新
• 开始时读取 nango.getCheckpoint()，并在每个页面或批次后运行 nango.saveCheckpoint()
• 检查点数据改变了提供者请求或恢复状态（since、updated_after、cursor、page_token、offset、page、since_id 等）
• 仅变更检查点同步（modified_after、updated_after、变更记录端点）不使用 trackDeletesStart() / trackDeletesEnd()
• 如果未使用检查点，响应确切说明了为何不存在可行的检查点策略
• 原始提供者模式正确建模了省略与 null，字段使用直通命名或 API 的主流命名
• 使用 nango.paginate()，除非 API 确实无法适应 Nango 的分页器
• 删除策略与同步类型匹配：仅当提供者返回显式删除时，增量同步使用 batchDelete()；否则完全刷新回退在获取/保存之前使用 trackDeletesStart()，并且仅在成功完成完整获取加保存后使用 trackDeletesEnd()
• 处理了所需的元数据
• 已在 index.ts 中注册
• Dryrun 使用 --validate -e dev --no-interactive --auto-confirm 成功
• <sync-name>.test.json 由 nango dryrun ... --save 在 --validate 后生成
• 已运行 nango generate:tests 且 npm test 通过

每周安装次数

107

仓库

nangohq/skills

首次出现

2026年2月12日

安全审计

Gen Agent Trust HubPassSocketPassSnykWarn

安装于

opencode106

codex105

gemini-cli104

kimi-cli104

github-copilot104

amp104

• full refresh because it is simpler
• saveCheckpoint() without getCheckpoint()
• reading or saving a checkpoint without using it in request params or pagination state
• using syncType: 'incremental' or nango.lastSyncDate in a new sync
• using trackDeletesStart() / trackDeletesEnd() with a changed-only checkpoint (modified_after, updated_after, changed-records endpoint). Those requests omit unchanged rows, so trackDeletesEnd() will falsely delete them.
• using trackDeletesStart() / trackDeletesEnd() in an incremental sync that already has explicit deleted-record events

Choose the Path

Action:

• One-time request, user-triggered, built with createAction()
• Read references/actions.md before writing code

Sync:

• Scheduled or webhook-driven cache updates built with createSync()
• Complete the Sync Strategy Gate first
• Read references/syncs.md before writing code

Workflow (recommended)

1. Decide whether this is an action or a sync.
2. Read the matching reference file: references/actions.md or references/syncs.md.
3. For syncs, inspect provider docs or payloads for checkpoints and deletes, decide whether the endpoint returns full data or changed rows, and complete the Sync Strategy Gate.
4. Gather required inputs and external values. For connection lookup, credentials, or discovery, use the Nango HTTP API.
5. Confirm this is a Zero YAML TypeScript project (no nango.yaml) and that you are in the Nango root (.nango/ exists).
6. Create or update the function under {integrationId}/actions/ or {integrationId}/syncs/, apply the schema and casing rules here, then register it in index.ts.
7. Validate with nango dryrun ... --validate -e dev --no-interactive --auto-confirm.
8. If validation cannot pass, stop and report the missing external state or inputs.
9. After validation passes, run nango dryrun ... --save, then nango generate:tests, then npm test.
10. Deploy with nango deploy dev only when requested.

Required Inputs (Ask User if Missing)

Always:

• Integration ID (provider name)
• Connection ID (for dryrun)
• Script name (kebab-case)
• API reference URL or sample response

Action-specific:

• Use case summary
• Input parameters
• Output fields
• Metadata JSON if required
• Test input JSON for dryrun --input and mocks (required; use {} for no-input actions)

Sync-specific:

• Model name (singular, PascalCase)
• Frequency (every hour, every 5 minutes, etc.)
• Checkpoint schema (timestamp, cursor, page token, offset/page, since_id, or composite)
• How the checkpoint changes the provider request or resume state
• Delete strategy (deleted-record endpoint/webhook, or why full refresh is required)
• If proposing a full refresh, the exact provider limitation that blocks checkpoints from the docs/sample response
• Metadata JSON if required (team_id, workspace_id)

If any required external values are missing, ask a targeted question after checking the repo and provider docs. For syncs, choose a checkpoint plus deletion strategy whenever the provider supports one. If you cannot find a viable checkpoint strategy, state exactly why before writing a full refresh.

Preconditions (Do Before Writing Code)

Confirm TypeScript Project (No nango.yaml)

This skill only supports TypeScript projects using createAction()/createSync().

ls nango.yaml 2>/dev/null && echo "YAML PROJECT DETECTED" || echo "OK - No nango.yaml"

If you see YAML PROJECT DETECTED:

• Stop immediately.
• Tell the user to upgrade to the TypeScript format first.
• Do not attempt to mix YAML and TypeScript.

Reference: https://nango.dev/docs/implementation-guides/platform/migrations/migrate-to-zero-yaml

Verify Nango Project Root

Do not create files until you confirm the Nango root:

ls -la .nango/ 2>/dev/null && pwd && echo "IN NANGO PROJECT ROOT" || echo "NOT in Nango root"

If you see NOT in Nango root:

• cd into the directory that contains .nango/
• Re-run the check
• Do not use absolute paths as a workaround

All file paths must be relative to the Nango root. Creating files with extra prefixes while already in the Nango root will create nested directories that break the build.

Project Structure and Naming

./
|-- .nango/
|-- index.ts
|-- hubspot/
|   |-- actions/
|   |   `-- create-contact.ts
|   `-- syncs/
|       `-- fetch-contacts.ts
`-- slack/
    `-- actions/
        `-- post-message.ts

• Provider directories: lowercase (hubspot, slack)
• Action files: kebab-case (create-contact.ts)
• Sync files: kebab-case (many teams use a fetch- prefix, but it's optional)
• One function per file (action or sync)
• All actions and syncs must be imported in index.ts

Register scripts in index.ts (required)

Use side-effect imports only (no default/named imports). Include the .js extension.

// index.ts
import './github/actions/get-top-contributor.js';
import './github/syncs/fetch-issues.js';

Symptom of incorrect registration: the file compiles but you see No entry points found in index.ts... or the function never appears.

Non-Negotiable Rules

Shared platform constraints

• Zero YAML TypeScript projects use createAction() / createSync(), not nango.yaml.
• Register every action/sync in index.ts with side-effect imports (import './<path>.js').
• You cannot add arbitrary packages. Use relative imports; built-ins include zod, crypto/node:crypto, and url/node:url.
• Use the Nango HTTP API for connection lookup, credentials, and proxy calls outside function code. Do not invent CLI token/connection commands.
• Add an API doc link comment above each provider call.
• Action outputs cannot exceed 2MB.
• HTTP retries default to 0; set retries deliberately, especially for writes.

Sync rules

• Sync records need a stable string id.
• New syncs should define a checkpoint schema, call nango.getCheckpoint() first, and nango.saveCheckpoint() after each page or batch.
• A checkpoint is valid only if it changes the request or resume state (since, updated_after, cursor, page_token, offset, page, since_id, etc.). Saving one without using it is not incremental sync.
• New syncs must not use syncType: 'incremental' or nango.lastSyncDate.
• Default to nango.paginate(...) + nango.batchSave(...). Avoid manual while (true) loops when cursor, link, or offset pagination fits.
• Prefer batchDelete() when the provider returns deletions, tombstones, or delete webhooks.
• Use full refresh only if the provider cannot return changes, deletions, or resume state, or if the dataset is tiny.
• For full refresh, cite the exact provider limitation from docs or payloads. "It is easier" is not enough.
• deleteRecordsFromPreviousExecutions() is deprecated. For full refresh, call trackDeletesStart() before fetch/save and trackDeletesEnd() only after a successful full fetch/save.
• Never combine trackDeletesStart() / trackDeletesEnd() with changed-only checkpoints (modified_after, updated_after, changed-records endpoints, etc.). They omit unchanged rows, so trackDeletesEnd() would delete them.
• Checkpointed full refreshes are still full refreshes. Call trackDeletesEnd() only in the run that finishes the full window.

Conventions

• Match field casing to the external API. Passthrough fields keep provider casing; non-passthrough fields should use the majority casing of that API.
• Prefer explicit field names.
• Add .describe() examples for IDs, timestamps, enums, and URLs.
• Avoid any; use inline mapping types.
• Prefer static Nango endpoint paths (avoid :id / {id} in the exposed endpoint); pass IDs in input/params.
• List actions should expose cursor plus a next-cursor field in the majority casing of that API (next_cursor, nextCursor, etc.).
• Use nango.zodValidateInput() only when you need custom validation or logging; otherwise rely on schemas + nango dryrun --validate.

Schema Semantics

• Default non-required inputs to .optional().
• Use .nullable() only when null has meaning, usually clear-on-update; add .optional() when callers may omit the field too.
• Raw provider schemas should match the provider: .optional() for omitted fields, .nullable() for explicit null, .nullish() only when the provider truly does both.
• Final action outputs and normalized sync models should prefer .optional() and normalize upstream null to omission unless null matters.
• Default generated schemas to .optional() for non-required inputs and normalized outputs; widen only when the upstream contract justifies it.
• Prefer .nullable() over z.union([z.null(), T]) or z.union([T, z.null()]).
• Return null only when the output schema allows it.
• z.object() strips unknown keys by default. For provider pass-through use z.object({}).passthrough(), z.record(z.unknown()), or z.unknown() with minimal refinements.

Field Naming and Casing Rules

• Use explicit suffixes in the API's majority casing: IDs (user_id, userId), names (channel_name, channelName), emails (user_email, userEmail), URLs (callback_url, callbackUrl), and timestamps (created_at, createdAt).

Mapping example (API expects a different parameter name):

const InputSchema = z.object({
    userId: z.string()
});

const config: ProxyConfiguration = {
    endpoint: 'users.info',
    params: {
        user: input.userId
    },
    retries: 3
};

If the API is snake_case, use user_id instead. The goal is API consistency.

Dryrun, Mocks, and Tests (required)

Required loop (do not skip steps):

1. Run nango dryrun ... --validate -e dev --no-interactive --auto-confirm until it passes.
2. Actions: always pass --input '{...}' (use --input '{}' for no-input actions).
3. Syncs: use --checkpoint '{...}' when you need to simulate a resumed run.
4. If validation cannot pass, stop and state the missing external state or inputs required.
5. After validation passes, run nango dryrun ... --save -e dev --no-interactive --auto-confirm to generate <script-name>.test.json.
6. Run nango generate:tests, then npm test.

Hard rules:

• Treat <script-name>.test.json as generated output. Never create, edit, rename, or move it (including recorded hash fields).
• If mocks are wrong or stale, fix the code and re-record with --save.
• Do not hard-code error payloads in *.test.json; use a Vitest test with vi.spyOn(...) for 404/401/429/timeout cases.
• Connection ID is the second positional argument; do not use --connection-id.
• Use --integration-id <integration-id> when script names overlap across integrations.
• Prefer --checkpoint for new incremental syncs; --lastSyncDate is a legacy pattern.
• If nango is not on PATH, use npx nango ....
• CLI upgrade prompts can block automation; set NANGO_CLI_UPGRADE_MODE=ignore if needed.

Reference: https://nango.dev/docs/implementation-guides/platform/functions/testing

References

• Action patterns, CRUD examples, metadata usage, and ActionError examples: references/actions.md
• Sync patterns, concrete checkpoint examples, delete strategies, and full refresh fallback: references/syncs.md

Useful Nango docs (quick links)

• Functions runtime SDK reference: https://nango.dev/docs/reference/functions
• Implement an action: https://nango.dev/docs/implementation-guides/use-cases/actions/implement-an-action
• Implement a sync: https://nango.dev/docs/implementation-guides/use-cases/syncs/implement-a-sync
• Checkpoints: https://nango.dev/docs/implementation-guides/use-cases/syncs/checkpoints
• Deletion detection (full vs incremental): https://nango.dev/docs/implementation-guides/use-cases/syncs/deletion-detection
• Testing integrations (dryrun, --save, Vitest): https://nango.dev/docs/implementation-guides/platform/functions/testing
• Nango HTTP API reference: https://nango.dev/docs/reference/api

Deploy (Optional)

Deploy functions to an environment in your Nango account:

nango deploy dev

# Deploy only one function
nango deploy --action <action-name> dev
nango deploy --sync <sync-name> dev

Reference: https://nango.dev/docs/implementation-guides/use-cases/actions/implement-an-action

When API Docs Do Not Render

If web fetching returns incomplete docs (JS-rendered):

• Ask the user for a sample response
• Use existing actions/syncs in the repo as a pattern
• Run dryrun with --validate until it passes, then run dryrun with --save, then nango generate:tests

Final Checklists

Action:

• Nango root verified
• references/actions.md was used for the action pattern
• Schemas and types are clear, and missing-value rules match the provider vs normalized contract
• createAction() includes endpoint, input, output, and scopes when required
• Fields use passthrough casing or the API's majority casing
• Provider call includes an API doc link comment and intentional retries
• nango.ActionError is used for expected failures
• Registered in index.ts
• Dryrun succeeds with --validate -e dev --no-interactive --auto-confirm --input '{...}'
• <action-name>.test.json was generated by nango dryrun ... --save after --validate
• nango generate:tests ran and npm test passes

Sync:

• Nango root verified
• references/syncs.md was used for the sync pattern
• Models map is defined, ids are stable strings, and normalized models prefer .optional() unless null matters
• Incremental was chosen first, with a checkpoint schema unless full refresh is explicitly justified from docs or payloads
• nango.getCheckpoint() is read at the start and nango.saveCheckpoint() runs after each page or batch
• Checkpoint data changes the provider request or resume state (since, updated_after, cursor, page_token, offset, page, since_id, etc.)
• Changed-only checkpoint syncs (modified_after, updated_after, changed-records endpoint) do not use trackDeletesStart() / trackDeletesEnd()
• If checkpoints were not used, the response explains exactly why no viable checkpoint strategy exists
• Raw provider schemas model omitted vs null correctly, and fields use passthrough casing or the API's majority casing
• nango.paginate() is used unless the API truly cannot fit Nango's paginator
• Deletion strategy matches the sync type: batchDelete() for incremental only when the provider returns explicit deletions; otherwise full-refresh fallback uses trackDeletesStart() before fetch/save and trackDeletesEnd() only after a successful full fetch plus save
• Metadata handled if required
• Registered in index.ts
• Dryrun succeeds with --validate -e dev --no-interactive --auto-confirm
• <sync-name>.test.json was generated by nango dryrun ... --save after --validate
• nango generate:tests ran and npm test passes

Weekly Installs

107

Repository

nangohq/skills

First Seen

Feb 12, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykWarn

Installed on

opencode106

codex105

gemini-cli104

kimi-cli104

github-copilot104

amp104