> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cobalt.peoplereign.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Skillsets & skills

> Author custom capabilities for what an integration can't do out of the box.

# Skillsets & skills

Skillsets are the **exception path**. When an [Integration](/integrations/overview)
already connects the system you need, use it. Reach for a Skillset only when no
integration covers the job — a bespoke internal API, an unusual workflow — and
you need to teach the agent how to do it yourself.

## The three pieces

| Piece                      | What it is                                                                                                                                                                    |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Skillset**               | A self-contained domain — a small chapter of related capability (for example "PTO Lookup"). It owns Skills and its configurations, and carries a [sensitivity](#sensitivity). |
| **Skill**                  | A single playbook within a Skillset — the instructions for one job, written in plain language (and optionally shell or `curl`).                                               |
| **Skillset configuration** | The credentials a Skillset's Skills need (a URL, an API key), supplied once and injected at run time. Secrets never live inside Skill text.                                   |

## A Skillset

A Skillset has a **name**, a short **description** that tells the agent when to
reach for this domain, and a **sensitivity**. It groups the Skills and
configurations for one area of work.

## A Skill

Each Skill has:

* **Name** — short and action-oriented (for example "Check PTO Balance").
* **Description** — the trigger: when to *use* this Skill and when to *skip* it.
  The agent reads this to decide whether the Skill applies.
* **Content** — the body: plain-language instructions for doing the job, which
  can include shell commands or `curl` calls. It references credentials by
  variable name (never inline).
* **Requires confirmation** — set this for anything that writes or changes data,
  so the agent confirms with the user before acting. Leave it off for read-only
  lookups.

## A configuration and how credentials are injected

Add a configuration to a Skillset to hold its named **variables** — for example
`URL` and `API_KEY`. Mark secret values as secret; they're encrypted at rest and
never shown back in the console or exposed to the model.

At run time, each variable is injected as an environment variable named
**`<CONFIGURATION_NAME>_<KEY>`**, upper-snake-cased. So a configuration named
`PTO API` with a key `API_KEY` becomes:

```
$PTO_API_API_KEY
```

Reference it in Skill content with `$PTO_API_API_KEY` or `${PTO_API_API_KEY}`.
The agent never sees the secret value — only the variable name — and Cobalt
scrubs injected values out of anything the model emits.

## A worked example

A Skillset **PTO Lookup** with a configuration **PTO API** (`URL`, `API_KEY`) and
a Skill **Check PTO Balance**:

* **Description:** *Use when the user asks how much PTO or vacation they have
  left. Skip for requests to book or cancel time off.*
* **Requires confirmation:** off (read-only).
* **Content:**

````
Look up the user's remaining PTO balance.

Call the PTO service for the resolved user and return their remaining balance
in days. Use:

```bash
curl -s "$PTO_API_URL/balance?user=$USER_EMAIL" \
  -H "Authorization: Bearer $PTO_API_API_KEY"
```

Report the number of days plainly. If the call fails, say you couldn't reach
the PTO system and offer to hand off to a human.
````

## Sensitivity

A Skillset is `standard` (the default) or `elevated`. Set `elevated` when the
work touches PHI, compensation, credentials, or security operations. Elevated
work is routed only to models covered by a Business Associate Agreement, gets
tighter PII handling and shorter retention, and stores its memory under a
separate key. Don't mark work `elevated` unless it needs it — it's slower and
more constrained by design. See [sensitivity](/reference/glossary#sensitivity)
in the glossary.

## Keep Skills small

One Skill, one job. A focused Skill with a clear "use when / skip when"
description is easier for the agent to route to than a sprawling one that tries
to do everything. Split big jobs into several Skills under the same Skillset.