ivy-interactive/ivy-framework/ivy-create-any-connection

ivy-create-any-connection

Create a connection to an external API or service inside an existing Ivy project. This produces connection files under Connections/[ConnectionName]/ -- it does NOT create a separate project or catalog entry. Only use this skill when the user wants to connect to an API or service that does not already have a pre-built reference connection in the Ivy catalog.

Pre-flight: Read Learnings

If the file .ivy/learnings/ivy-create-any-connection.md exists in the project directory, read it first and apply any lessons learned from previous runs of this skill.

Reference Files

Read before implementing:

• references/AGENTS.md -- Ivy framework API reference (widgets, hooks, layouts, inputs, colors)

Step 1: Validate the Project

1. Verify this is a valid Ivy project. Check for a .csproj file and Program.cs in the working directory. If this is not an Ivy project, tell the user and stop.

1. LLM endpoint detection: If the user's request mentions an OpenAI-compatible LLM endpoint (URL contains openai, litellm, chat/completions, or v1; or keywords like "OpenAI-compatible", "LLM proxy", "chat completions"), do NOT create an ad-hoc connection. Instead, tell the user to use the OpenAI reference connection, which already supports custom endpoints via the OpenAI:Endpoint secret. Stop and suggest using the /ivy-create-using-reference-connection skill with "OpenAI" as the provider.

Step 2: Clarify the Target API

1. Is it clear what API or service the connection is for? If not, ask the user to clarify. Ask for a link to the API documentation or the name of the service. Some services have multiple APIs (e.g. Stripe has payments, billing, customers). If so, clarify which API and reflect this in the connection name.

1. Determine a name for the connection. This is usually the service name in PascalCase, like "Stripe" or "GitHub". Ask the user to confirm the name.

1. Create the connection directory using the pattern Connections/[ConnectionName]/ inside the user's project directory.

Expected directory structure after this skill completes:

[UserProject]/
├── [UserProject].csproj
├── Program.cs
├── Connections/
│   └── [ConnectionName]/
│       ├── [ConnectionName]Connection.cs
│       ├── [ConnectionName]ConnectionTests.cs
│       └── (OpenAPI only: ClientFactory, .refitter, Refresh.ps1, generated client)
│       └── (Custom only: [ConnectionName]Client.cs)
└── Apps/
    └── [ConnectionName]App.cs

Step 3: Choose an Approach

1. Try to find a good NuGet package that implements the API.

GOOD indicators:

• Lots of downloads
• Recently updated
• Permissive license (MIT, Apache-2.0, BSD, ISC, etc.)
• Good documentation
• Official, created by the service itself

BAD indicators:

• Few downloads
• Not updated in a long time
• Restrictive license (GPL, etc.)
• No documentation
• Not official, created by a third party

Notes:

• For anything related to LLM model inference, prefer packages that provide an IChatClient adapter via Microsoft.Extensions.AI. It is fine to also register the provider-specific client (e.g. AnthropicClient) -- but always register IChatClient as well if possible, since it gives a unified chat interface across all LLM connections.

Given these parameters, present the user a list of potential NuGets. The strategy for choosing the connection approach (in priority order):

1. NuGet package -- if a good NuGet exists, proceed to the "NuGet Approach" section
2. OpenAPI/Swagger spec -- if no good NuGet exists but the API has an official OpenAPI spec, use Refitter to generate a typed client. Proceed to the "OpenAPI / Refitter Approach" section
3. Custom client -- as a last resort, if there is no NuGet and no OpenAPI spec, generate a custom HTTP client from the API documentation. Proceed to the "Custom HTTP Client Approach" section

Consult with the user on which approach to take if not clear.

NuGet Approach

Add the NuGet package

1. Add the selected NuGet package(s) to the project using the dotnet CLI:

dotnet add package [PackageName]

Create the Connection class

1. Create Connections/[ConnectionName]/[ConnectionName]Connection.cs implementing IConnection and IHaveSecrets.

The connection class must follow this pattern:

using Ivy;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
 
namespace [ProjectNamespace].Connections.[ConnectionName];
 
public class [ConnectionName]Connection : IConnection, IHaveSecrets
{
    public string GetContext(string connectionPath) => """
        # [ConnectionName] Connection
 
        ## Getting the service
 
        ```csharp
        var client = UseService<[ServiceType]>();
        ```
 
        ## Common Usage
 
        // Include 2-3 of the most common usage examples with code snippets
        // Show how to call the most important methods
        // Include information about response types and error handling
        """;
 
    public string GetNamespace() => typeof([ConnectionName]Connection).Namespace!;
 
    public string GetName() => "[ConnectionName]";
 
    public string GetConnectionType() => "Nuget:[PackageId]";
 
    public ConnectionEntity[] GetEntities() =>
    [
        // List the main entities this API exposes
        // e.g. new("Message", "Messages"),
    ];
 
    public void RegisterServices(Server server)
    {
        server.Services.AddSingleton(sp =>
        {
            var config = sp.GetRequiredService<IConfiguration>();
            var apiKey = config["[ConnectionName]:ApiKey"] ?? "";
            // Create and return the API client
        });
 
        // For LLM connections, also register IChatClient:
        // server.Services.AddSingleton<IChatClient>(sp => { ... });
    }
 
    public async Task<(bool ok, string? message)> TestConnection(IConfiguration config)
    {
        try
        {
            var apiKey = config["[ConnectionName]:ApiKey"];
            if (string.IsNullOrEmpty(apiKey))
                return (false, "[ConnectionName]:ApiKey is not configured. Please set your API key in user secrets.");
 
            // Create a client and call a lightweight read-only endpoint
            return (true, "Connected successfully.");
        }
        catch (Exception ex)
        {
            return (false, $"Connection test failed: {ex.Message}");
        }
    }
 
    public Secret[] GetSecrets() => [new Secret("[ConnectionName]:ApiKey")];
    // If the user provided a value, use: new Secret("[ConnectionName]:ApiKey", "user-provided-value")
}

• Some connections need multiple secrets. Use appropriate names.

Set up secrets

1. Determine what secrets are needed to connect to the API. For example: API key, bearer token, client ID/secret, endpoint URL, etc. Ask the user what credentials the API requires if not clear from documentation.

1. Initialize user secrets for the project (idempotent if already initialized):

dotnet user-secrets init

Note: If the user provided specific credential values in their prompt (API keys, tokens, endpoints), set them as Preset values in GetSecrets(): new Secret("Key", "user-provided-value"). This ensures the connection works immediately without manual secret configuration.

1. Make sure the connection class's GetSecrets() method returns all secret keys, and RegisterServices() reads them from IConfiguration.

After completing the NuGet approach, proceed to the Verification section.

OpenAPI / Refitter Approach

No suitable NuGet package was found, but the API has an official OpenAPI/Swagger specification. Use Refitter to generate a strongly-typed C# client from the spec.

Find the OpenAPI spec

1. Search for the official OpenAPI/Swagger spec URL for the API. Common locations:

• https://api.example.com/openapi.json
• https://api.example.com/swagger.json
• https://api.example.com/v1/openapi.yaml
• The API documentation site often links to it
• GitHub repositories may contain the spec file

Validate that the URL returns a valid OpenAPI 2.0/3.0/3.1 spec (JSON or YAML). Ask the user to confirm the spec URL.

Determine authentication

1. What authentication scheme does the API use?

• Bearer token (Authorization: Bearer <token>) -- most common for modern APIs
• API key header (e.g. X-Api-Key: <key>) -- common for simpler APIs

Note the auth scheme type (bearer or apikey) and the header name (e.g. Authorization or X-Api-Key).

Set up secrets

1. Initialize user secrets for the project (idempotent if already initialized):

dotnet user-secrets init

Note: If the user provided specific credential values in their prompt (API keys, tokens, endpoints), set them as Preset values in GetSecrets(): new Secret("Key", "user-provided-value"). This ensures the connection works immediately without manual secret configuration.

Install Refitter and Refit

1. Ensure the Refitter dotnet tool is installed globally:

dotnet tool install --global refitter

1. Add the Refit NuGet package to the project:

dotnet add package Refit

Create the .refitter configuration

1. Create the file Connections/[ConnectionName]/[ConnectionName].refitter with smart defaults:

{
    "openApiPath": "<OpenAPI spec URL>",
    "namespace": "[ProjectNamespace].Connections.[ConnectionName]",
    "outputFilename": "<absolute path to Connections/[ConnectionName]/[ConnectionName]Client.cs>",
    "naming": {
        "useOpenApiTitle": false,
        "interfaceName": "[ConnectionName]Client"
    },
    "immutableRecords": false,
    "operationNameGenerator": "SingleClientFromPathSegments",
    "optionalParameters": true,
    "addAutoGeneratedHeader": false,
    "generateXmlDocCodeComments": false,
    "generateStatusCodeComments": false,
    "codeGeneratorSettings": {
        "generateOptionalPropertiesAsNullable": true,
        "generateNullableReferenceTypes": true
    }
}

Key settings explained:

• operationNameGenerator: "SingleClientFromPathSegments" -- generates a single interface with method names derived from URL path segments instead of operationIds (cleaner names)
• optionalParameters: true -- optional query params become C# optional parameters with defaults
• immutableRecords: false -- generates mutable classes (safer for serialization)
• generateNullableReferenceTypes: true -- respects nullable reference types
• interfaceName -- omits the I prefix; Refitter adds it automatically, producing I[ConnectionName]Client

Generate the client

1. Run refitter to generate the C# client from the OpenAPI spec:

refitter --settings-file "Connections/[ConnectionName]/[ConnectionName].refitter" --skip-validation --no-banner

This generates [ConnectionName]Client.cs containing the I[ConnectionName]Client Refit interface with all API methods.

1. Verify the generated file exists and contains the expected interface. If generation fails, check that:

• The OpenAPI spec URL is accessible
• The spec is valid (the --skip-validation flag is already used)
• The output path is correct

Create Refresh.ps1

1. Create Connections/[ConnectionName]/Refresh.ps1 so the client can be regenerated when the API spec changes:

# Regenerates the [ConnectionName] API client from the OpenAPI spec.
# Run this script when the API spec has been updated.
#
# Prerequisites: dotnet tool install --global refitter
 
$ErrorActionPreference = "Stop"
$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
$settingsFile = Join-Path $scriptDir "[ConnectionName].refitter"
 
Write-Host "Regenerating [ConnectionName] client from OpenAPI spec..." -ForegroundColor Cyan
refitter --settings-file $settingsFile --skip-validation --no-banner