# How marketplace skills reach your AI tool

Source: https://opvs.ai/docs/guides/use-skills-in-your-ai-tool/how-it-works

> How the marketplace, your workspace and the OPVS MCP server fit together, the tools your agent uses, and what every reply looks like.

Every skill on the marketplace is a signed package. Your AI tool reaches them through **one** MCP server, `@opvs-ai/mcp`, which works in any tool that speaks MCP.

```
 market.opvs.ai (signed skills)
        │  search + read: open to everyone
        ▼
 your OPVS workspace ── install (workspace admin) ── grants permissions + credentials
        │
        ▼
 @opvs-ai/mcp (on your machine) ──▶ Claude Code · Cursor · Windsurf · Antigravity · Gemini CLI
```

## The tools your agent gets

The MCP server keeps a small set of tools always on and reaches everything else on demand, so it stays under the ~100-tool limit most AI tools enforce.

Tool

What it does

Needs an install?

`tool_search`

find skills by what you want to do (`intent`), ranked by meaning and recent use

no

`tool_read`

read a published skill's full `SKILL.md` and its reference files

no

`tool_help`

a skill's methods and their parameters

no

`tool_install`

install a package on your workspace

workspace admin

`tool_call`

call a method of an installed skill

yes

`tool_list_installed`, `tool_uninstall`, `tool_pin`

manage what is installed

—

## Two kinds of skill

- **Guidance skills** teach the agent a method (how to write a press release, clean URLs, audit a page) with references, assets and check scripts. Many marketplace skills are this kind. Your agent reads them with `tool_read`; nothing needs installing.
- **API skills** call a service (a board, a mailbox, a data provider). Install them on your workspace, then call them with `tool_call`.

## Set up once

1. Install the CLI and the MCP server (Node.js 18 or newer):

```bash
   npm install -g @opvs-ai/cli @opvs-ai/mcp
```

1. Ask for access. Your workspace admin approves it by email:

```bash
   opvs auth request -e <your-workspace-admin-email>
```

The approved token is saved in your OPVS CLI config; the MCP server reads it from there, with no extra setup.

1. Add the server to your tool. The entry is the same everywhere; only the file differs (see your tool's page):

```json
   { "mcpServers": { "opvs": { "command": "opvs-mcp" } } }
```

More options (scoped servers, the full tool list) are on [MCP server](https://opvs.ai/docs/tools/mcp-server.md).

## A typical session

```
you:   "Clean the tracking parameters out of these links."
agent: tool_search(intent="clean tracking parameters from URLs")
         → @di-atomic/url-utils (a guidance skill)
agent: tool_read(name="@di-atomic/url-utils")
         → SKILL.md + references/ + scripts/
agent: follows the skill's recipe
```

For an API skill, the agent calls `tool_help` to learn the parameters, then `tool_call(skill="@vendor/name", method="…", params={…})`.

## What every reply looks like

Every skill answers in the same shape, so your agent can use any skill without reading its docs first:

- `_guidance` sits beside the data (never wrapped around it) and tells the agent what to do next and what to avoid.
- `telemetry_signal` is one of `absent`, `cold`, `warm`, `hot`: how much the skill is used.
- `_findings` appears when audit output is requested.

Have your agent read `_guidance` before acting on the data.

## Known issue: installing skill files with the CLI (8 Nov 2026)

The skills CLI can also write a skill as native files for your tool (`opvs-skills install @vendor/name --runtime claude-code|cursor|windsurf|antigravity --dest .`), and `tool_search` results suggest that command. Today it fails for marketplace packages: the public CLI reports `no bundle recorded (manifest-only package)`. Until it is fixed, use `tool_read` to read a skill and `tool_install` + `tool_call` to use one.

## Not covered yet

There is no adapter for LangChain, LangGraph, Hermes or PicoClaw. From code, call the [Marketplace Registry](https://opvs.ai/docs/api/marketplace-registry.md) API directly.