Using AI assistants with the Video SDK

Video SDK packages include docs and files that you can use to get accurate coding assistance from AI assistants such as Cursor, Claude Code, and Codex. The native SDK packages include an AI-friendly Docs/ folder starting with version 2.5.7, and the Video SDK for Web includes an agent skill and JSON type definitions starting with version 2.5.0.

Note

This is available in the Android, iOS, Linux, macOS, and Windows SDK packages starting with version 2.5.7, and in the Video SDK for Web starting with version 2.5.0.

Video SDK for Android, iOS, Linux, macOS, and Windows

The native SDK packages ship the AI-friendly documentation inside the package itself, so you point your AI assistant at the files you already downloaded.

Video SDK version differences

Starting with Video SDK version 2.6.0 the *-API.md files are removed and only the *-API.json files are included. Keep your Video SDK version in mind when reviewing this documentation.

What's included

The Docs/ folder is located at the root of the SDK package and includes everything you need to provide context to your AI assistant.

  • index.md - Entry point and module map
  • *-API.md - Human-readable API explanations including lifecycle, behavior, and edge cases
  • *-API.json - Structured API metadata including signatures, params, async flags, and snippets/examples
  • skills/.../SKILL.md - Skill definition to teach the assistant how to navigate these docs

How to use these files

  1. Open Docs/index.md or Docs/videosdk/index.md (the path varies by package).
  2. Identify the API module you want to use.
  3. Read both files for the API module.
    • xxx-API.md for semantics and constraints.
    • xxx-API.json for exact signatures, fields, examples, etc.
  4. Prompt your AI assistant with explicit context.
    • "Use Docs/zoom_video_sdk_share_helper_interface-API.md and matching JSON only and then cross-check async behavior in JSON before suggesting code."

Best practices for using each file type

Each of the file types serve specific uses that work in tandem.

Markdown

  • Lifecycle and callback order
  • Usage notes and warnings
  • Conceptual behavior

JSON

  • Exact method signatures
  • Parameter names/types
  • Structured examples and async indicators

Always validate implementation details with JSON if there is any mismatch.

Prompt templates

These prompt templates will help you get started using the files with your AI assistant.

  • "Use only Docs/ docs for this answer. Prefer JSON for signatures and async behavior."
  • "Compare xxx-API.md and xxx-API.json and list any differences."
  • "Generate code using API names exactly as documented in JSON."

Using the built-in skill

The package includes a skill, for example zm-videosdk-ios-api/SKILL.md.

  1. Copy or symlink the skill folder into the skills directory for your assistant. Use the project path to scope the skill to a single project, or the home directory path to make it available in all of your projects.
    • Cursor - .cursor/skills/ or ~/.cursor/skills/
    • Claude Code - .claude/skills/ or ~/.claude/skills/
    • Codex - .agents/skills/ or ~/.agents/skills/
  2. Verify relative links inside SKILL.md still resolve after moving.
  3. Restart or reload your assistant if needed.

Common mistakes

There are a few mistakes that cause the AI assistant to not act as expected, but they can easily be avoided.

  • Assuming Windows/macOS behavior for Linux APIs without checking package scope notes.
  • Not referencing the Docs/ folder at all, which causes the AI assistant to fall back on general knowledge and possibly hallucinate API names or signatures.
  • Relying on only one file type instead of using .md and .json together. Each covers different details that the other doesn't.
  • Forgetting to reload your assistant after adding the skill, which can cause the skill to not be recognized.
  • Moving the skill folder without verifying that relative links inside SKILL.md still resolve correctly.

Video SDK for Web

Starting with version 2.5.0, the @zoom/videosdk NPM package includes an agent skill under the skill folder and a set of JSON type definitions written for AI coding tools. Instead of copying files by hand, you install the skill with the CLI that ships in the package.

Install the agent skill

After you install @zoom/videosdk, run the installer to add the skill to your project.

npx @zoom/videosdk install-skill

By default the installer detects an existing .cursor, .claude, or .agents directory in your project and installs the skill for that tool, falling back to Cursor if it finds none. Use --target to choose one or more tools explicitly, and --global to install the skill in your home directory so it applies to all of your projects.

npx @zoom/videosdk install-skill --target cursor   # or claude | codex | all
npx @zoom/videosdk install-skill --global          # install for all your projects

The installer writes the skill to a tool-specific folder.

  • Cursor - .cursor/skills/video-sdk-web/
  • Claude Code - .claude/skills/video-sdk-web/
  • Codex - .agents/skills/video-sdk-web/

With --global, the installer writes to the same paths under your home directory. Restart or reload your editor after installing so it picks up the new skill.

What the skill includes

The skill gives your AI assistant task-focused guidance for building and debugging a Video SDK for Web application.

  • SKILL.md - Skill definition that tells the assistant when and how to use the reference material
  • references/ - Guidance for core flows such as authentication, sessions, and events, along with audio, video, screen share, chat, recording, transcription, framework integration, browser support, and error codes
  • troubleshooting/ - Common issues and their solutions, error code mapping, and how to report quality data to Zoom

Type definitions for AI coding

The package ships two forms of type definitions, and each has a different audience.

  • .json files in dist/types-json - Structured type definitions intended for AI coding tools. Files are split by feature area, such as videoclient.json, media.json, chat.json, subsession.json, and event-callback.json, with index.json as the entry point.
  • .d.ts files in dist/types - The TypeScript declarations, retained for human developers and traditional reference tooling such as editor autocomplete and type checking.

Both describe the same API. Point your AI assistant at the JSON files when you want exact signatures, parameter names, and event payloads, and keep using the .d.ts files in your own editor as usual.

Best practices

Here are some best practices to keep the assistant's output accurate.

  • Ask the assistant to use the installed skill and the JSON types rather than its general knowledge of the Video SDK.
  • Prefer dist/types-json over .d.ts when the assistant needs exact method signatures or event payload shapes.
  • Reinstall the skill after you upgrade @zoom/videosdk so the guidance matches your SDK version.
  • Keep the scope clear. This skill covers the Video SDK for Web and not embedded Zoom Meetings or Webinars, which use the Meeting SDK.