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:
- Research - Read the service's API documentation
- Create Tools - Build tool configurations for each API operation
- Create Block - Build the block UI configuration
- Add Icon - Add the service's brand icon
- Create Triggers (optional) - If the service supports webhooks
- Register - Register tools, block, and triggers in their registries
- Configure Deployment Availability - Wire OAuth client and service-account metadata
- Generate and Validate the Catalog - Regenerate docs/catalog artifacts and run drift checks
Step 1: Research the API
Before writing any code:
- Use Context7 to find official documentation:
mcp__context7__resolve-library-id, then fetch withmcp__context7__query-docs - Or use WebFetch to read API docs directly
- 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
transformResponseagainst unverified payload shapes
If response schemas are missing or incomplete, do one of the following before proceeding:
- Ask the user for sample responses
- Ask the user for test credentials so you can verify the live payload
- Reduce the scope to only endpoints whose response shapes are documented
- 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.operationfor same-process Sim/provider work. Put the handler underapps/sim/lib/internal/{service}/execute-tool.tsand register every ID inapps/sim/lib/internal/tool-operations/registry.server.ts. - Use
ToolConfig.requestonly 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 tokensvisibility: 'user-only'for API keys and user credentialsvisibility: 'user-or-llm'for operation parameters- Always use
?? nullfor nullable API response fields - Always use
?? []for optional array fields - Set
optional: truefor outputs that may not exist - Never output raw JSON dumps - extract meaningful fields
- When using
type: 'json'and you know the object shape, definepropertieswith the inner fields so downstream consumers know the structure. Only use baretype: '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
selectorKeymust use the unified server selector path. Apply theadd-selectorskill: add browser-safe metadata to `apps/sim/lib/selectors