# Agent Skill

> Install the Orshot agent skill to enhance your AI coding agent with Orshot API knowledge

- **URL**: https://orshot.com/docs/integrations/agent-skill

---

**GitHub Repository:** [https://github.com/orshot-hq/orshot-agent-skills](https://github.com/orshot-hq/orshot-agent-skills)

**skills.sh:** [https://skills.sh/orshot-hq/orshot-agent-skills/orshot](https://skills.sh/orshot-hq/orshot-agent-skills/orshot)

## Introduction

The Orshot Agent Skill gives your AI coding agent comprehensive knowledge of the Orshot API, SDKs, dynamic parameters, and integrations. Once installed, your agent can write correct Orshot API calls, use the right SDK methods, and handle errors — all without you referencing the docs manually.

Agent skills are part of the open [Agent Skills](https://skills.sh) ecosystem. They work with 30+ AI coding agents.

## Supported Agents

The skill works with all agents that support the [Agent Skills specification](https://agentskills.io/), including:

- **Cursor**
- **Claude Code**
- **GitHub Copilot**
- **Windsurf**
- **Codex**
- **Cline**
- **Roo Code**
- **Gemini CLI**
- **Amp**
- **Trae**
- **OpenCode**
- **Kilo Code**
- **Goose**
- And many more

## Installation

Install the skill using the `skills` CLI:```bash
npx skills add orshot-hq/orshot-agent-skills
```The CLI auto-detects your installed agents and configures them.

### Install for Specific Agents```bash
npx skills add orshot-hq/orshot-agent-skills -a cursor
npx skills add orshot-hq/orshot-agent-skills -a claude-code
npx skills add orshot-hq/orshot-agent-skills -a github-copilot
npx skills add orshot-hq/orshot-agent-skills -a windsurf
```### Install Globally

Install globally so the skill is available across all your projects:```bash
npx skills add orshot-hq/orshot-agent-skills -g
```### Non-Interactive Installation

For CI/CD or scripting:```bash
npx skills add orshot-hq/orshot-agent-skills -g -y -a cursor
```## What's Included

The skill covers the complete Orshot platform:

### API Endpoints

- **Render from Studio Templates** — `POST /v1/studio/render`
- **Render from Utility Templates** — `POST /v1/generate/`
- **Generate Signed URLs** — `POST /v1/signed-url/create`
- **List/Get/Delete/Duplicate Studio Templates**
- **Brand Assets API** — Upload, list, delete
- **Enterprise APIs** — Create templates, bulk create, update modifications, generate variants

### Dynamic Parameters

- **Style overrides** — `title.fontSize`, `title.color`, `logo.borderRadius`, etc.
- **AI content generation** — `.prompt` for text and image elements
- **Interactive links** — `.href` for clickable elements in PDFs
- **Video parameters** — `.trimStart`, `.trimEnd`, `.muted`, `.loop`
- **Multi-page syntax** — `page1@title`, `page2@subtitle`

### SDKs

- **Node.js** — `npm install orshot`
- **Python** — `pip install orshot`
- **PHP** — `composer require nicholasgriffintn/orshot-php`
- **Ruby** — `gem install orshot`

### Social Publishing

Publish rendered images and videos directly to 13+ social platforms via API — including Twitter/X, Instagram, LinkedIn, Pinterest, Facebook, TikTok, YouTube, Threads, Bluesky, and more. The skill covers the full `publish` API parameter with scheduling, drafts, and per-platform options.

### Developer Apps & OAuth

Build third-party integrations with OAuth 2.0. The skill covers app registration, Authorization Code flow, Device flow (for CLI/headless apps), token management, and all available permission scopes.

### White-Label Embed

Embed Orshot's template editor into your app using iframe, React SDK, or Vue SDK. The skill covers setup, per-user templates, JWT authentication, webhooks, and programmatic control via PostMessage API.

### Response Handling

- **Types:** `url`, `base64`, `binary`
- **Formats:** `png`, `webp`, `jpg`, `avif`, `pdf`, `mp4`, `webm`, `gif`
- **PDF options:** margins, page ranges, color mode (RGB/CMYK), DPI

### Error Reference

Common error codes, what they mean, and how to fix them.

### Live Documentation Access

The skill teaches your agent to fetch any Orshot documentation page as clean markdown by appending `.md` to the URL. This means your agent always has access to the latest, most detailed docs on demand — without the skill file needing to include everything.

For example, your agent can fetch `https://orshot.com/docs/api-reference.md` or `https://orshot.com/docs/publish/publish-from-api.md` for detailed reference when needed.

### Migration from Competitors

The skill includes accurate API mapping tables for migrating from other image generation platforms. Each migration guide covers authentication changes, endpoint mapping, and request format translation with side-by-side code examples.

Supported migrations:

- **[BannerBear](https://orshot.com/blog/bannerbear-api-alternative)** — array-based `modifications` → flat object
- **[Placid](https://orshot.com/blog/placid-api-alternative)** — `layers` object → flat `modifications`
- **[Creatomate](https://orshot.com/blog/creatomate-api-alternative)** — UUID template IDs → integer IDs, output format differences
- **[RenderForm](https://orshot.com/blog/renderform-api-alternative)** — `X-API-KEY` header + `data` dot notation → Bearer auth + `modifications`
- **[Abyssale](https://orshot.com/blog/abyssale-api-alternative)** — `elements` with `payload` → flat `modifications`
- **[DynaPictures](https://orshot.com/blog/dynapictures-api-alternative)** — endpoint mapping
- **[Contentdrips](https://orshot.com/blog/contentdrips-api-alternative)** — key differences

## Usage

After installation, describe what you want in natural language. Your agent will write the correct code.

**Example prompts:**

- "Generate a PNG from my Orshot template 123 with the title 'Hello World'"
- "Use the Orshot Python SDK to render a PDF from template 456"
- "Create a signed URL for my website-screenshot template that never expires"
- "Generate a 10-second MP4 video from template 789 with custom trimming"
- "List all my studio templates using the Orshot API"
- "Migrate my BannerBear API integration to Orshot"
- "Set up OAuth for my app to access Orshot workspaces"
- "Add social publishing to my render workflow — post to Twitter and LinkedIn"
- "Embed the Orshot editor in my React app with per-user templates"

## Managing the Skill

### List Installed Skills```bash
npx skills list
```### Update to Latest Version```bash
npx skills update
```### Remove the Skill```bash
npx skills remove orshot
```## Agent Skill vs MCP Server

|                      | Agent Skill                                    | [MCP Server](https://orshot.com/docs/integrations/mcp-server)     |
| -------------------- | ---------------------------------------------- | ----------------------------------------------- |
| **What it does**     | Teaches your agent Orshot API knowledge        | Gives your agent live tools to call Orshot API  |
| **How it works**     | Static instructions injected into context      | Real-time API calls via MCP protocol            |
| **API key handling** | You write the code with your key               | Agent calls API directly (key in prompt or env) |
| **Best for**         | Writing production code                        | Quick interactive prototyping                   |
| **Install**          | `npx skills add orshot-hq/orshot-agent-skills` | Add SSE URL to agent config                     |

Both can be used together for the best experience — the skill provides knowledge while the MCP server provides live tooling.