add-tools
Create tool configurations for a Sim integration by reading API docs
simstudioai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add simstudioai/sim --skill add-tools技能说明
name: add-tools description: Create tool configurations for a Sim integration by reading API docs argument-hint: [api-docs-url]
Add Tools Skill
You are an expert at creating tool configurations for Sim integrations. Your job is to read API documentation and create properly structured tool files.
Your Task
When the user asks you to create tools for a service:
- Use Context7 or WebFetch to read the service's API documentation
- Create the tools directory structure
- Generate properly typed tool configurations
Hard Rule: No Guessed Response Schemas
If the docs do not clearly show the response JSON for a tool, you MUST tell the user exactly which outputs are unknown and stop short of guessing.
- Do NOT invent response field names
- Do NOT infer nested paths from nearby endpoints
- Do NOT guess array item shapes
- Do NOT write
transformResponseagainst unverified payloads
If the response shape is unknown, do one of these instead:
- Ask the user for sample responses
- Ask the user for test credentials so you can verify live responses
- Implement only the endpoints whose outputs are documented
- Leave the tool unimplemented and explicitly say why
Directory Structure
Create files in apps/sim/tools/{service}/:
tools/{service}/
├── index.ts # Barrel export
├── types.ts # Parameter & response types
└── {action}.ts # Individual tool files (one per operation)
Tool Configuration Structure
Choose the execution boundary first
Every tool must use exactly one of these configurations:
- In-process operation (preferred): use
InternalToolConfigwhen the executor and the implementation run in the same Sim process/trust/runtime plane. Materialize typedoperation.input, implement the handler underapps/sim/lib/internal/{service}/execute-tool.ts, and register every tool ID inapps/sim/lib/internal/tool-operations/registry.server.ts. - External provider request: use
ToolConfig.requestonly when the URL is an absolute external HTTP(S) provider endpoint.
Never set a tool URL to /api/..., construct an absolute URL back to Sim, declare
request.internal, add a directExecution property (it fails bun run check:tool-request-boundary), import a route module, or create an API route merely to normalize files,
authorize access, or reuse server code. A real browser/API route may remain as a thin adapter, but
the route and the tool must call the same operation directly. A true cross-process/capability
boundary uses an explicit server client and is not disguised as a tool self-hop.
For protected Sim resources, the internal handler calls the domain's authorized application use
case with trusted execution context; use the migrate-application-operation skill.
External provider request
Use this structure only for an absolute external provider API:
import type { {ServiceName}{Action}Params } from '@/tools/{service}/types'
import type { ToolConfig } from '@/tools/types'
interface {ServiceName}{Action}Response {
success: boolean
output: {
// Define output structure here
}
}
export const {serviceName}{Action}Tool: ToolConfig<
{ServiceName}{Action}Params,
{ServiceName}{Action}Response
> = {
id: '{service}_{action}', // snake_case, matches tool name
name: '{Service} {Action}', // Human readable
description: 'Brief description', // One sentence
version: '1.0.0',
// OAuth config (if service uses OAuth)
oauth: {
required: true,
provider: '{service}', // Must match OAuth provider ID
},
params: {
// Hidden params (system-injected, e.g. the OAuth accessToken)
accessToken: {
type: 'string',
required: true,
visibility: 'hidden',
description: 'OAuth access token',
},
// User-only params (credentials, api key, IDs user must provide)
someId: {
type: 'string',
required: true,
visibility: 'user-only',
description: 'The ID of the resource',
},
// User-or-LLM params (everything else, can be provided by user OR computed by LLM)
query: {
type: 'string',
required: false, // Use false for optional
visibility: 'user-or-llm',
description: 'Search query',
},
},
request: {
url: (params) => `https://api.service.com/v1/resource/${params.id}`,
method: 'POST',
headers: (params) => ({
Authorization: `Bearer ${params.accessToken}`,
'Content-Type': 'application/json',
}),
body: (params) => ({
// Request body - only for POST/PUT/PATCH
// Trim ID fields to prevent copy-paste whitespace errors:
// userId: params.userId?.trim(),
}),
},
transformResponse: async (response: Response) => {
const data = await response.json()
return {
success: true,
output: {
// Map API response to output
// Use ?? null for nullable fields
// Use ?? [] for optional arrays
},
}
},
outputs: {
// Define each output field
},
}
In-process operation
import type { InternalToolConfig } from '@/tools/types'
export const {serviceName}{Action}Tool: InternalToolConfig<
{ServiceName}{Action}Params,
{ServiceName}{Action}Response
> = {
id: '{service}_{action}',
name: '{Service} {Action}',
description: 'Brief description',
version: '1.0.0',
params: {
// Same canonical metadata as an external tool.
},
operation: {
input: (params) => ({
// Map resolved tool params into the typed semantic operation input.
}),
},
outputs: {
// Define each output field.
},
}
The registered handler accepts InternalToolOperationCall, validates request.input, uses only
trusted request.context for authority, forwards request.signal, and returns the same bounded
Response contract expected by the tool executor. It has no URL, method, request headers, fetch
fallback, or caller-controlled `_co