Skip to main content

APIMatic SDK Skill

The apimatic-sdk skill turns your AI coding assistant into a guided SDK builder. Describe what you want, and the agent authenticates with the APIMatic CLI, scaffolds your project, configures CodeGen settings, generates the SDK, applies customizations, and publishes to a package registry or source repository, all from within Claude Code, Cursor, or Codex.

Think of it as an AI engineer for your SDK pipeline: one conversation from OpenAPI spec to published SDK.

What the skill does​

Once active, the skill walks the agent through every part of building and maintaining an APIMatic SDK:

AreaWhat the skill covers
AuthenticationBrowser-based login, API key fallback, CI-friendly auth with environment variables
Project scaffoldingFirst-time setup, src/spec/ layout, APIMATIC-META.json creation
SDK generationGenerating SDKs in C#, Java, PHP, Python, Ruby, TypeScript, and Go
CodeGen settingsApplying code branding, timeout and retry policies, HTTP configuration, serialization, documentation flags, and more via APIMATIC-META.json
Change trackingInitializing --track-changes, saving customizations with sdk save-changes, reapplying across regenerations
CustomizationAdding custom code, modifying generated files following safe merge conventions
PublishingPublishing to a package registry or source repository (GitHub) via publishing profiles

When the agent invokes this skill​

The agent automatically activates apimatic-sdk when you ask about:

  • Generating an SDK using the APIMatic CLI
  • Customizing a generated SDK or preserving customizations across regenerations
  • Running sdk save-changes or saving changes to an already-customized SDK
  • Changing a CodeGen setting such as enabling retry on timeout, setting the project name, disabling linting, or changing the timeout
  • Publishing an SDK to a package registry or GitHub using a publishing profile
  • Running sdk publish or listing publishing profiles

The skill covers only SDKs built with the @apimatic/cli toolchain.

Use the skill​

Once installed, open your project in Claude Code, Cursor, or Codex, and describe what you want. The agent picks up the skill automatically.

Example prompts​

Generating an SDK from scratch:

"I have an OpenAPI spec at ./spec.yaml. Generate a TypeScript SDK for it."

Customizing a generated SDK:

"Generate a Python SDK with change tracking so I can customize it and save my changes."

Applying a CodeGen setting:

"Enable retry on timeout in my Java SDK and set the maximum retry count to 3."

Saving existing customizations:

"I've already customized the generated TypeScript SDK. Save my changes so they reapply on the next generation."

Publishing an SDK:

"Publish my TypeScript SDK version 1.2.0 to GitHub using my publishing profile."

What happens under the hood​

For a typical first-time SDK generation, the agent:

  1. Verifies you have the APIMatic CLI installed.
  2. Runs browser-based authentication (with an API key fallback).
  3. Scaffolds the project with src/spec/ and APIMATIC-META.json if starting from scratch.
  4. Asks for the target language and any customization preferences.
  5. Applies any CodeGen settings to APIMATIC-META.json before generation.
  6. Runs apimatic sdk generate with the chosen language and flags.
  7. Surfaces the output path (for example, ./sdk/typescript).

For subsequent requests (customizing, saving changes, regenerating, or publishing), the agent edits the right configuration files and runs the appropriate CLI commands without re-asking for information you've already provided.

CodeGen settings​

The skill prefers configuration over manual file edits. Before touching any generated file, it checks whether your request maps to a CodeGen setting in APIMATIC-META.json. If a matching setting exists, it applies the change there so it survives every future regeneration automatically. Only when no applicable CodeGen setting covers your request does the agent fall back to making manual changes directly in the generated files.

Change tracking and customization​

When you need to add code that goes beyond what CodeGen settings can express, the skill uses change tracking:

  1. Generate with --track-changes to initialize an sdk-source-tree/ alongside your spec.
  2. Apply customizations to the generated SDK files
  3. Run apimatic sdk save-changes to record the delta.
  4. On every future regeneration, your saved customizations are automatically reapplied.

Publishing​

Publishing requires a publishing profile configured on the APIMatic dashboard (Dashboard > Publishing Profiles). The skill:

  1. Lists available profiles with apimatic publishing profile list so you can pick the right one.
  2. Runs apimatic sdk publish with your chosen profile ID, language, semantic version, and publish type.
  3. Shows you the publishing logs after the command finishes (https://dash.apimatic.io/publish/.../logs/...).

Troubleshooting​

Authentication fails​

Check that your APIMatic account is active and your API key is correct. If browser login doesn't work, ask the agent to use the API key fallback:

# macOS / Linux:
export APIMATIC_API_KEY=YOUR_API_KEY

# Windows PowerShell:
$env:APIMATIC_API_KEY = "YOUR_API_KEY"

SDK already exists at the destination​

If the CLI reports an existing SDK at the destination, confirm whether you want to overwrite it. The agent will re-run the command with --force once you confirm. For CI pipelines where you always want to overwrite, include --force in the generate command from the start.

save-changes fails with "change tracking not enabled"​

Change tracking wasn't enabled when the SDK was first generated. Ask the agent to regenerate with --track-changes. If you already have a customized SDK you don't want overwritten, the agent will ask for a safe destination before running generation.

Publishing stays in "queued" state for a long time​

Don't cancel or rerun the command, the queued state is normal and resolves on its own. Wait for the CLI to finish. Only take action if the CLI exits with an explicit error message.