> ## Documentation Index
> Fetch the complete documentation index at: https://docs.versori.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tips & Best Practices

> Get the most out of AI-assisted integration development with the Versori skill.

## Prepare a research document

The skill works best when your AI tool has a clear understanding of the systems and requirements involved. Before starting, gather:

* **API documentation links** for each system you want to integrate
* **Authentication details** — which auth method each system uses (API key, OAuth 2.0, etc.)
* **Data models** — the objects and fields you need to map between systems
* **Example payloads** — sample API requests and responses help the agent generate accurate transformations
* **Trigger requirements** — whether the integration should run on webhook events, a schedule, or manually

> [!TIP]
>
> Start your prompt with a research document or a detailed description of the integration. The more context you
> provide upfront, the fewer iterations you will need.

## Write effective prompts

Be specific about what you want to build. A good prompt includes:

* **The systems involved** — name the source and target platforms
* **The trigger type** — webhook, schedule (with cron expression), or manual
* **Field mappings** — which fields in the source map to which fields in the target
* **Authentication methods** — how each system should authenticate
* **Edge cases** — what should happen when records already exist, when fields are missing, or when API calls fail

**Good prompt:**

```
Build an integration between HubSpot and Salesforce.
When a new contact is created in HubSpot (webhook), check if they exist in Salesforce by email.
If they exist, update the record. If not, create a new lead.
Use OAuth 2.0 for both systems.
Map: HubSpot firstname → Salesforce FirstName, HubSpot lastname → Salesforce LastName,
HubSpot email → Salesforce Email, HubSpot company → Salesforce Company.
```

**Vague prompt:**

```
Sync contacts between HubSpot and Salesforce.
```

The vague prompt will still work, but the agent will need to make assumptions about trigger type, field mappings, and authentication — leading to more back-and-forth.

## SDK patterns the skill uses

The skill generates code using the Versori Run SDK. Understanding these patterns helps you review and refine the generated workflows:

* **[Workflows & triggers](https://docs.versori.com/latest/run-sdk/latest/workflows.md)** — webhook and schedule-based entry points for integrations
* **[Task types](https://docs.versori.com/latest/run-sdk/latest/workflows/task-types.md)** — the building blocks of workflows: functions, HTTP calls, and more
* **[Context & KV storage](https://docs.versori.com/latest/run-sdk/latest/context.md)** — how workflows access connections, logging, and persistent state
* **[Durable workflows](https://docs.versori.com/latest/run-sdk/latest/durable-workflows.md)** — long-running workflows with persistent state across executions

## Common integration patterns

The skill handles a variety of integration patterns. These guides cover common use cases in detail:

* [Real-time integrations](https://docs.versori.com/latest/guides/use-cases/real-time.md) — event-driven workflows triggered by webhooks
* [Batch integrations](https://docs.versori.com/latest/guides/use-cases/batch.md) — scheduled data synchronisation between systems
* [Bidirectional sync](https://docs.versori.com/latest/guides/use-cases/bidirectional.md) — two-way data flow between systems
* [Multi-tenancy](https://docs.versori.com/latest/guides/use-cases/multi-tenancy.md) — integrations that support multiple end users

> [!WARNING]
>
> Always review generated code before deploying to production. While the skill follows best practices and
> generates tested code, you should verify that field mappings, authentication configuration, and error handling
> meet your specific requirements.

## Troubleshooting

If the skill is not activating or behaving as expected:

* **Check the CLI is authenticated** — run `versori context list` to verify you have an active context
* **Ensure a project exists** — the agent will guide you through creating one, but you can also create one manually with `versori projects create`
* **Check your prompt** — the skill activates on integration-related tasks. If your request is about something unrelated, it will not engage
* **Make sure the skill is installed** — confirm it is in your tool's skill directory, or re-run `versori skills download --latest` to get the latest version


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.