Truto Agent Skills: Stop AI Hallucinations When Building Integrations

Prompting Tip: A good first prompt after install is not 'build me a Salesforce integration'. Be specific. Tell the model which Truto skill to use, which API surface you want, and which behaviors it must respect. Example: "Use truto:truto-api-conventions and truto:truto-cli to create a Node.js worker that syncs crm/contacts, paginates with next_cursor, and handles upstream rate limits in caller code."

Teaching the AI Truto API Conventions That Actually Matter

Providing an AI agent with API documentation is not just about showing it the endpoints. It is about teaching the AI the operational realities of the platform. The point of the truto-api-conventions skill is simple: kill the expensive, boring mistakes before they show up in review. Here is exactly what the AI learns.

Unified API vs Proxy API

Truto gives you two data-plane surfaces. The Unified API transforms provider data into a common schema. The Proxy API returns data in the provider's native format. The skill teaches the AI that if you are building cross-provider business logic, it should default to Unified. If you need provider-only fields or endpoints the common model does not cover, the AI should drop to Proxy APIs (/proxy/{resource}) purposefully, not by accident.

Handling Rate Limits and Retries (Caller-Managed)

This is the single most common mistake AI assistants make with Truto. They assume the platform absorbs rate limits and retries automatically behind the scenes. It doesn't.

When an upstream API returns an HTTP 429, Truto passes that error directly to the caller. What Truto does provide is normalized rate limit metadata in standardized headers per the IETF specification (ratelimit-limit, ratelimit-remaining, ratelimit-reset, and Retry-After). Your code is responsible for reading these headers and implementing retry and exponential backoff logic.

With the Truto skill loaded, the AI generates the retry logic correctly, rather than writing a naive while loop that crashes your application:

async function fetchWithBackoff(
  run: () => Promise<Response>,
  attempt = 0
): Promise<Response> {
  const res = await run();
 
  if (res.status !== 429) {
    return res;
  }
 
  const retryAfter = Number(res.headers.get('Retry-After') || 0);
  const reset = Number(res.headers.get('ratelimit-reset') || 0);
  const waitSeconds = Math.max(retryAfter, reset, Math.min(2 ** attempt, 60));
 
  await new Promise(resolve => setTimeout(resolve, waitSeconds * 1000));
  return fetchWithBackoff(run, attempt + 1);
}

Normalizing Cursor-Based Pagination

Third-party APIs use wildly different pagination strategies - offset, page numbers, cursor-based, or link headers. Truto normalizes all of these into a standard cursor-based format.

The AI learns that every list response from Truto contains a next_cursor field. It knows never to append ?page=2 to a Truto unified API call. It will write clean, predictable pagination loops that work identically whether you are pulling data from Jira, Greenhouse, or QuickBooks:

type Page<T> = { result: T[]; next_cursor?: string | null };
 
async function listAllContacts(fetchPage: (nextCursor?: string) => Promise<Page<any>>) {
  const out: any[] =[];
  let nextCursor: string | undefined;
 
  do {
    const page = await fetchPage(nextCursor);
    out.push(...page.result);
    nextCursor = page.next_cursor ?? undefined;
  } while (nextCursor);
 
  return out;
}

Unified Writes Still Need an Escape Hatch

Another easy miss is write behavior. Truto's Unified API lets you send common fields and merge provider-specific fields through the remote_data object. That is a clean compromise: keep the shared model for most of the request, but leave room for the vendor oddities every real integration eventually needs. The skill explicitly teaches the AI to use remote_data when custom provider fields are requested, preventing the model from giving up on the Unified API too early.

Writing Complex JSONata Transformations

One of Truto's most powerful features is the ability to map custom API data with JSONata. Writing complex JSONata expressions from scratch can be tedious. The truto-jsonata skill provides the AI with detailed examples of Truto's extended JSONata functions, such as $mapValues, $firstNonEmpty, and specific date formatters from the @truto/truto-jsonata package.

A response mapping that normalizes HubSpot contacts into Truto's unified schema becomes a single expression string generated effortlessly by the AI:

response.{
  "id": $string(id),
  "first_name": properties.firstname,
  "last_name": properties.lastname,
  "email": properties.email,
  "created_at": properties.createdate
}

If you prompt Cursor with: "Write a Truto mapping that takes a Salesforce response, extracts the custom Industry__c field, and maps it to company_sector, defaulting to 'Unknown' if missing," the AI will instantly generate the correct expression using the $firstNonEmpty function.

Building with the Truto CLI and Truto Skills

Writing code is only half the battle. You still need to test it, inspect the data, and manage platform resources. The truto-cli skill bridges the gap between writing integration logic and actually running it.

The Truto CLI covers the full admin API, data-plane APIs, and power-user features like bulk export and diffing (read our CLI blog post for a deep dive). Without context, an AI will guess the CLI syntax. It will invent flags like --account-id instead of the required -a, or it will try to write a custom Python script to paginate through records when a single CLI command would do the job.

With the skill loaded, the AI knows the exact command structures. You can prompt your assistant to scaffold resources directly from your terminal.

Managing Admin Resources Instead of clicking through a dashboard, tell the AI to create an integration. It knows the required fields and optimistic locking rules:

truto integrations create -b '{"name":"slack","config":{"label":"Slack","auth_type":"oauth2"} }'

Testing Data-Plane APIs When you need to verify a unified model or proxy endpoint, the AI knows how to construct the right call. It understands that unified paths contain a slash (crm/contacts) while proxy paths do not (tickets), and that the -a flag is mandatory:

truto unified crm contacts -m search -a <account-id> -b '{"query":"Jane"}'

Bulk Exports and Data Piping If you need to extract data for analysis, the AI won't write a custom pagination script. It knows the CLI has an export command that handles auto-pagination natively. It also knows to use ndjson for streaming large datasets instead of buffering everything in memory:

truto export crm/contacts -a <account-id> -o ndjson | jq '.email'

By combining the CLI with Truto Skills, your AI assistant becomes an operator, not just a code generator. It can scaffold the configuration, test the endpoints, and export the results without leaving the editor.

Why Declarative Platforms Are the Best Match for AI Agents

There's a broader point here that goes beyond Truto specifically. The platforms that benefit most from AI coding assistants are the ones where "writing code" means authoring configuration and expressions rather than imperative logic.

Consider the contrast. On a code-heavy integration platform, asking the AI to add a new CRM connector means generating hundreds of lines across multiple files - an HTTP client class, authentication handler, pagination logic, response serializers, error mappers, and tests for all of it. The surface area for hallucination is enormous.

As detailed in our guide to shipping API connectors as data operations, Truto uses zero integration-specific code. Everything is handled via declarative JSON configurations and JSONata mapping expressions. The runtime engine - which handles auth, pagination, error normalization, and everything else - is the same generic pipeline for every integration. No per-integration code to hallucinate.

This architectural choice wasn't made with AI in mind; it was made for extensibility and reliability. But it turns out that a platform designed around declarative data rather than imperative code is exactly the kind of system where AI assistants excel. The skill just needs to teach the AI the shape of the config and the JSONata expression syntax. The platform handles the rest.

Stop Fighting the AI, Start Shipping Integrations

The gap between AI coding assistant adoption and trust in their output tells a clear story: developers use these tools because the speed gains are real, but they spend too much time fixing the output. A generic coding assistant is fast but generic. A skill-equipped assistant is still not infallible, but now it knows your platform rules, your escape hatches, and the difference between a real abstraction and an invented one.

If your team is already using Cursor or Claude Code to build B2B SaaS integrations, the next step is obvious: stop pasting the same Truto docs into chat threads and install the context once. You stop fighting the AI over outdated documentation and start treating it like a senior integration engineer who has memorized the entire platform specification.