> ## Documentation Index
> Fetch the complete documentation index at: https://agents.concierca.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Skill list, read, create, edit, link, and archive.

A **skill** packages reusable capability for agents: a prompt block (injected prose), documentation, tags, a category and optional underlying tool requirements. Skills are either **tenant-owned** (editable) or **platform skills** (read-only, provided by Concierca AI).

***

## `skill_list`

List skills available in this tenant (plus platform skills). Optional name/description search.

| Name     | Type   | Required | Description                    |
| -------- | ------ | -------- | ------------------------------ |
| `search` | string | no       | Name/description term          |
| `limit`  | number | no       | Max rows (default 50, max 200) |

**Returns:** `{ skills: [...], count }`. Each row: `id, slug, name, description, category, category_id, scope, skill_type, tags, requires_credentials, is_system, tenant_id, created_at, updated_at` (no prompt block / docs). Archived skills are excluded.

**Permissions:** read.

```json theme={null}
{ "method": "tools/call", "params": { "name": "skill_list", "arguments": { "search": "report" } } }
```

## `skill_get`

One skill with docs, prompt block and tool requirements.

| Name | Type   | Required | Description            |
| ---- | ------ | -------- | ---------------------- |
| `id` | string | yes      | Skill **uuid or slug** |

**Returns:** `{ skill }` — the full record: all list columns plus `docs_markdown, prompt_block, body, tools_required, default_tools, underlying_tools, parameter_schema, load_mode_default`. Not found → `{ error: "Skill not found" }`.

**Permissions:** read.

```json theme={null}
{ "method": "tools/call", "params": { "name": "skill_get", "arguments": { "id": "lead-scoring" } } }
```

## `skill_create`

Create a **new** tenant-owned skill — the counterpart to `skill_save` (which only edits). Scope is intra-tenant (`department` | `global`); platform skills cannot be created here. The slug is auto-derived from the name when omitted (and de-duplicated).

| Name            | Type      | Required             | Description                                                            |
| --------------- | --------- | -------------------- | ---------------------------------------------------------------------- |
| `name`          | string    | yes                  | Skill name                                                             |
| `slug`          | string    | no                   | Auto-derived from name when omitted                                    |
| `description`   | string    | no                   | Short description                                                      |
| `prompt_block`  | string    | no                   | The injected skill prose                                               |
| `docs_markdown` | string    | no                   | Documentation                                                          |
| `tags`          | string\[] | no                   | Tags                                                                   |
| `category`      | string    | no                   | Must be a listed skill category (see `category_list {entity:"skill"}`) |
| `scope`         | string    | no                   | `department` \| `global`                                               |
| `department_id` | string    | for department scope | Department uuid                                                        |
| `dry_run`       | boolean   | no                   | Validate without writing                                               |

**Returns:** `{ status:"created", skill_id, slug, note, audit }` — `slug` is the resolved (de-duplicated) slug. `dry_run:true` → `{ dry_run:true, valid:true, would: {action:"create_skill", slug, scope, name}, note }`.

**Permissions:** write; **Company-Admin only**.

```json theme={null}
{ "method": "tools/call", "params": { "name": "skill_create", "arguments": {
  "name": "Lead scoring",
  "prompt_block": "Score each lead 0–100 on fit and intent ...",
  "scope": "global"
} } }
```

## `skill_save`

Edit a tenant-owned skill: name, description, prompt\_block, docs\_markdown, body, tags, category. The pre-edit state is snapshotted (revertible). Platform skills are read-only.

| Name                                                           | Type      | Required | Description        |
| -------------------------------------------------------------- | --------- | -------- | ------------------ |
| `id`                                                           | string    | yes      | Skill uuid or slug |
| `name`, `description`, `prompt_block`, `docs_markdown`, `body` | string    | no       | Content fields     |
| `tags`                                                         | string\[] | no       | Tags               |
| `category`                                                     | string    | no       | Category           |

**Returns:** `{ status:"saved", skill_id, updated, note, audit }` — `updated` lists the patched field names. Editing a platform skill → `{ error: "Skill not found (platform skills are read-only via MCP)" }`.

**Permissions:** write; **Company-Admin only**.

```json theme={null}
{ "method": "tools/call", "params": { "name": "skill_save", "arguments": {
  "id": "lead-scoring", "prompt_block": "Score each lead 0–100 on fit, intent and budget ..."
} } }
```

## `skill_link`

Link **one** skill to an agent (additive) — the per-link counterpart to `agent_update.skills`, which replaces the whole set.

`load_mode` semantics: `inject`/`preload` = the skill text is inlined into the agent's prompt on every run; `discover` (default) = listed only, the agent loads it on demand (progressive disclosure). Duplicate links are rejected.

Grant authority follows the skill's scope: a global skill's underlying tools may be conferred by a Superadmin, a department skill's by a Company-/Department-Admin, a user skill's by its owner or a Company-Admin.

| Name        | Type   | Required | Description                                              |
| ----------- | ------ | -------- | -------------------------------------------------------- |
| `agent_id`  | string | yes      | Agent uuid (use `agent_list`)                            |
| `skill_id`  | string | yes      | Skill uuid or slug (use `skill_list`)                    |
| `load_mode` | string | no       | `inject` \| `preload` \| `discover` (default `discover`) |

**Returns:** `{ ok:true, link, skill, conferred_tools, note?, audit }`. `link` is the new `agent_skills` row (`{id, skill_id, load_mode, created_at}`); `skill` is `{id, slug, name}`; `conferred_tools` lists any underlying tools granted to the agent by the link. A duplicate link → `{ error: "Skill already assigned to this agent" }`.

**Permissions:** write; grant authority per skill scope as above.

```json theme={null}
{ "method": "tools/call", "params": { "name": "skill_link", "arguments": {
  "agent_id": "<agent-uuid>", "skill_id": "lead-scoring", "load_mode": "preload"
} } }
```

## `skill_archive`

Archive a tenant-owned skill (soft + reversible) — hides it from `skill_list` without deleting; pass `unarchive:true` to restore. Platform skills and system skills are rejected. Use when a skill is mis-configured but still linked to agents (a hard delete would conflict).

| Name        | Type    | Required | Description               |
| ----------- | ------- | -------- | ------------------------- |
| `id`        | string  | yes      | Skill uuid or slug        |
| `unarchive` | boolean | no       | Restore an archived skill |

**Returns:** `{ status:"archived"|"unarchived", id, archived_at, note, audit }`. Platform skills (`tenant_id IS NULL`) and system skills are rejected with `{ error }`.

**Permissions:** write; **Company-Admin only**.

```json theme={null}
{ "method": "tools/call", "params": { "name": "skill_archive", "arguments": { "id": "lead-scoring" } } }
```