Skip to main content

​
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
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:
Vague prompt:
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 — webhook and schedule-based entry points for integrations
  • Task types — the building blocks of workflows: functions, HTTP calls, and more
  • Context & KV storage — how workflows access connections, logging, and persistent state
  • Durable workflows — 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:
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