跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
安全

add-integration

Add a complete Sim integration from API docs, covering tools, block, icon, optional triggers, registrations, resolved-secret/model-input safety, and integration conventions. Use when introducing a new service under `apps/sim/tools`, `apps/sim/blocks`, and `apps/sim/triggers`.

simstudioai · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add simstudioai/sim --skill add-integration

技能说明


name: add-integration description: Add a complete Sim integration from API docs, covering tools, block, icon, optional triggers, registrations, resolved-secret/model-input safety, and integration conventions. Use when introducing a new service under apps/sim/tools, apps/sim/blocks, and apps/sim/triggers. argument-hint: [api-docs-url]

Add Integration Skill

You are an expert at adding complete integrations to Sim. This skill orchestrates the full process of adding a new service integration.

Overview

Adding an integration involves these steps in order:

  1. Research - Read the service's API documentation
  2. Create Tools - Build tool configurations for each API operation
  3. Create Block - Build the block UI configuration
  4. Add Icon - Add the service's brand icon
  5. Create Triggers (optional) - If the service supports webhooks
  6. Register - Register tools, block, and triggers in their registries
  7. Configure Deployment Availability - Wire OAuth client and service-account metadata
  8. Generate and Validate the Catalog - Regenerate docs/catalog artifacts and run drift checks

Step 1: Research the API

Before writing any code:

  1. Use Context7 to find official documentation: mcp__context7__resolve-library-id, then fetch with mcp__context7__query-docs
  2. Or use WebFetch to read API docs directly
  3. Identify:
    • Authentication method (OAuth, API Key, both)
    • Available operations (CRUD, search, etc.)
    • Required vs optional parameters
    • Response structures

Hard Rule: No Guessed Response Schemas

If the official docs do not clearly show the response JSON shape for an endpoint, you MUST stop and tell the user exactly which outputs are unknown.

  • Do NOT guess response field names
  • Do NOT infer nested JSON paths from related endpoints
  • Do NOT invent output properties just because they seem likely
  • Do NOT implement transformResponse against unverified payload shapes

If response schemas are missing or incomplete, do one of the following before proceeding:

  1. Ask the user for sample responses
  2. Ask the user for test credentials so you can verify the live payload
  3. Reduce the scope to only endpoints whose response shapes are documented
  4. Leave the tool unimplemented and explicitly report why

Step 2: Create Tools

Directory Structure

apps/sim/tools/{service}/
├── index.ts          # Barrel exports
├── types.ts          # TypeScript interfaces
├── {action1}.ts      # Tool for action 1
├── {action2}.ts      # Tool for action 2
└── ...

Key Patterns

Choose the tool boundary before writing the declaration:

  • Use InternalToolConfig.operation for same-process Sim/provider work. Put the handler under apps/sim/lib/internal/{service}/execute-tool.ts and register every ID in apps/sim/lib/internal/tool-operations/registry.server.ts.
  • Use ToolConfig.request only for an absolute external HTTP(S) provider endpoint.

Never point a tool at /api/..., construct an absolute URL back to Sim, declare request.internal, add a directExecution property (it fails bun run check:tool-request-boundary), or add an API route merely to reuse code, normalize files, or authorize resources. A real external/browser route and an in-process tool may share the same operation, but neither calls the other. Follow the full transport and handler rules in the add-tools skill.

types.ts:

import type { ToolResponse } from '@/tools/types'

export interface {Service}{Action}Params {
  accessToken: string      // For OAuth services
  // OR
  apiKey: string          // For API key services

  requiredParam: string
  optionalParam?: string
}

export interface {Service}Response extends ToolResponse {
  output: {
    // Define output structure
  }
}

Tool file pattern: an external provider API uses ToolConfig with request (absolute https:// URL, headers, body, transformResponse); same-process Sim work uses InternalToolConfig with operation. Both full templates, param visibility rules, and output typing live in .agents/skills/add-tools/SKILL.md — read it before writing the first tool.

Critical Rules

  • visibility: 'hidden' for OAuth tokens
  • visibility: 'user-only' for API keys and user credentials
  • visibility: 'user-or-llm' for operation parameters
  • Always use ?? null for nullable API response fields
  • Always use ?? [] for optional array fields
  • Set optional: true for outputs that may not exist
  • Never output raw JSON dumps - extract meaningful fields
  • When using type: 'json' and you know the object shape, define properties with the inner fields so downstream consumers know the structure. Only use bare type: 'json' when the shape is truly dynamic

Resolved Secrets at Model and Persistence Boundaries

Classify every request field (ordinary provider input / AI-consumed text / opaque model bytes / Sim-durable storage) before implementing the tool and apply the shared projection or provenance mechanism only where a concrete Sim {{...}} resolution path reaches a later model or log boundary. Full rules and the required tests are in .agents/skills/add-tools/SKILL.md → "Resolved Secrets and Provenance Boundaries".

Step 3: Create Block

File Location

apps/sim/blocks/blocks/{service}.ts

Follow .agents/skills/add-block/SKILL.md for the block structure, subBlock types, condition/dependsOn/required/mode syntax, outputs, canvasPresentation sentences, and the {Service}BlockMeta export (minimum 7 templates, plus url and skills). Every block declares canvasPresentation; bun run apps/sim/scripts/check-canvas-sentences.ts --block={service} must pass (CI runs check:canvas-sentences --require-coverage).

Two rules that are easy to get wrong when copying from existing blocks:

  • Every remote selectorKey must use the unified server selector path. Apply the add-selector skill: add browser-safe metadata to `apps/sim/lib/selectors
阅读完整来源 ↗