> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/ai-workflows/agent-skills.md).

# Agent Skills

Configure AI tools and coding assistants with official Agent Skills for Oxylabs products.

Oxylabs Agent Skills (`skills.md`) teach LLMs and AI coding assistants how to configure and interact with Oxylabs products. With a skill installed, your assistant writes accurate connection strings, request payloads, and automation code – without syntax or parameter hallucinations.

## Overview 

Oxylabs skills are published in two repositories:

<table><thead><tr><th width="188.6640625">Repositories</th><th>Products covered</th><th>Required credentials</th></tr></thead><tbody><tr><td><a href="https://github.com/oxylabs/web-api-skills">oxylabs/web-api-skills</a></td><td>Web API</td><td>Web API key</td></tr><tr><td><a href="https://github.com/oxylabs/agent-skills">oxylabs/agent-skills</a></td><td>Proxies, Agent Browser, Web Unblocker, Video Data, Web Scraper API</td><td>Product <code>USERNAME</code> and <code>PASSWORD</code></td></tr></tbody></table>

{% hint style="info" %}
**Note:** Skills teach your assistant how to write code for Oxylabs products. To let your assistant call Oxylabs products directly, see [Model Context Protocol (MCP)](/ai-workflows/mcp.md).
{% endhint %}

## Web API Agent Skills

A separate repository with skills that teach your agent to use Oxylabs Web API for live web search and page fetching.

<table><thead><tr><th width="263.734375">Skill</th><th>Covers</th></tr></thead><tbody><tr><td><code>oxylabs-web-api</code></td><td>Mechanics – the MCP tools, parameters, latency, errors, retries – plus a dependency-free CLI helper</td></tr><tr><td><code>oxylabs-web-research</code></td><td>The research method: search, pick sources, read, cite</td></tr><tr><td><code>migrate-to-oxylabs</code></td><td>Porting a codebase off Tavily, Exa, Firecrawl, Perplexity, Brave or Linkup</td></tr></tbody></table>

### Installation

```bash
npx skills add oxylabs/web-api-skills
```

Works with any skills-aware agent. Claude Code can instead take the repo as a plugin, which wires the skills and the [MCP server](/ai-workflows/mcp.md#web-api) together:

```
/plugin marketplace add oxylabs/web-api-skills
/plugin install oxylabs-web-api
```

Then `export OXYLABS_WEB_API_KEY=<key>` – in the environment, never in a config file, and from a **Web API** instance, not another Oxylabs product – start a new session, and run `/skills` to confirm all three loaded. Cloning and running `./install.sh` still works if you'd rather not use npx; the [README](https://github.com/thevastas/oxy_skills#install) has that and the manual copy.

### Skills or MCP?

They solve different halves and compose well:

| Criteria                | Skills                                                         | MCP server                       |
| ----------------------- | -------------------------------------------------------------- | -------------------------------- |
| Gives the agent         | Judgment – when to search, which sources to trust, how to cite | Typed tools it can call directly |
| Needs a running process | No                                                             | Yes                              |
| Works in                | Agents that load skill directories                             | Any MCP client                   |

Installing both is a reasonable default. The server bundles `oxylabs-web-api` and serves it as the `oxylabs://skill/web-api` resource, so connecting it alone gives an agent both halves – install the skills separately when you want them without a running server, or when you want `migrate-to-oxylabs`.

### Troubleshooting

<table><thead><tr><th width="300.53515625">Issue</th><th>Solution</th></tr></thead><tbody><tr><td><code>401</code> error with a valid-looking key</td><td>The key is almost always from a different Oxylabs product. Create a Web API instance and generate a key for it.</td></tr><tr><td><code>429</code> error with <code>QUOTA_EXCEEDED</code></td><td>Your plan's quota is used up. Retrying won't help.</td></tr><tr><td>MCP server fails with <code>Executable not found: oxylabs-web-api-mcp</code></td><td>The server isn't installed. Run <code>uv tool install git+https://github.com/oxylabs/web-api-mcp</code>.</td></tr></tbody></table>

## Oxylabs Agent Skills

One repository with skills for Proxies, Agent Browser, Web Unblocker, Video Data, and Web Scraper API. You install all of them at once, then add credentials for the products you use.

### Available skills

Use product specific skills through the `skill/` directory.

<table><thead><tr><th width="168.19140625">Skill</th><th>Description</th><th data-hidden></th></tr></thead><tbody><tr><td><a href="https://github.com/oxylabs/agent-skills/blob/main/skills/proxies/SKILL.md"><code>proxies</code></a></td><td>Generate connection strings, handle entry nodes, and apply geo-targeting, IP rotation, and session persistence.</td><td></td></tr><tr><td><a href="https://github.com/oxylabs/agent-skills/blob/main/skills/headless-browser/SKILL.md"><code>headless-browser</code></a><br>(Agent Browser)</td><td>Control remote browsers via Chrome DevTools Protocol (CDP), configure fingerprints, and manage Playwright or Puppeteer automation.</td><td></td></tr><tr><td><a href="https://github.com/oxylabs/agent-skills/blob/main/skills/web-unblocker/SKILL.md"><code>web-unblocker</code></a></td><td>Route traffic through the correct gateways, manage custom headers, toggle JavaScript rendering, and configure SSL.</td><td></td></tr><tr><td><a href="https://github.com/oxylabs/agent-skills/blob/main/skills/video-data/SKILL.md"><code>video-data</code></a></td><td>Extract video metadata, subtitles, search results, and channel data, and download video or audio via High-Bandwidth Proxies.</td><td></td></tr><tr><td><a href="https://github.com/oxylabs/agent-skills/blob/main/skills/web-scraper-api/SKILL.md"><code>web-scraper-api</code></a></td><td>Build request payloads, custom parsing parameters, and geo-targeting fields, and format JSON output for 40+ targets.</td><td></td></tr></tbody></table>

The `proxies` skill covers [Residential](https://developers.oxylabs.io/products/proxies/residential-proxies), [Mobile](https://developers.oxylabs.io/products/proxies/mobile-proxies), [ISP](https://developers.oxylabs.io/products/proxies/isp-proxies), [Dedicated ISP](https://developers.oxylabs.io/products/proxies/dedicated-isp-proxies), [Datacenter](https://developers.oxylabs.io/products/proxies/datacenter-proxies), and [Dedicated Datacenter Proxies](https://developers.oxylabs.io/products/proxies/dedicated-datacenter-proxies).

### Installation

#### Claude Code (plugin marketplace) <a href="#claude-code-plugin-marketplace" id="claude-code-plugin-marketplace"></a>

Set up Claude Code and run the following commands to install all 5 skills as a single plugin:

```bash
/plugin marketplace add oxylabs/agent-skills
/plugin install oxylabs@oxylabs-agent-skills
```

To update skills, run this command:

```bash
/plugin marketplace update oxylabs-agent-skills
```

#### Other agents (generic) <a href="#other-agents-generic" id="other-agents-generic"></a>

For other agents and custom environments, load the repository into your project workspace via the standard skills CLI:

```bash
npx skills add https://github.com/oxylabs/agent-skills.git
```

### Configuration

All skills authenticate with environment variables in a `.env` file. Add only the variables for the products you use.

<table><thead><tr><th width="167.9296875">Variable</th><th width="248">Product</th><th>Description</th></tr></thead><tbody><tr><td><p><code>OXY_RES_USERNAME</code></p><p><code>OXY_RES_PASSWORD</code></p></td><td>Residential and Mobile Proxies</td><td>Proxy user username and password</td></tr><tr><td><p><code>OXY_DC_USERNAME</code></p><p><code>OXY_DC_PASSWORD</code></p></td><td>Datacenter and ISP Proxies</td><td>Proxy user username and password</td></tr><tr><td><p><code>OXY_HB_USERNAME</code></p><p><code>OXY_HB_PASSWORD</code></p></td><td>Agent Browser</td><td>Agent Browser user username and password</td></tr><tr><td><p><code>OXYLABS_USERNAME</code></p><p><code>OXYLABS_PASSWORD</code></p></td><td>Web Unblocker</td><td>Web Unblocker user username and password</td></tr><tr><td><code>OXY_HB_ENDPOINT</code></td><td>Video Data (optional)</td><td>High-Bandwidth Proxy endpoint for video and audio downloads</td></tr><tr><td><p><code>OXY_WSA_USERNAME</code></p><p><code>OXY_WSA_PASSWORD</code></p></td><td>Video Data, Web Scraper API</td><td>Web Scraper API user username and password</td></tr></tbody></table>

{% hint style="warning" %}
**Disclaimer:** `OXY_HB_ENDPOINT` refers to High-Bandwidth Proxies, not Agent Browser. Video Data uses your Web Scraper API credentials and only needs this endpoint for media downloads.
{% endhint %}

## Which skills to use

<table><thead><tr><th width="582.09765625">Need</th><th>Use</th></tr></thead><tbody><tr><td>Bring your own HTTP client, proxy auth, IP rotation, sticky sessions, or raw geo-targeted proxy traffic</td><td><a href="/products/proxies.md">Proxies</a></td></tr><tr><td>Give your AI agent live web search and page reading, so it can research current information and cite its sources</td><td><a href="broken://spaces/BQ7Zf9paoN3FTeGcyfY1/pages/aGOzja8pC7VIOga2z73J">Web API</a></td></tr><tr><td>Click, fill forms, take screenshots, or automate with Playwright or Puppeteer</td><td><a href="/products/agent-browser.md">Agent Browser</a></td></tr><tr><td>Fetch protected pages without browser interactions</td><td><a href="/products/web-unblocker.md">Web Unblocker</a></td></tr><tr><td>Collect YouTube metadata, subtitles, search results, or channel data, or download video and audio</td><td><a href="https://developers.oxylabs.io/api-targets/video-and-social-media">Video Data</a></td></tr><tr><td>Get structured data from supported targets, search results, e-commerce pages, or parsed JSON</td><td><a href="/products/web-scraper-api.md">Web Scraper API</a></td></tr></tbody></table>

{% hint style="info" %}
**Note:** Start with the most specific product that fits the task. Test one small request first to confirm authentication and output, then scale up.
{% endhint %}

If you need help navigating Agent Skills, contact our 24/7 support team for assistance at <support@oxylabs.io>.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/ai-workflows/agent-skills.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.