Truto Agent Skills: Stop AI Hallucinations When Building Integrations

If you are looking for AI agent skills for integrations, stop trying to out-prompt a generic model. The reliable fix is to give the assistant vendor-specific context before it writes code. Your AI coding assistant has no idea how Truto actually works under the hood. It will confidently generate API calls to endpoints that don't exist, fabricate authentication flows, and invent pagination parameters.

This isn't a bug in the AI - it's a context problem. The model's training data is inherently stale, generic, or both when it comes to specific platforms. Agent Skills solve this by injecting accurate, structured knowledge directly into your AI's context so it writes correct integration code on the first try.

Truto Skills packages Truto's unified API, proxy API, CLI, Link SDK, JSONata mapping patterns, and API conventions into a public SKILL.md-compatible repository for Cursor, Claude Code, and other compatible agents. This post covers what Agent Skills are, how to install the official Truto skills, and why a declarative integration platform is the perfect match for AI-assisted development.

The Hallucination Problem in API Integrations

AI coding tools are now standard kit, not a toy. The 2025 Stack Overflow Developer Survey (n = 49,000+) revealed that AI tool usage in developer workflows has climbed to 80%. However, that same survey found that 66% of developers say their biggest frustration with AI tools is solutions that are "almost right, but not quite," and only 29% of developers trust AI outputs to be completely accurate.

Faster code is easy. Correct integration code is the part that still hurts. A CodeRabbit analysis of 470 open-source pull requests from December 2025 found roughly 1.7x more issues in AI-coauthored pull requests compared to human-only PRs when the AI lacks proper domain context.

Integration hallucination is code that looks plausible but is wrong for the actual API contract you are calling. Ask Claude Code or Cursor to "build a Truto integration that syncs HubSpot contacts" without any additional context, and you'll get something that looks right but is wrong in subtle, time-wasting ways.

What this looks like in practice:

• It guesses that the base URL is https://api.truto.io (it's actually https://api.truto.one).
• It invents a /v2/contacts endpoint when the actual path is /unified/crm/contacts.
• It writes page or offset loops where the caller should use next_cursor.
• It assumes the platform will magically absorb HTTP 429 rate limit errors.
• It drops provider-specific write fields that should be passed through the remote_data object.
• It mixes Truto Unified API assumptions with raw provider fields.

These are not abstract problems. Every SaaS platform has its own quirks: different auth flows, non-standard error codes, unique pagination schemes, and undocumented rate limit behaviors. An AI model trained on generic web data doesn't know that Salesforce returns PascalCase field names while HubSpot nests everything under a properties object.

When building integrations manually, engineers spend hours reading vendor documentation to figure out these edge cases. When an AI agent writes the code, it skips the reading phase and goes straight to hallucinating. Prompting harder is not a strategy. When the API rules are specific and changing, long chats without structured context usually just produce more confident nonsense.

What Are Agent Skills (SKILL.md)?

Agent Skills are portable, version-controlled packages of instructions that teach AI coding assistants how to perform domain-specific tasks correctly.

The format was created by Anthropic in October 2025 and released as an open standard on December 18, 2025. It has since been adopted by Claude Code, Cursor, GitHub Copilot, OpenAI Codex CLI, Databricks, and others. Rather than dumping a 50-page API specification into your prompt window - which burns through your context window and degrades the model's instruction-following capabilities - Agent Skills use progressive disclosure.

At its core, a skill is a folder containing a SKILL.md file with YAML frontmatter (name and description) and Markdown instructions:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

The three-level loading system keeps token usage incredibly lean:

1. Metadata only - At startup, the agent reads just the name and description of every installed skill (~50-100 tokens each). This is enough for the AI to know when to activate each skill.
2. Full instructions - When the AI decides a skill is relevant to the current task, it loads the complete SKILL.md into context.
3. Reference files - Scripts, docs, and templates load only if the instructions explicitly reference them.

This means you can install dozens of skills without bloating every prompt. The pattern is catching on fast. Pulumi released Agent Skills to teach AI assistants infrastructure-as-code best practices. Auth0 published skills covering 20+ framework-specific implementations. Databricks provides skills for their apps, notebooks, and ML workflows. The market has already voted: if your product has tricky conventions, a generic coding assistant is not enough.

Introducing Truto Skills

Truto Skills is Truto's official skills repository for teaching coding assistants how to build against Truto without guessing. The official repository packages everything an AI coding assistant needs to build integrations on Truto correctly.

The repository includes five main capabilities:

That coverage matters because Truto is not just one API. It is a unified API platform with 200+ third-party tools and multiple surfaces: Unified APIs, Proxy APIs, Sync Jobs, Webhooks, Custom APIs, MCP servers, CLI workflows, and frontend connection flows. If the assistant only knows one slice, it will keep reaching for the wrong tool.

How to Install Truto Skills in Cursor and Claude Code

Getting your AI assistant equipped with Truto skills takes less than a minute. The fastest path depends on your environment.

Claude Code

If you are using Anthropic's Claude Code CLI, add the Truto skills repository as a plugin marketplace and install it directly. Anthropic's plugin docs support adding marketplaces from GitHub repos:

/plugin marketplace add trutohq/truto-skills
/plugin install truto@truto-skills

The skills will be automatically namespaced in your environment (e.g., truto:truto-api-conventions, truto:truto-jsonata) so they do not collide with local project skills.

Cursor

Cursor supports fetching remote rules directly from GitHub repositories. This ensures your AI always has the latest API conventions without you needing to manually update local markdown files.

1. Open Cursor Settings.
2. Navigate to Rules.
3. Click Add Rule under the Project Rules section.
4. Select Remote Rule (GitHub).
5. Enter the repository URL: https://github.com/trutohq/truto-skills

This automatically pulls in the skills and applies the truto-api rule to your project. Cursor keeps the rules synced with the source repository, so updates are reflected automatically.

Any Agent (via npx skills)

For other compatible AI agents, or if you want a tool-agnostic path, you can use the open-source Skills CLI to install the skills locally into your project directory:

npx skills add trutohq/truto-skills

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.