# Agent Skills (/api-reference/agent-skills)



**Agent Skills** are [Claude Code](https://claude.com/claude-code) plugins that Runbear publishes so you can drive Runbear from your terminal. The headline skill, `runbear:deploy`, takes a local Claude Code project — its `CLAUDE.md`, skills, subagents, docs, and code — and deploys the whole thing to a hosted Runbear **Claude Agent SDK** agent. From there you connect the agent to Slack and chat with your project as a teammate.

This is the counterpart to the [MCP Server](./mcp-server): the MCP server lets a client *manage* your agents; the deploy skill *ships your local project into* one.

<Callout type="info" title="Requires the Runbear MCP server">
  `runbear:deploy` runs the deploy through the [Runbear MCP server](./mcp-server), so that server must be connected in your Claude Code session first. The skill uses the `create_project_upload` and `finalize_project_upload` tools; if they aren't available, connect the MCP server and try again.
</Callout>

## Install [#install]

In Claude Code, add the Runbear marketplace and install the `runbear` plugin:

```bash
/plugin marketplace add runbear-io/skills
/plugin install runbear@runbear-skills
```

This registers the `/runbear:deploy` command. You'll also need the Runbear MCP server connected — see [MCP Server → Connect](./mcp-server#connect).

On macOS, Linux, or WSL:

```bash
install_id="$(command -v uuidgen >/dev/null 2>&1 && uuidgen || cat /proc/sys/kernel/random/uuid)"
claude mcp add --transport http runbear "https://api.runbear.io/mcp?install_id=$install_id"
```

On Windows PowerShell:

```powershell
$installId = [guid]::NewGuid()
claude mcp add --transport http runbear "https://api.runbear.io/mcp?install_id=$installId"
```

<Callout type="info" title="Local tools">
  The deploy script shells out to `git`, `zip`, and `curl`, so make sure those are on your `PATH`.
</Callout>

## Deploy your project to Slack [#deploy-your-project-to-slack]

### 1. Deploy the project to a new agent [#1-deploy-the-project-to-a-new-agent]

From your project directory, create a fresh Claude Agent SDK agent and deploy to it in one step:

```bash
/runbear:deploy --new "My Project"
```

The skill creates the agent, packs and uploads your files, and finalizes the deploy. On success it reports the file count and a link to the new agent's setup page in the Runbear dashboard.

To deploy into an **existing** agent instead, pass its app UUID, agent URL, or agent name as the first argument:

```bash
/runbear:deploy <appId>
/runbear:deploy https://app.runbear.io/agents/<appId>
/runbear:deploy "My Project"
```

A name is fuzzy-matched against your agents. If more than one agent matches — or several share the same name — the skill lists the matches with their app IDs so you can pick the right one instead of guessing.

<Callout type="info" title="Agent type">
  The target must be a **Claude Agent SDK** agent (that's what `--new` creates). Other agent types are rejected with `agent_must_be_claude_agent_sdk`.
</Callout>

### 2. Connect the agent to Slack [#2-connect-the-agent-to-slack]

Once your project is in the agent's workspace, bring it to Slack. From the same Claude Code session you can ask the Runbear MCP server to do it — it exposes `get_slack_install_link`, `deploy_to_slack`, and `join_slack_channels` (see [MCP Server → Slack](./mcp-server#slack)):

```text
Deploy the "My Project" agent to our Slack workspace and join #project-team.
```

Or wire it up from the dashboard the same way you would any other agent — see [Adding Channels](../get-started/channel).

### 3. Chat with it [#3-chat-with-it]

Mention the agent in Slack. On its next activation the Agent SDK loads the files you deployed, so it runs against the same `CLAUDE.md`, skills, and code you have locally.

## Upload a large workspace [#upload-a-large-workspace]

Use the workspace upload flow for local directories that exceed the project deploy limits, such as investor diligence folders containing spreadsheets, PDFs, and supporting documents. The skill packages the selected sources into compressed tar shards, using zstd by default with gzip as a fallback, then uploads them through resumable GCS sessions. The agent-worker extracts the shards into the agent's writable workspace on the next activation.

Install the public [`runbear` plugin](https://github.com/runbear-io/skills) and run `/runbear:workspace-upload`. The skill:

1. inventories the selected local sources without following symlinks;
2. packages them into compressed tar shards and a SHA-256 manifest;
3. requests one resumable GCS upload session per shard through `create_workspace_upload`;
4. resumes and completes each direct upload;
5. calls `finalize_workspace_upload`; and
6. polls `get_workspace_upload_status` until extraction is complete.

Uploaded files are ordinary workspace files: the agent can read, edit, and delete them. With `--name <name>`, everything lands under `<name>/` in the workspace root. Without `--name`, a single source file or directory keeps its own name, while multiple sources are grouped under a generated `upload-<timestamp>/` directory.

The server accepts at most **64 shards**, **512 MiB per shard**, **20 GiB total compressed**, and **200,000 files**. It verifies archive size, SHA-256, file count, paths, and entry types before installing the upload into the workspace.

Keep the generated local shards until `get_workspace_upload_status` returns `completed`. A successful `finalize_workspace_upload` response means the job was queued, not that the files are ready.

## Options [#options]

| Argument         | Purpose                                                                                                                                                                      |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<target>`       | Deploy to an existing agent, as the first positional argument — an app UUID, agent URL, or agent name (fuzzy-matched, with an interactive picker when more than one matches) |
| `--new "<name>"` | Create a new Claude Agent SDK agent named `<name>` and deploy to it                                                                                                          |
| `--cwd <path>`   | Project folder to deploy (defaults to the current directory)                                                                                                                 |
| `--overwrite`    | Replace files that already exist in the agent workspace                                                                                                                      |

```bash
/runbear:deploy --new "My Project" --cwd ./services/api
/runbear:deploy "My Project" --cwd ./services/api --overwrite
```

## What gets deployed [#what-gets-deployed]

The skill sends the files that `git` tracks (or would track — it honors `.gitignore`), minus anything sensitive. Both the local packing step and the server re-validation block:

* **Secrets and env files** — `.env` / `.env.*`, and any file containing API keys, tokens, private keys, bearer tokens, or database URLs with real inline credentials.
* **Credential and agent config** — `.mcp.json`, `.claude/settings.json`, `.claude/settings.local.json`, `.claude.json`.
* **Build and dependency output** — `.git/`, `node_modules/`, `dist/`, `build/`, `.next/`, `.turbo/`, `coverage/`, `.venv/`, `vendor/`, `__pycache__/`, and similar.

A deploy is capped at **500 files**, **25 MiB** decompressed, and a **50 MiB** archive. If your project is larger, deploy a focused subset with `--cwd`.

<Callout type="warn" title="Never paste secrets into chat">
  The skill deliberately leaves secrets out of the upload, and you should never paste credentials into the conversation. When an integration needs a secret, set it up in the dashboard at `https://app.runbear.io/agents/<agentId>/integrations`, where credentials are stored in the vault and masked.
</Callout>

## Related [#related]

* [MCP Server](./mcp-server) — manage your Runbear agents from any MCP client
* [Adding Channels](../get-started/channel) — connect an agent to Slack, Discord, and more
* [Team Agent overview](../team-agent/overview) — what a hosted agent is and how it works