# Skills overview

> Skills give your agent capabilities beyond answering — collect a lead, escalate to a human, search the web, or call your own API. Learn how skills become tools the model can call, and how the confirm gate keeps state-changing calls safe.

Out of the box, a Bookbag agent answers questions from your data. **Skills** let it *do things* too — capture a lead, hand a conversation to a person, look up a live order, search the web, or call any API you own. Each skill you enable becomes a tool the model can call mid-conversation, with the parameters you define.

Skills are configured per agent. The agent decides *when* to call a skill based on the conversation and the skill's description, then Bookbag executes it, captures the result, and lets the agent weave that result into its reply.

> **WHERE SKILLS LIVE:** Open an agent and expand **Skills** in the left sidebar. It has two pages: **Marketplace** — a catalog of free, ready-made skills you add in one click — and **My skills** — the skills installed on this agent, shown as cards you click into to configure, test, reset, or remove.

## How a skill becomes a tool

Every enabled skill is exposed to the model as a function-calling tool. Three fields do the work:

| Field | What it does |
| --- | --- |
| Name | The function name the model calls. Letters, numbers, and underscores only — Bookbag normalizes it for you (max 60 chars). |
| Description | Tells the model *when* to use the skill. This is the single most important field for reliable calling — be specific about the trigger. |
| Parameters schema | A JSON Schema describing the arguments the model must supply. It is the single source of truth for both validation and the tool definition. |

> **WRITE DESCRIPTIONS FOR THE MODEL, NOT THE USER:** A description like *"Look up the status of a customer's order. Use whenever a customer asks where their order is or for a tracking update."* calls far more reliably than *"Order lookup."*

## Skill types

Every skill is one of three types. You rarely set this directly — choosing a template or connector sets it for you.

| Type | Backed by | Examples |
| --- | --- | --- |
| `custom` | A built-in capability or your own HTTP endpoint | Collect leads, escalate to human, web search, custom HTTP skill |
| `integration` | A connector from the catalog | Shopify, Stripe, Zendesk, Calendly, HubSpot |
| `webhook` | A fire-and-forget HTTP call | Notify an internal system when something happens |

## The confirm gate

Every skill has an **execution mode** that controls whether it runs automatically or pauses for explicit approval first.

| Mode | Behavior | Use for |
| --- | --- | --- |
| `auto` | Runs immediately when the model calls it. | Read-only or low-risk skills: order lookup, web search, collecting a lead. |
| `confirm` | Pauses and asks for explicit confirmation before running. This is the default. | Anything that changes state: cancelling a subscription, issuing a refund, creating a ticket in another system. |

When a `confirm`-mode skill is invoked, Bookbag returns a `confirm_required` response with a one-time **token** instead of running. The skill only executes when that token is confirmed; denying it cancels the run. This gives you a safety checkpoint in front of irreversible operations.

> **DEFAULT TO CONFIRM FOR ANYTHING THAT WRITES:** New skills are created in `confirm` mode on purpose. Only switch a skill to `auto` once you're confident it is safe to run without a human in the loop.

## Adding & managing skills

Skills are managed per agent under **Skills** in the sidebar.

1. **Add from the Marketplace** — On the **Marketplace** page, click a skill. If it needs anything to run — an API key, a Slack channel, a Shopify store domain — its fields appear right there. Fill what you have (you can add it later) and click **Add to agent**.
2. **Configure it in My skills** — Open **My skills** and click the skill's card to open its detail. Change its settings, (re-)enter API keys, switch between auto and confirm, and enable or disable it.
3. **Reset to defaults** — In the detail view, **Reset** restores the skill's original settings and clears the custom config and API keys you saved for it.
4. **Delete a skill** — Removes it from the agent. You lose any settings and keys you saved on it, so you're asked to type the skill's name to confirm.
5. **Create your own** — On **My skills**, click **Create your own skill** to open a builder: name it, describe when the agent should use it, and point it at your own API (method, URL, headers, and the inputs the agent should collect).

> **KEYS STAY ENCRYPTED:** Any API key you put on a skill is encrypted at rest and never shown back — when you edit a skill, secret fields are blank and you only re-enter a key to change it. See [Credentials & security](/docs/skills/credentials).

## Testing a skill

Each skill has a **Test** button. Supply sample parameters and run it:

1. **Open the skill → Test this skill** — In My skills, click the skill card and use the **Test this skill** section — fill in sample inputs (JSON) for the parameters and run it.
2. **Auto-mode skills run immediately** — You see the raw result the agent would receive — HTTP status, parsed body, or the connector's output.
3. **Confirm-mode skills return a token** — The test returns `confirm_required` plus a token, exactly as it would in a live conversation. Confirm the token to execute, or deny it to cancel.

> **CHECK:** Every run — test or live — is logged with its inputs, output, status, and latency so you can audit what the agent did.

## Built-in skills and connectors

Bookbag ships a set of ready-to-use skills plus a connector catalog for popular tools. Start with the built-ins, then add connectors as you need them.

- **[Collect leads](/docs/skills/collect-leads)** — show a form and capture name, email, and more.
- **[Escalate to a human](/docs/skills/escalate-to-human)** — hand the conversation to your team and open a help-desk ticket.
- **[Web search](/docs/skills/web-search)** — pull in real-time information from the web.
- **[Custom skill](/docs/skills/custom-skill)** — call any API you own with full control over method, URL, headers, and body.
- **[Shopify skills](/docs/skills/shopify)** — look up orders and products from your store.

The connector catalog also includes Stripe, Zendesk, Freshdesk, Zoho Desk, Help Scout, HubSpot, Salesforce, Intercom, Slack, Google Calendar, Calendly, and Cal.com. Each connector authenticates with credentials you enter **on the skill itself** when you add it — API keys are encrypted at rest and never shown back. See [Credentials & security](/docs/skills/credentials).

## What's next

- [Collect leads](/docs/skills/collect-leads) — Capture contact details right inside the chat.
- [Escalate to a human](/docs/skills/escalate-to-human) — Route conversations that need a person to your help desk.
- [Custom skill](/docs/skills/custom-skill) — Call your own API with the confirm gate and SSRF protection.
- [Help Desk overview](/docs/help-desk/overview) — Where escalated conversations land for your team.